Config Reconciler

Config Reconciler

Config Reconciler helps modpack authors update configuration defaults while preserving independent player changes. Separate downloads are available for Fabric, Forge, and NeoForge.

It compares the previous pack default, the player's current configuration, and the incoming pack default. Independent changes are combined. Same-key conflicts keep the player's value by default and are recorded for review.

Features include conservative key-level merging for JSON objects, Java .properties, and a subset of TOML; backups; text/JSON reports; and a dry-run mode. Unsupported divergent files keep the player copy. The mod performs no network access or telemetry.

Installation and supported versions

Install one JAR matching your loader in mods/. Fabric API is not required. Fabric Loader 0.16.14 or newer is required for the Fabric file.

• Fabric: 1.18.2, 1.19.2, 1.19.4, 1.20.1, 1.20.4, 1.20.6, 1.21.1, 1.21.4, 1.21.5, 1.21.8, 1.21.10, 1.21.11, 26.1.2, 26.2.
• Forge: 1.18.2, 1.19.2, 1.19.4, 1.20.1, 1.20.4.
• NeoForge: 1.20.6, 1.21.1, 1.21.4, 1.21.5, 1.21.8, 1.21.10, 1.21.11, 26.1.2, 26.2.

Use the Java version required by the game: Java 17 for the selected older versions, Java 21 for 1.20.6–1.21.11, and Java 25 for 26.x. Other patches, snapshots, 1.12.2, 1.16.5, and Quilt are not advertised in this release.

Important setup rule

Place defaults in config/config_reconciler/defaults/ using paths relative to config/. For example, config/config_reconciler/defaults/example.json manages config/example.json.

Do not also ship a managed target through normal launcher overrides. The launcher would overwrite the player's copy before Minecraft starts. Ship that file only under config/config_reconciler/defaults/ and let Config Reconciler update its target.

Installing the mod alone has no effect until a modpack supplies managed defaults. When migrating an existing pack, first ship its current defaults: differing existing targets are adopted on the first run. In later pack releases, update the defaults and optionally config/config_reconciler/pack-version.txt.

Settings are generated in config/config_reconciler/reconciler.json. Set dryRun to true to preview updates. The default conflict policy is KEEP_USER; KEEP_INCOMING is also available. Reports are in .config-reconciler/reports/latest.txt and latest.json.

Alpha limitations

• Dedicated-server bootstrap and two-launch merge checks do not cover full gameplay or client GUI behavior. Test a pack update on a copy first.
• Manages config/, not options.txt or per-world serverconfig/.
• JSON arrays are atomic values.
• TOML arrays of tables and multiline strings are not merged when both sides differ. This is not a complete TOML parser.
• Divergent files above the merge-size limit remain unchanged, without large backup triplets.
• No in-game conflict editor, popup, or automatic restore. Restore manually from backups with the game closed.
• Writes are atomic per file, not a transaction across all configurations.
• Conflicts are reported during the update that detects them; historical reports remain available after later runs.
• Restart is recommended after files change because another early-loading mod may already have cached them.
• Reports and backups can contain secrets from configuration files; review before sharing.

License and credits

MIT License. Runtime loader/library APIs are acknowledged in META-INF/THIRD_PARTY_NOTICES.md; their implementations and Minecraft game files are not included in our JARs. Source code is supplied separately.

Developed with AI assistance. The avatar is an AI-generated symbolic illustration of configuration merging, not an in-game screenshot or a representation of new game items. This is an independent community project, not an official Mojang, Microsoft, or CurseForge product.