Configuration for Modpacks

For players and pack authors who want to change defaults and ship them with a pack: where configs live, how overrides resolve, and how template JSON is written.

Config Directory Layout

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

Override Rules

• Compat configs resolve in three layers with priority user > mods > default; files with the same mod_id override wholesale by layer.
• In-game edits are copy-on-write: packaged and community files stay read-only and your changes land in compat/user/. Reset Config restores a mod to its packaged or applied community default.
• A compat file only activates when its target mod_id (and any declared dependencies) are actually loaded; configs for absent mods are skipped cleanly.

Compat config details — which layer to edit, how to edit it, and how to roll back — live in Editing configs by hand; how the adaptation tools relate is on Mod Compatibility.

Shipping Defaults with a Pack

1. Tune the bindings in-game until you are happy, then take the matching file from config/controlflex/profiles/.
2. For an optional layout, package it as a custom template at config/controlflex/templates/<name>.json — it appears in the in-game template switcher.
3. Put the relevant files from config/controlflex/ into your pack's overrides (e.g. overrides/config/controlflex/ on CurseForge / Modrinth packs). Player edits still go to profiles/ and compat/user/ and are preserved.

Template JSON Format

A template maps “action → button|mode” per layer. This is the structure of the built-in Basic template (excerpt):

{
  "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
  }
}

Button tokens (ButtonId)

Mode tokens (TriggerMode)

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

Chords join buttons with +; the mode follows |. A binding string reads button1+button2|MODE.

Radial Menu Config

Radial layouts persist in config/controlflex/radial_menu/radial_menus.json with icons alongside them; the in-game editor is easier, and shipping this file in a pack carries the menus along.

Upgrades & Migration

Upgrading from 0.8.6.x to 0.8.7+ migrates profiles, compat files, and client settings on first launch, copying originals to config/controlflex/backup/. When a pack bumps the mod version, players' profiles/ and compat/user/ are preserved.