Mod Adaptation
Control Flex is built for modpacks: most mods work out of the box. When one sits on the wrong layer or its screen misbehaves, the adaptation chain solves it in escalating steps — in-game center → community repo → compat JSON → bridge mod.
Step One: Auto-Discovery
At startup Control Flex scans Minecraft's KeyMapping registry and registers every non-vanilla binding as a bindable action, then reconciles again when you open settings — so nothing gets missed. Library mods (the Fabric API and Kotlin language-support families) are exempted and never clutter the lists.
Step Two: The In-Game Center
Open Control Flex Settings → Mod Adaptation: every installed mod is listed with name, icon, and version. Each mod has three tabs:
- Key Bindings: the mod's discovered actions, assigned to layers (Main / Screen / Overlay) and bound straight to gamepad buttons.
- Screen Adaptation: stick mode, layer mapping, and cursor rules while that mod's GUI is open.
- Overlay Adaptation: the same, for interactive HUDs (spell wheels, photo HUDs, and similar).
Adding a rule: open the target GUI or HUD once in-game so Control Flex records it, then use + Add Screen/Overlay Adaptation in the mod's page and pick it from the recent-pages list (up to 50). Entries that could not be matched to a mod can be scanned automatically.
Stick Behavior: Three Choices
| Behavior | What it does | Default for |
|---|---|---|
| Independent | Stick directions act as actions bound on Layer Mapping | Both sticks on Overlay; the right stick on Screen |
| Radial Path | Stick traces a path or angle — spell wheels and ring menus | Assigned manually |
| Virtual Mouse | Stick moves a cursor inside that UI | The left stick on Screen |
With no rule: Screen uses Virtual Mouse on the left stick and Independent on the right; Overlay keeps both sticks Independent. Cursor style offers system / Bedrock / hand; Virtual Mouse has a speed setting, and Radial Path has threshold, radius, angle bias, and whether the last angle is restored.
Step Three: The Community Repo
The official community source is ControlFlexMC/cfx-compat-configs. From Mod Adaptation: Sync Configs → browse variants → preview Bindings / Screen / Overlay → Apply (existing user files are backed up first). Extra sources can be added, and local JSON can be imported or exported from a mod's page.
Where Your Edits Go
All edits are copy-on-write: packaged and community files stay read-only and your changes land in config/controlflex/compat/user/. A mod's Reset Config restores its packaged or applied community default. Packaged rules sit behind every mod — the JAR ships three (JEI, Epic Fight, Nightfall), and each only activates when its target mod is actually loaded.
Step Four: If It Still Misbehaves
- Check Key Mapping — is the action on the right layer?
- Add a Screen/Overlay rule, or apply a community config.
- Physical keys only → Virtual KBM.
- Bypasses KeyMapping entirely → hand-write or share compat JSON, or write a bridge mod.
For compat JSON fields, layer priority, and pack distribution, see Mod Compatibility; for bridge-mod development, see Bridge Mods.