模组适配

Control Flex 为整合包而生：大多数模组开箱即用；当某个模组不在正确的位置、或界面里的摇杆行为不对时，用模组适配中心逐级解决 —— 游戏内中心 → 社区配置库 → compat JSON → 桥接模组。

第一层：自动发现

启动时扫描 Minecraft 的 KeyMapping 注册表，把每个非原版绑定注册为可绑定动作；打开设置时还会再对齐一次（reconcile），因此游戏中途换的模组也不会漏。库类模组（Fabric API、Kotlin 语言支持等家族）会被自动豁免，不混进列表。

第二层：游戏内适配中心

打开 Control Flex 设置 → 模组适配：每个已安装模组按名称、图标与版本列出。进入某个模组有三个页签：

按键绑定：该模组被发现的全部动作，分配层级（Main / Screen / Overlay）并直接绑手柄按键。
界面适配：该模组的 GUI 打开时的摇杆模式、层级映射与光标规则。
叠层适配：同样的事，针对交互式 HUD（法术轮盘、拍照 HUD 等）。

添加一条界面 / 叠层规则：先在游戏中把目标界面打开一次让 Control Flex 记录它，然后在模组详情里点 + 添加界面/叠层适配，从“最近页面”（最多 50 条）里选中即可。偶尔遇到无法归属到模组的条目，可以自动扫描。

摇杆行为：三选一

行为	说明	默认出现在
Independent	摇杆方向当作动作，在层级映射里绑定	Overlay 双摇杆；Screen 右摇杆
Radial Path	摇杆描出路径 / 角度 —— 法术轮盘、圆环菜单类界面	需手动指定
Virtual Mouse	摇杆在该界面内移动光标	Screen 左摇杆

没有规则时：Screen 层左摇杆为虚拟鼠标、右摇杆为 Independent；Overlay 层两杆都保持 Independent。光标样式可选系统 / 基岩 / 手型；Virtual Mouse 可调光标速度，Radial Path 可调阈值、半径、角度偏置与是否记忆上次角度。

第三层：社区配置库

官方社区源是 ControlFlexMC/cfx-compat-configs。在模组适配里点 Sync Configs → 浏览变体 → 预览按键 / 界面 / 叠层 → Apply；应用前会先备份已有的用户文件。也支持添加自定义远程源，或在模组详情页导入 / 导出本地 JSON。

你的修改存在哪里

所有编辑都是写时复制：内置与社区文件保持只读，你的改动落到 config/controlflex/compat/user/。某个模组的 Reset Config 会把该模组恢复为内置或已应用的社区默认。内置配置藏在每个模组的规则背后 —— 模组 JAR 自带 JEI、Epic Fight、Nightfall 三份，且只在目标模组实际加载时生效。

第四层：仍然不行怎么办

检查按键映射 —— 这个动作绑在正确的层了吗？
为它添加界面 / 叠层规则，或应用社区配置。
只认物理键 → 虚拟键鼠。
完全绕开 KeyMapping → 手写 / 分享 compat JSON，或写一个桥接模组。

compat JSON 的字段、分层优先级与整合包分发方式，见模组兼容性；桥接模组开发见桥接模组。