How to JSON

How to JSON explains the rules every DragonMineZ data file follows. You don't need to know Java to configure DragonMineZ, but your files have to be valid JSON, and DragonMineZ upgrades its files between versions in ways you should know about before you start editing.

Ground rules

Standard JSON. No trailing commas; keys and strings go in double quotes. The config parser tolerates // comments and skips keys that start with _, $ or // without a warning, but DragonMineZ drops them whenever it rewrites a file (a version upgrade, /dmzconfig or the in-game config editor). Keep long notes outside the file.
UTF-8 encoding. Config is read and written as UTF-8 (ConfigLoader.java). Don't save files as UTF-16, or with a byte order mark (BOM) that your editor might add silently.
Use a real editor. VS Code, Notepad++ or IntelliJ catch bracket and quote mismatches before they reach the server. Notepad works, but it won't warn you about syntax errors.
Validate before you deploy. A single misplaced comma makes the whole file fail to parse. Paste the file into any JSON validator (or use your editor's built-in linter) before restarting or reloading a live server.

When DragonMineZ can't read your file

DragonMineZ never overwrites a file it can't read. If a config file has a syntax error:

DragonMineZ logs <file> has malformed JSON; using defaults this session and leaving your file untouched, with the line, column and path of the error.
For that session the game runs on the built-in default values of that file. Your file stays exactly as you left it.
Fix the syntax and run /dmzreload (or restart) to apply your values.

The same applies to the other JSON files DragonMineZ loads: a malformed custom form, raid, tournament, quest, saga, side quest or wish file is skipped (not regenerated) and reported.

The JSON load report

Configured in: General Server Configdeveloper.reportJsonProblemsInChat

All these problems are collected in one report. With developer.reportJsonProblemsInChat enabled in general-server.json (the default), every player sees a short summary in chat on login: the files that failed ([!]) and the default files that were upgraded automatically ([~]). The report also flags unknown keys, usually a typo such as "tpGainMultipler": the key is ignored and the rest of the file still loads. The server log has the full details.

Config versions and automatic upgrades

Every config file (general-server.json, combat.json, a race's character.json and stats.json, forms, entities.json, raids, tournaments and so on) carries a configVersion string in X.Y.Z form, for example "2.2.0". Do not edit it by hand. DragonMineZ compares it with the mod's own config version every time it loads the file:

Current version: the file is loaded as it is.
Older or missing version: DragonMineZ upgrades the file. Any value that isn't in X.Y.Z form, such as the old numeric 21.0, counts as outdated.

An upgrade goes through these steps:

The old file is moved to config/dragonminez/oldBackup/<same relative path> (for example oldBackup/races/saiyan/forms/superforms.json).
A fresh file is generated from the new defaults.
Your old values are merged back in with a three-way merge against the defaults of the previous release, which ship inside the mod jar (data/dragonminez/previousConfigs/):
- a value you never changed (it still equals the previous release's default) takes the new default, so balance changes reach you;
- a value you changed is kept;
- keys added in the new version are added with their default, and entries you added to maps (for example extra entity ids) are kept;
- if there is no previous-release copy of a file (custom races, newly added files), every value that differs from the new default is kept.
The log shows Regenerating <file>. Reason: Outdated version (...) and how many of your values were preserved.

Values the merge can't carry over (for example a value of the wrong type, such as a string where a number is expected) fall back to the default. After an update, compare the new file with its copy in oldBackup/ if something looks off.

Leave configVersion alone Changing configVersion by hand either forces an unwanted upgrade or makes DragonMineZ treat an outdated file as current, so new keys and balance fixes are not merged in.

Custom and user-defined files

Custom races (any folder under config/dragonminez/races/ that isn't a default race) go through the same version check: their character.json and stats.json are upgraded with the merge above, keeping every value you set. DragonMineZ never generates default forms for them.
Custom form files (form groups that aren't DragonMineZ defaults, in races/<race>/forms/ or forms/) keep their content: when their version is outdated, a copy is moved to oldBackup/ and the file is saved again with the current version.
Extra raid and tournament files you add are loaded as they are.
Custom quests, sagas and side quests you create in the world save are never modified. Only the default files DragonMineZ generated are upgraded (see below).
Files whose name starts with old_ in the forms, raids and tournaments folders are ignored, so you can park a file there without it being loaded.

Quest files and defaultsVersion

Configured in: General Server Configgameplay.autoUpdateQuests

Default quest, saga and side quest files in <world>/dragonminez/ carry a "defaultsVersion" field instead of configVersion. When a new DragonMineZ version ships changed defaults and autoUpdateQuests is on, DragonMineZ runs a similar three-way merge on them (against data/dragonminez/previousQuests/ in the jar). If both you and the new version changed the same field, your value is kept and the conflict is listed in <world>/dragonminez/quest_update_report.txt. Before changing a file, DragonMineZ copies it to <world>/dragonminez/oldBackup/. See Custom Quests for how the merge treats each field, and Reloading and Updating Changes for how upgrades are reported.

Common mistakes

Not renaming raceName, groupName or other id-like fields consistently between the folder name and the JSON content. DragonMineZ keys many lookups off both.
Copying a form or race file and forgetting to change its internal identifiers, so one entry silently overrides another.
Editing a file while the server is running and expecting it to apply live. See Reloading and Updating Changes for what needs a reload and what needs a restart.
Editing the copy in oldBackup/ thinking it's still active. It isn't: DragonMineZ never reads it back.
Typos in key names. The key is ignored (and reported), so your value never applies.

Checking a field against the code

The modding pages of this wiki name the Java class behind each file (for example RaceCharacterConfig.java, FormConfig.java or GeneralServerConfig.java in com.dragonminez.common.config). When in doubt about a field name or type, that class is the ground truth: the wiki describes it, but the code defines it. The easiest reference is a freshly generated file: start a test instance, then copy the file DragonMineZ writes.