配置文件格式
基本信息
| 属性 | 值 |
|---|---|
| 目录 | <.minecraft>/config/CustomMainMenu/（ConfigurationLoader.java:32） |
| 默认文件名 | mainmenu.json |
| 格式 | JSON（Gson JsonParser） |
| 随包模板 | /assets/custommainmenu/mainmenu_default.json |
| 编辑器 schema | 仓库根目录 mainmenu.schema.json |
加载规则
ConfigurationLoader.load()（ConfigurationLoader.java:29-81）：
- 目录不存在就
mkdir()。 mainmenu.json不存在时，从 jar 内/assets/custommainmenu/mainmenu_default.json复制一份出来。- 遍历目录下所有以
.json结尾的文件（含mainmenu.json自身），文件名去扩展名后作为界面名（GuiConfig.name），逐个GuiConfig.load()+config.addGui()。
⚠️ 遍历顺序是 File.listFiles() 的未定义顺序，不是字典序。多界面 + synced 依赖时有顺序敏感问题（见背景（Background））。
界面名 → 缩放后缀
文件名后缀直接决定 GUI 缩放档位（GuiConfig.java:57-71），后缀被剥离后作为界面名：
| 文件名 | 界面名 | guiScale |
|---|---|---|
mainmenu_small.json |
mainmenu |
1 |
mainmenu_normal.json |
mainmenu |
2 |
mainmenu_large.json |
mainmenu |
3 |
mainmenu_auto.json |
mainmenu |
0 |
mainmenu.json |
mainmenu |
-1（标准） |
详见 GUI 缩放变体。
顶层结构
| 键 | 类型 | 必填 | 对应加载器 |
|---|---|---|---|
images |
对象 | 是 | GuiConfig.loadImages（:209） |
buttons |
对象 | 是 | GuiConfig.loadButtons（:229） |
texts |
对象 | 是 | GuiConfig.loadTexts（:219） |
other |
对象 | 是 | GuiConfig.loadOthers（:112） |
version |
int | 否 | ⚠️ 代码从不读取，纯装饰 |
⚠️ 四个键都是 get(...).getAsJsonObject() 无判空硬读（GuiConfig.java:210 / :220 / :230 / :115）。缺任意一个 → NullPointerException → 被 ConfigurationLoader 抛出 → CustomMainMenu.preInit 记录 “Will have to crash here :(” 后 throw new RuntimeException（CustomMainMenu.java:54-57），游戏直接崩在启动期。要写自定义界面就得把这四段都写全（可以给空对象 {}）。
⚠️ texts vs labels：仓库自带 mainmenu.schema.json:591 把文本段命名为 labels，但代码只认 texts（GuiConfig.java:220），随包模板也用 texts。以代码为准。
other 段
| 子键 | 类型 | 元素 |
|---|---|---|
splash-text |
对象 | 飘字（SplashText） |
panorama |
对象 | 全景图（Panorama） |
background |
对象 | 背景（Background） |
alignments |
对象 | 自定义锚点，见 锚点系统 |
⚠️ alignments 在顶层而非 other 段——loadAlignments 读 jsonObject.has("alignments")（GuiConfig.java:98）。schema 把它放在 other 里是错的。
数组即随机
getStringPlease（GuiConfig.java:368-379）对任何 JSON 数组字段随机取一个元素：
| 输入 | 结果 |
|---|---|
"a" |
"a" |
["a","b"] |
加载时随机取 "a" 或 "b" |
| 数组为空 | rng.nextInt(0) → IllegalArgumentException |
| 对象 | 记 ERROR 日志，返回字面量 "ERROR" |
⚠️ 每次调用都 new Random()（:369），且这是加载期一次性行为——所以数组是"每次重载/每次启动随机固定一个"，不是每次渲染都变。飘字另有自己的逐行随机（见 飘字（SplashText））。
失败行为
配置加载没有 try/catch 兜底：ConfigurationLoader 把异常原样抛回（ConfigurationLoader.java:65-73），由 CustomMainMenu.preInit 转成 RuntimeException。运行期重载才带回滚（见 重载与错误处理）。