FuzzyBot: Updating to match new version of source page

2026-10-13T05:22:49Z

Updating to match new version of source page

New page

'''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 <code>//</code> comments and skips keys that start with <code>_</code>, <code>$</code> or <code>//</code> without a warning, but DragonMineZ drops them whenever it rewrites a file (a version upgrade, <code>/dmzconfig</code> or the in-game config editor). Keep long notes outside the file.
* '''UTF-8 encoding.''' Config is read and written as UTF-8 (<code>ConfigLoader.java</code>). 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 <code><file> has malformed JSON; using defaults this session and leaving your file untouched</code>, 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 <code>/dmzreload</code> (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 ===
{{Config|General Server Config|developer.reportJsonProblemsInChat}}
All these problems are collected in one report. With <code>developer.reportJsonProblemsInChat</code> enabled in <code>general-server.json</code> (the default), every player sees a short summary in chat on login: the files that failed (<code>[!]</code>) and the default files that were upgraded automatically (<code>[~]</code>). The report also flags '''unknown keys''', usually a typo such as <code>"tpGainMultipler"</code>: 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 (<code>general-server.json</code>, <code>combat.json</code>, a race's <code>character.json</code> and <code>stats.json</code>, forms, <code>entities.json</code>, raids, tournaments and so on) carries a <code>configVersion</code> string in <code>X.Y.Z</code> form, for example <code>"2.2.0"</code>. '''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 <code>X.Y.Z</code> form, such as the old numeric <code>21.0</code>, counts as outdated.
An upgrade goes through these steps:
# The old file is '''moved''' to <code>config/dragonminez/oldBackup/<same relative path></code> (for example <code>oldBackup/races/saiyan/forms/superforms.json</code>).
# 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 (<code>data/dragonminez/previousConfigs/</code>):
#* 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 <code>Regenerating <file>. Reason: Outdated version (...)</code> 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 <code>oldBackup/</code> if something looks off.

{{Note|type=warning|title=Leave configVersion alone|text=Changing <code>configVersion</code> 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 <code>config/dragonminez/races/</code> that isn't a default race) go through the same version check: their <code>character.json</code> and <code>stats.json</code> 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 <code>races/<race>/forms/</code> or <code>forms/</code>) keep their content: when their version is outdated, a copy is moved to <code>oldBackup/</code> 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 <code>old_</code> in the forms, raids and tournaments folders are ignored, so you can park a file there without it being loaded.

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

== Common mistakes ==
* Not renaming <code>raceName</code>, <code>groupName</code> 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 [[Special:MyLanguage/Reloading and Updating Changes|Reloading and Updating Changes]] for what needs a reload and what needs a restart.
* Editing the copy in <code>oldBackup/</code> 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 <code>RaceCharacterConfig.java</code>, <code>FormConfig.java</code> or <code>GeneralServerConfig.java</code> in <code>com.dragonminez.common.config</code>). 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.

{{Navbox Modding}}

How to JSON/en - Revision history

FuzzyBot: Updating to match new version of source page