兼容配置（compat JSON）

compat JSON 是整套适配体系的可分享载体：游戏内界面写出来的是它，社区配置库分发的是它，桥接模组安装的也是它。这一页从「文件放哪」讲到「字段怎么写」，再到「怎么贡献一份、怎么自建一个配置源」。

本页内容： 文件与生效规则 · 内置配置 · 社区配置库 · 字段说明 · 贡献配置 · 自建配置源 · 排障

一、文件放在哪，什么情况下才会生效

• 三个目录：compat/default/（从 JAR 释放，只读）、compat/mods/（桥接模组安装，只读）、compat/user/（你的改动，优先级最高）。
• 身份来自 JSON 里的 mod_id，不是文件名；但 user/ 层的文件必须叫 <mod_id>.json，游戏内界面与热重载都按这个名字找文件。
• 三个门槛全过才会加载：目标 mod_id 已安装、dependencies 里每个 mod 都已加载、mod_versions 里有一条匹配当前模组版本。任一不满足，整份文件跳过（日志会区分「模组未加载」和「依赖未加载」）。
• 以点开头的文件（如 .applied.json）不会被当成配置解析。
• 旧格式 {modid}_keys.json 会在启动时自动迁移：原文件备份改名，字段转换到新格式。

二、内置了什么

JAR 内只带三份配置，每次启动释放到 config/controlflex/compat/default/：

同目录下的 exempt_mods.json 不是兼容配置，它声明「库类模组」名单，让 Fabric API、Kotlin 语言支持这类库不进入适配列表。其余模组靠自动发现或社区配置库补充。

三、社区配置库

官方源是 ControlFlexMC/cfx-compat-configs：一棵纯静态目录树，按 MC 版本与加载器分目录，每个模组一份 JSON，外加一份 manifest.json 记录路径与 sha256。

<repo-root>/                   # this directory's URL is the baseUrl players add
├── 1.20.1/                   # MC version dir (must match the game version name exactly)
│   ├── forge/
│   │   ├── manifest.json
│   │   └── mods/
│   │       ├── jei.json
│   │       └── epicfight.json
│   └── fabric/
│       ├── manifest.json
│       └── mods/
│           └── jei.json
└── 1.21.1/
    └── neoforge/

客户端只会请求两种 URL：{baseUrl}/{mcVersion}/{loader}/manifest.json 与 manifest 里 path 指向的内容文件。只读当前加载器目录，某个版本 / 加载器没做就是 404 —— 这是正常情况，不算失败，也不影响其他源。

游戏内路径：设置 → 模组适配 → 右上「更多」→ 同步最新配置。模组详情页会出现「找到 N 个社区适配配置」横幅 → 选变体 → 只读预览 → 应用。应用会先备份旧的 user 文件、原子覆盖、写入 .applied.json，再热重载该模组，无需重启。

同一个 mod_id 但内容不同 = 并行变体，由玩家挑选；同一个 sha256 出现在多个源 = 互为镜像，按源列表顺序回退重试。内容按 sha256 缓存到 compat/repo/content/<mod_id>/<sha256>.json，文件不可变。

官方源是怎么钉版本的

• 内置两个源，指向同一个 ref：cdn.jsdelivr.net/gh/ControlFlexMC/cfx-compat-configs@<ref> 与 raw.githubusercontent.com/ControlFlexMC/cfx-compat-configs/refs/heads/<ref>。前者快、后者稳，互为镜像。
• <ref> 是一个版本 tag，跟着 ControlFlex 的发版走（本版是 0.8.8），不是 main —— 所以老版本玩家同步到的永远是那套格式能吃的配置，不会被上游新格式搞坏。
• 仓库里为此保留了一条版本线一支分支 / tag：0.8.4、0.8.5、0.8.7、0.8.8…。你要给某个旧版本补配置，就切到对应分支，别往 main 上放旧格式文件。
• 两个内置源可以禁用、可以调序，但不能删除；「恢复默认源」只重置它们。自己加的源随便增删。

仓库里现在覆盖了什么

按「MC 版本 / 加载器」分目录，目前已收录 12 个模组的配置。同一份配置通常会复制到适用的每个加载器目录，所以不同版本线的覆盖并不一致：

这张表会随仓库变，以目录树为准；create / emi 的配置还通过 dependencies 要求对应桥接模组已安装 —— 它们的键位是桥接提供的。

四、字段说明

顶层字段

dependencies 的实际用法

它不是「自动装依赖」，而是一道激活闸门：数组里每个 mod_id 都已加载，这份配置才生效。真实配置里主要用在两种场景 —— 配置依赖某个桥接模组提供的键位，或者这份配置本身就属于一个独立兼容 mod。

{
  "mod_id": "emi",
  "dependencies": [
    { "mod_id": "cfx_compat_emi", "mod_name": "Control Flex x EMI",
      "home_pages": ["https://www.curseforge.com/minecraft/mc-mods/cfx-x-emi"] }
  ],
  "mod_versions": [ { "version": "", "screenKeys": { "key.emi.view_recipes": {} } } ]
}

只读 mod_id（大小写不敏感），mod_name / home_pages 只在社区配置预览页展示。写成字符串数组或非数组会被整段忽略。目标模组就是自己的配置不需要它。

mod_versions 与版本匹配

数组按顺序求值，首个匹配生效；如果没有任何一条匹配当前模组版本，整份配置不生效（日志会给警告）。

• 比较按点分段做数值比较：缺的段补 0，非数字前缀会被剥掉（v1.0 → 1.0，0-beta → 0）。
• 区间写坏（缺括号 / 逗号、边界无法解析、下界大于上界）→ 整条 entry 被丢弃，不只是这个字段。
• 把具体的区间放前面，最后用一条 "" 通配兜底。

三个按键分区与派发通道

三个分区都是「裸键名 → 每键设置」的对象。裸键名 = KeyMapping.getName() 去掉 modid: 前缀；内部动作 ID 仍是 {modid}:{keyName}。一个键出现在多个分区就是多分区的成员（并集）；一个都没写的键默认只在游戏内生效。

"inGameKeys": {
  "channels": ["keyMapping"],
  "key.epicfight.dodge": {},
  "key.epicfight.attack": { "channels": ["keyMapping", "eventBus"],
                            "extraBehaviors": ["suppressLayerSwitch"] }
}

分区没写 channels 时的默认值：

• 模组触发两次（两条路径都在监听）→ 只留 keyMapping。
• 模组只听 Forge 事件 → ["eventBus"]。
• 按住打开的菜单自己轮询 GLFW → 加 glfwPoll。

extraBehaviors

每键行为开关，目前只有一个取值：suppressLayerSwitch —— 该动作的绑定被按住期间，压制层级切换动作；保存时这个绑定会被强制成 HOLD 模式。用于模组自带的「修饰键式」按键（例如 Iron's Spells 的 key.irons_spellbooks.spell_bar_modifier）。显式写 [] 表示明确关闭。

phasePersistentKeys

声明某个键的绑定要跨相位切换保持一致：

"inGameKeys":  { "key.irons_spellbooks.spell_wheel": {} },
"overlayKeys": { "key.irons_spellbooks.spell_wheel": {} },
"phasePersistentKeys": { "key.irons_spellbooks.spell_wheel": ["inGame", "overlay"] }

• 只允许 ["inGame", "overlay"] 与 ["inGame", "screen"] 两种配对，源必须是 inGame，目标恰好一个。
• 必须同时在两个分区里声明这个键，只写配对不算数（会警告并忽略）——靠并集隐式获得成员资格也不行。
• 运行时目标层的绑定是被软锁定的，值从游戏层实时派生（不落盘复制）：按住不放的按钮跨过切换仍然按住，界面 / 叠层弹出时不会把菜单「抖」关掉。
• 这类动作的绑定会被物化为 HOLD，并且跳过物品抑制。在绑定界面里编辑目标层会写入一份快照绑定并解锁；重置该键可恢复锁定与派生。

ignoreKeys

把动作从绑定界面里藏掉（调试键、作弊键、重复键）："ignoreKeys": ["key.epicfight.config"]。匹配动作 ID 时会自动补 modid: 前缀。

itemSuppressKeys

主手物品匹配时压制指定动作。典型场景：模组对特定物品接管了输入（战斗模式下普攻 / 交互由模组的连招与武器技能系统处理），把通用动作压掉避免打架。

"itemSuppressKeys": [
  { "item": "efn:yamato_dmc*", "playerState": ["epicfight:battle_mode"], "suppressActions": ["use"] },
  { "tag": "minecraft:swords", "playerState": ["epicfight:battle_mode"], "suppressActions": ["attack", "use"] }
]

每 tick 对主手物品求值一次；被 phasePersistentKeys 命中的动作豁免。

tips

绑定行上的提示文案：

"tips": [
  { "key": "key.epicfight.weapon_innate_skill",
    "text": { "en_us": "Bind to the same button as Attack; use HOLD mode.",
              "zh_cn": "请绑定为与「攻击」相同的按键，并使用 HOLD 模式。" } }
]

语言码没有白名单，运行时按玩家语言取，回落 en_us；连 en_us 都没有就不显示。至少写 en_us。

界面与叠层的摇杆、光标

键是全限定类名：界面用 screen.getClass().getName()；叠层用「打开者」类名，"*" 表示该模组的兜底。

"screen": {
  "com.dragonminez.client.gui.UtilityMenuScreen": {
    "leftStick":  { "behavior": "VIRTUAL_MOUSE" },
    "rightStick": { "behavior": "RADIAL_PATH", "threshold": 0.5, "cursorRadius": 90 }
  }
},
"overlay": {
  "io.redspace.ironsspellbooks.gui.overlays.SpellWheelOverlay": {
    "rightStick": { "behavior": "RADIAL_PATH", "threshold": 0.3, "cursorRadius": 40, "showCursor": false }
  }
}

条目还支持 cursorStyle（system / bedrock / hand）与 disabled: true（完全退出，不再回退）。解析顺序：user 层优先于内置，具体叠层条目优先于同模组的 "*"，命中但缺所需那一侧（左 / 右）就继续往下一个配置找。

从旧格式迁移（≤ 0.8.5）

0.8.7 起启动时会自动迁移旧文件（先备份再改字段）。如果你在手工维护配置，或者要读一份老配置，对照这张表：

写完先自查这几条

1. 三个分区必须是对象，写成数组会被整段丢弃（只留一条警告）。
2. 分区里的 channels 是保留键（分区默认值），不要拿它当键名。
3. 每键的 channels: [] 与 extraBehaviors: [] 是有意义的显式空，不等于省略。
4. mod_versions 首个匹配生效：具体区间放前面，"" 兜底放最后；没有一条匹配 = 整份配置不生效。
5. 写坏的 version 会丢掉整条 entry，不只是这个字段。
6. 身份来自 JSON 里的 mod_id，但 user 层文件名必须叫 <mod_id>.json。
7. phasePersistentKeys 必须两边都声明才生效；只写配对会被忽略。
8. UTF-8、无 trailing comma；只有默认行为不对时才去加 channels 覆盖。

最小模板

{
  "mod_id": "examplemod",
  "contributors": ["yourname"],
  "config_version": "1.0.0",
  "mod_versions": [
    {
      "version": "",
      "inGameKeys": {},
      "screenKeys": {},
      "overlayKeys": {},
      "ignoreKeys": [],
      "tips": [],
      "screen": {},
      "overlay": {}
    }
  ]
}

五、如何贡献一份配置

1. Fork 仓库，并切到匹配分支。配置格式随 ControlFlex 版本变化，源是按分支消费的；只 fork 到默认分支时要先把对应版本分支拉下来。
2. 新建 <mc-version>/<loader>/mods/<mod_id>.json。键名用模组 Controls 分类里的裸键名（不带 modid: 前缀），找不到就开日志里的 [ModCompat] 行。
3. 重新生成 manifest：python3 generate_manifest.py。改了内容不重算 sha256，是玩家侧「内容下载失败」的头号原因。
4. 游戏内验证。把你的 fork 当源加进源列表，或直接把文件丢进 compat/user/ 重启。加载是否成功看 [ModCompat] 日志。
5. 提 PR，写清测试过的模组版本、加载器，以及这份配置修好了什么。

只影响某个加载器就只放那个目录；两边行为一致就复制一份进另一个目录。文件大小上限 2 MB（实际配置通常只有几 KB）。

六、如何添加其他配置源

一个「源」就是一棵静态 HTTP 目录树：{baseUrl}/{mcVersion}/{loader}/manifest.json 加内容文件。没有服务端逻辑，任何静态托管都能当源。

两条路线

• Fork 官方仓库（推荐）：目录布局、manifest 生成器、一批能用的配置都现成，只加自己的配置就行。代价是要跟上游同步。
• 从零搭一棵：自控发布节奏、放私有或实验性配置，按下面的规范建目录即可。

manifest.json 关键字段

{
  "schemaVersion": 1,
  "name": "My Pack Configs",
  "items": [
    {
      "mod_id": "jei",
      "mod_name": "Just Enough Items (JEI)",
      "path": "mods/jei.json",
      "sha256": "a4dcfadbca3d0a8b19be2ec5d191fc12801d199583393ef0fec13007e06b927f",
      "home_pages": ["https://www.curseforge.com/minecraft/mc-mods/jei"]
    }
  ]
}

官方仓库的 generate_manifest.py 可以照搬到自己的源：扫描 <mc-version>/<loader>/mods/*.json，抽出 mod_id / mod_name / home_page，算 sha256，幂等写回 manifest。

托管选择与硬性限制

在游戏里添加源

1. 进 设置 → 模组适配 → 右上「更多」→ 编辑源列表。
2. 把 baseUrl 粘到下方输入框 → 添加 → 完成；列表有变化时关闭对话框会触发一次后台同步。
3. 打开「同步最新配置」，确认你这个源同步成功（有分源进度与日志）；之后模组卡片会出现社区配置角标。

源列表行为：内置源可以禁用 / 调序但不能删除；你自己的源可增删调序；「恢复默认源」只重置那两个内置源。每个源缓存在 compat/repo/manifest/<source-id>/，id 由 URL 派生（小写，冲突时加 -1 / -2）。

本地测试

cd <your-source-root>
python3 -m http.server 8000
# then add http://127.0.0.1:8000 in "Edit source list"

允许 http:// 源（只拒绝 https → http 的重定向降级），本地测试不需要证书。改完文件点一次「同步最新配置」即可。

七、排障