CFXControl Flex Wiki
English中文

Editing compat configs by hand

Everything you can tune in game lives in the UI, but sometimes you need a text editor: bulk changes, copying a snippet from someone else's config, repairing a stale one. This page covers which layer to edit, how to do it, and how to undo it.

1. Work out which layer you are editing

Directory Written by What happens to your edit
compat/default/ Extracted from the JAR Overwritten on mod upgrade — do not edit this one
compat/mods/ Installed by bridge mods Overwritten when the bridge updates; also read-only
compat/user/ The in-game UI, Apply, or you Highest priority, never overwritten (Apply backs it up first)

Overriding is a whole-file replacement, not a field merge: for a given mod_id, a user file replaces both mods/ and default/ entirely. So when you copy a snippet, copy the whole mod_versions block with it.

2. Option one: the in-game editor (recommended)

  1. Go to Settings → Mod Adaptation, pick the mod, switch to Key Bindings / Screen Adaptation / Overlay Adaptation.
  2. Save — changes are written to compat/user/<mod_id>.json and that mod is hot-reloaded immediately, no restart.
  3. If you break something, hit Reset Config: the mod returns to its built-in or applied community default (equivalent to deleting the user file).

Rule editing is always copy-on-write: built-in and community files stay read-only and the UI only writes to the user layer. That is why you can never break a built-in config.

3. Option two: edit user/<mod_id>.json directly

  1. Copy compat/default/<mod_id>.json, or an applied community file — do not start from scratch, it is easy to miss fields.
  2. Rename it <mod_id>.json and drop it into config/controlflex/compat/user/. The name has to match; both the UI and hot-reload look it up by that name.
  3. Change only the fields you care about; delete whole entries for keys you do not need. This file applies as a whole, not as a patch.
  4. Save as UTF-8, and watch out for trailing commas.
  5. Restart the game to apply. There is no watcher on disk files; only Apply and the in-game editor hot-reload.

Broken JSON will not crash the game: the whole file is skipped and a parse error is logged. So check the log after editing instead of blaming the controller.

4. Option three: take a file straight from a source

You do not have to press Sync in game: find <mc-version>/<loader>/mods/<mod_id>.json in cfx-compat-configs, download it into compat/user/ and restart. Handy for pre-seeding a pack or for machines with no network.

This does not write .applied.json, so the in-game variant list will not show it as applied — but the config itself works normally.

5. Traps when hand-editing

Trap What to know
mod_versions order First match wins; a broad interval placed early swallows every later version. Always put the "" wildcard last.
Interval syntax Malformed (missing bracket / comma, lower > upper) → the whole entry is discarded, not just that field.
Sections must be objects The old array form is dropped wholesale, with a warning.
channels inside a section It is a reserved key meaning "default channels for this section", never a key name.
channels: [] An explicit empty array is meaningful: this key dispatches nothing — quite different from omitting the field.
phasePersistentKeys The key must be declared in both sections; the pairing alone is ignored (and warned about).
mod_id It must be an installed mod's ID; if the mod is epicfight, writing epic_fight means it never activates.
Encoding UTF-8, no trailing commas; on Windows, make sure Notepad does not save UTF-16 — tips turn into mojibake immediately.

6. Rolling back

After a rollback, glance at the log to confirm which file is now in effect — especially if you had the same config in several layers.

7. Shipping the change in a modpack

Put compat/user/*.json together with profiles/ into the pack's overrides (on CurseForge / Modrinth, overrides/config/controlflex/). Player changes still land in the user layer and win over your preset files; but remember whole-file semantics — as soon as a player edits the same mod_id, your preset no longer participates.

After a mod update, mod_versions may no longer match and the config goes quietly inert. Before releasing, run the new mod version and confirm in the log that the config actually loaded.

Modpack configuration

Templates, profiles, button tokens and shipping defaults with a pack.

See pack configuration →

Field reference

Confirm field meanings and allowed values before editing.

Look up fields →

In-game mod adaptation

Layering, screen / overlay rules and applying community configs in the UI.

See the UI walkthrough →