配置文件与整合包

面向想改默认配置、并让它随整合包一起分发的玩家与包作者：配置放在哪、覆盖规则是什么、模板 JSON 怎么写。

配置目录结构

config/controlflex/
├── templates/          # template JSON (built-in + custom)
├── profiles/           # per-template user modifications
├── compat/             # mod compatibility configs
│   ├── default/        # packaged (extracted from the JAR, read-only)
│   ├── mods/           # installed by bridge mods (read-only)
│   └── user/           # your edits (highest priority)
├── guides/             # guide assets, same default/mods/user layering
├── radial_menu/        # radial menu layouts and icons
├── backup/             # automatic backups from migrations
└── cfx-client.json     # global client state

覆盖规则

• 兼容配置分三层，优先级 user > mods > default；同 mod_id 的文件按层整体覆盖。
• 游戏内编辑是“写时复制”：内置与社区文件保持只读，你的改动落到 compat/user/。Reset Config 会把某个模组恢复为内置或已应用的社区默认。
• 兼容文件只在目标 mod_id（及其声明的 dependencies）实际加载时生效，未安装的模组配置会被干净跳过。

兼容配置的细节（改哪一层、怎么改、怎么回退）见手动修改配置；各种适配手段之间的关系见模组兼容。

作为整合包分发默认配置

1. 先在游戏里调出你满意的键位，然后从 config/controlflex/profiles/ 取对应文件。
2. 想做成“可选布局”时，把它整理成一个自定义模板放进 config/controlflex/templates/<name>.json —— 它会出现在游戏内的模板切换列表中。
3. 把 config/controlflex/ 下的相应文件放进整合包的 overrides（如 CurseForge / Modrinth 包的 overrides/config/controlflex/）。玩家的个人改动仍然写进 profiles/ 与 compat/user/，不会丢失。

模板 JSON 格式

模板把“动作 → 按键|模式”按层组织起来。以下是内置 Basic 模板的结构（节选）：

{
  "templateMeta": {
    "name": "basic",
    "displayName": "Basic",
    "description": "Basic controller bindings for Minecraft Java Edition",
    "version": 4
  },
  "mainActionBindings": {
    "layer_shift1": "leftBumper|HOLD",
    "jump": "buttonA|HOLD",
    "sneak": "rightStickClick|HOLD",
    "toggle_sneak": "rightStickClick|DOUBLE_TOGGLE",
    "attack": "rightTrigger|HOLD",
    "drop_stack": "rightStickClick+dpadDown|PRESS",
    "sys_pause": "buttonStart|LONG_PRESS",
    "controlflex:key.controlflex.open_settings": "buttonBack+buttonStart|PRESS"
  },
  "shift1ActionBindings": { "controlflex:key.controlflex.open_radial_menu_2": "buttonBack|HOLD" },
  "shift2ActionBindings": {},
  "shift3ActionBindings": {},
  "shift4ActionBindings": {},
  "guiActionBindings": {
    "inv_select": "buttonA|PRESS",
    "inv_quick_move": "buttonY|TAP",
    "mouse_wheel_up": "rightStickUp|HOLD"
  },
  "overlayActionBindings": {
    "gui_back": "buttonB|PRESS"
  },
  "virtualKbmBindings": {
    "key.keyboard.left.shift": { "guiLayer": { "binding": "leftTrigger", "enabled": true } }
  },
  "thresholds": {
    "tapThresholdMs": 500,
    "longPressThresholdMs": 1000
  }
}

按键 token（ButtonId）

模式 token（TriggerMode）

PRESS · RELEASE · HOLD · TAP · LONG_PRESS · TOGGLE · DOUBLE_PRESS · DOUBLE_TAP · DOUBLE_HOLD · DOUBLE_TOGGLE

组合键把按键用 + 连接；模式跟在 | 之后。键位字符串按 button1+button2|MODE 的形式书写。

径向菜单配置

径向菜单布局保存在 config/controlflex/radial_menu/radial_menus.json，图标资源放在同目录下；游戏内编辑器更直观，配置库分发时直接带上这个文件即可。

版本升级与迁移

从 0.8.6.x 升级到 0.8.7+ 时，配置档案、兼容文件与客户端设置会在首次启动自动迁移，原文件复制到 config/controlflex/backup/。整合包更新模组版本时，玩家的 profiles/ 与 compat/user/ 会被保留。