背景（Background）

基本信息

属性 值
源码类 lumien.custommainmenu.configuration.elements.Background（继承 Element）
配置位置 顶层 other → background（GuiConfig.loadOthers，GuiConfig.java:174-206）
绘制入口 GuiCustom.drawScreen，在全景图之后、普通元素之前（GuiCustom.java:207-226）
默认模式 FILL（Background.java:16）

mainmenu.schema.json 的 background 描述里明确写了「cannot have both a background image and a panorama at the same time」——代码层面两者都会画，panorama 先画、background 后画（不透明），所以同开时背景图会把全景图完全盖住，等于无效。

可配置项

字段 必填 默认值 说明
image 是 — 背景贴图（静态）
mode 否 fill 缩放/定位模式，见下表
slideshow 否 — 轮播对象；与 image 并存（轮播分支优先）

⚠️ image 在 GuiConfig.java:177 被无条件 get（backgroundObject.get("image") 不判 has）。若只写 slideshow 而不写 image，这里会抛 UnsupportedOperationException/NPE。源码因此没有像 Image 那样提供"二选一"的分支。

四种 mode

setMode 用 MODE.valueOf(newMode.toUpperCase(Locale.US)) 解析（Background.java:20-22），写错大小写以外的枚举名会抛 IllegalArgumentException 导致配置加载失败（进而被 ConfigurationLoader 抛出、整个 mod 崩在 preInit）。

mode 枚举 行为 实现
fill FILL 等比放大铺满全屏，允许裁掉溢出部分，不产生黑边；先按 factorWidth/factorHeight 中较大者算缩放 GuiCustom.java:296-306
stretch STRETCH 直接拉伸到 width×height，不保持宽高比 GuiCustom.java:307-310
center CENTER 原始像素尺寸居中，不缩放 GuiCustom.java:311-318
tile TILE 按 ceil(w/imgW) × ceil(h/imgH) 平铺 GuiCustom.java:319-328

贴图原始尺寸用 GL11.glGetTexLevelParameteri 从当前绑定纹理现场读取（GuiCustom.java:289-290）。

轮播背景

slideshow 子对象可含 images（字符串数组）、displayDuration、fadeDuration、shuffle、synced（GuiConfig.java:181-205）：

  • 设了 shuffle: true 则调 Slideshow.shuffle() 打乱数组。
  • 设了 synced: true 时不建自己的轮播，而是直接引用主菜单的同一个对象：CustomMainMenu.INSTANCE.config.getGUI("mainmenu").guiConfig.background.slideShow（GuiConfig.java:184-186）。
  • ⚠️ 已知崩溃路径：加载顺序是 GuiConfig.load() 先跑完、ConfigurationLoader 才 config.addGui()（ConfigurationLoader.java:64 与 :79）。若在 mainmenu.json 自身的 background 里写 "synced": true，此时 mainmenu 尚未入表，Config.getGUI("mainmenu") → this.guis.get(name) 返回 null（Config.java:29）→ 紧接着 .guiConfig 空指针崩溃。

相关条目