Der technische Teil ist auf Englisch – so, wie er im Wiki steht. Unterstrichene Begriffe haben eine Erklärung auf Deutsch.

🇬🇧 English · 🇩🇪 Deutsch

Mod format: writing a mod.json by hand

This page describes the mod.json that WolfSDK Loader and WolfSDK Studio 0.2.0 read, field by field, as modloader/wolfsdk/mod.py checks it. The examples are real files from the mods in the 0.2.0 packages. To make a mod without writing JSON, use the WolfSDK Studio. Which decls and paths exist: Modding Guide.

Keywords: mod format, mod.json, manifest, mod file format, write a mod by hand, Mod-Format, Mod von Hand schreiben

How do I write a mod by hand?

Make a folder in the mods folder next to WolfSDK.cmd, e.g. mods\my_mod (Open folder on the Mods page opens it).
Put a mod.json into it (fields below). Files it points to go into the same folder, e.g. mods\my_mod\decls\x.decl.
On the Mods page click Reload, tick the mod, then Check (or Check mod set on the Overview page).
Apply mods, Start game.

A skeleton from the command line, in the extracted folder:

python\python.exe -m wolfsdk new-mod my.mod --name "My Mod"

It writes mods\my_mod\mod.json with one example set. The loader reads every folder in mods with a mod.json; a broken one is listed with ! under Checks & messages.

Keywords: write a mod, create a mod, new mod, first mod, mod folder, new-mod, Reload, Mod schreiben, Mod erstellen, eigene Mod, wie schreibe ich eine Mod

All mod.json fields at a glance

Field	Required	Default	Meaning
`id`	yes	–	unique id, e.g. `example.big_magazine`
`name`	yes	–	name on the Mods page
`version`	no	`"0.0.0"`	shown on the Mods page
`author`	no	`""`	who made it
`description`	no	`""`	what it does and what was tested
`priority`	no	`100`	whole number; lower is applied first, higher wins
`spiel`	no	`"tno"`	the game: `"tno"` or `"tnc"`
`assets`	no	`{}`	the changes, keyed `type:name`, each with `set` and/or `file`
`cvars`	no	`{}`	cvars sent when the game starts

Other keys are ignored. The Studio adds "studio": {"version": 1} to the mods it writes.

Keywords: mod.json fields, all fields, keys, schema, reference, id, name, version, author, description, priority, spiel, assets, cvars, Felder, Aufbau

mod.json fields id and name

id and name are the only required fields; both must be non-empty text.

id identifies the mod. The loader remembers ticked mods by their id, so keep it stable between versions. Two mods with the same id: the second one is skipped with "Duplicate mod id". The shipped mods use dotted ids such as example.big_magazine, wolfsdk.tnc_photo_mode or studio.sandbox_tools.
name is what the Mods page shows.

version, author and description are optional text. The Mods page shows name, version, priority and the number of assets.

Keywords: id, name, mod id, mod name, required fields, Duplicate mod id, version, author, description, Pflichtfelder, Mod-Name

mod.json field spiel: which game a mod is for

spiel is "tno" (The New Order) or "tnc" (The New Colossus). Without it, a mod is a The New Order mod. Any other value is an error ("'spiel' must be 'tno' or 'tnc'").

The two games share neither asset names nor archive format. The loader only shows and applies the mods of the game selected at the top right.

Watch out: the apps read spiel, not game. A mod.json with only "game": "tnc" counts as a The New Order mod and does not appear for The New Colossus. The SDK packages use game (see the comparison below).

Keywords: spiel, game, tno, tnc, which game, New Order, New Colossus, mod not showing, mod does not appear, Spiel wählen, welches Spiel

mod.json field priority: load order and conflicts

priority is a whole number, default 100. Mods are applied in order of priority, then id, lowest first. Each mod works on the result of the one before.

Two mods change different values of the same decl: both work.
Two mods set the same value: the higher priority wins, and a conflict is reported.
Two mods replace the same asset with file: the higher priority wins, reported as a conflict.
Two mods write the same texture (image or texdb asset): refused before anything is written ("They can't be used together - please tick only one of them").

Conflicts do not block an apply; they are listed under Checks & messages.

Keywords: priority, load order, order, conflict, conflicts, two mods, override, overwrite, highest wins, Priorität, Reihenfolge, Konflikt

mod.json field assets: which game assets a mod changes

assets is an object. Each key names one asset as type:name, split at the first colon, e.g. weapon:weapon/handgun_base, material:models/weapons/handgun/handgun_hg or cfile:snapdemo.cfg. Each value is an object with set, file or both.

Rules the loader checks:

A key without a colon is an error ("asset key must look like 'type:name'").
An entry with neither set nor file is an error.
The asset must exist in the selected game ("asset does not exist in the game").
Retail names are lower case. Spell one asset the same way in every mod; two spellings are refused ("the same asset is spelled differently").

"assets": {} is allowed, for a mod that only sets cvars.

Keywords: assets, asset key, type:name, asset name, asset id, decl, weapon, material, cfile, Asset-Schlüssel, Asset-Name

Asset change set: edit single values in a decl

set maps dotted paths inside a decl to new values. Only these values change; comments, indentation and everything else in the decl stay as they are.

"damage:damage/tungsten/mg60": {
  "set": {
    "edit.damageParms.minDamage": 22.0,
    "edit.damageParms.maxDamage": 30.0
  }
}

A path must already exist in the decl, otherwise "unknown path(s)". set cannot add new fields; use file for that.
true/false are written as true/false. Numbers are written as given: 30.0 stays 30.0, 30 stays 30.
Text is quoted automatically when the original value was quoted. Block values such as virtualmapping need their braces: "{ 0.015625, 0.015625, 0.000000, 0.062500 }".
A number given as text ("0.00") is written exactly like that.

Keywords: set, dotted path, edit value, change value, decl path, unknown path, number format, Wert ändern, Pfad

Asset change file: replace a whole asset

file is a path relative to the mod folder. Its bytes replace the asset completely. From the shipped mod cheats_gamemode:

"gamemodesp:gamemode/campaign": { "file": "assets/gamemodesp__gamemode_campaign.decl" }

The path must stay inside the mod folder ("points outside the mod folder"), and the file must exist ("file is missing").
With set and file on one asset, the file comes first and the set values are applied on top.
The bytes are written as they are. The New Colossus cfile entries (encrypted configs such as snapdemo.cfg) must be stored encrypted for their own name: let the Studio's text replacement save them. A plain text file does not work there.
Prefer set: a file mod conflicts with every other mod on that asset.

Keywords: file, replace asset, full replacement, whole file, cfile, encrypted, relative path, Datei ersetzen, ganze Datei

mod.json field cvars: settings sent at game start

cvars maps cvar names to one value each (text, number or true/false; lists and objects are refused). They are sent every time the game starts with Start game or Spielen.cmd, and they win over the same cvar on Cheats & QoL.

The New Order: start arguments; cheat cvars also as +toggle, so the startup cheat reset does not wipe them.
The New Colossus: cvars the retail console accepts go as start arguments, the rest into the game's default.cfg; Revert removes them. Names that are not The New Colossus cvars are skipped. If another ticked mod replaces cfile:default.cfg, those cvars are left out, with a message.

Write values as text ("1"): the loader turns every value into text, and true would become True.

Keywords: cvars, cvar, console variables, settings, start arguments, default.cfg, +toggle, launch options, Startparameter, Einstellungen

Example: the smallest mod (Big Pistol Magazine)

The shipped mod example_big_magazine for The New Order, complete:

{
  "id": "example.big_magazine",
  "name": "Big Pistol Magazine (Example)",
  "version": "1.0.0",
  "author": "wolfsdk",
  "description": "Raises the pistol magazine from 20 to 66. ...",
  "priority": 100,
  "assets": {
    "weapon:weapon/handgun_base": {
      "set": { "edit.validAmmoClips.item[0].clipSize": 66 }
    }
  }
}

No spiel, so it is a The New Order mod. One set on one path; the rest of the weapon decl stays untouched.

Keywords: example, mod.json example, template, sample mod, smallest mod, big magazine, clipSize, Beispiel, Vorlage

Example: a value mod for The New Colossus (Invulnerable)

From the shipped mod tnc_erste (2 of its 7 assets shown):

{
  "id": "wolfsdk.tnc_erste",
  "name": "Invulnerable (TNC)",
  "version": "1.0.0",
  "priority": 100,
  "spiel": "tnc",
  "assets": {
    "table:playerdamage/normal": { "set": { "min": "0.0", "max": "0.0" } },
    "table:playerdamage/hard":   { "set": { "min": "0.00", "max": "0.00" } }
  }
}

"spiel": "tnc" makes it a The New Colossus mod. The values are text so that each keeps exactly the length of the original value.

Keywords: example, The New Colossus mod, TNC mod, spiel tnc, invulnerable, playerdamage, table, Beispiel, TNC

The shipped mod tnc_hidden_options changes no asset at all (description shortened):

{
  "id": "wolfsdk.tnc_hidden_options",
  "name": "Hidden Menu Options",
  "version": "1.0.0",
  "author": "wolfsdk",
  "description": "Turns on menu options the retail game hides: ...",
  "priority": 100,
  "spiel": "tnc",
  "cvars": {
    "menu_showOptionForDevMenu": "1",
    "menu_showOptionForSASMenu": "1",
    "menu_allowMeinLeben": "1",
    "g_setting_photomode": "1"
  },
  "assets": {}
}

The console refuses these developer cvars, so the loader writes them into default.cfg. Not yet confirmed in game.

Keywords: example, cvars only, cvar mod, menu options, Hidden Menu Options, default.cfg, Beispiel, Cvar-Mod

Example: a mod that replaces whole files (Photo Mode)

The shipped mod tnc_photo_mode (description shortened):

{
  "id": "wolfsdk.tnc_photo_mode",
  "name": "Photo Mode",
  "version": "1.0.0",
  "author": "wolfsdk",
  "description": "One key freezes the game for screenshots: ...",
  "priority": 100,
  "spiel": "tnc",
  "assets": {
    "cfile:default_snap.cfg": { "file": "assets/default_snap_cfg.bin" }
  }
}

assets/default_snap_cfg.bin is the encrypted form of the unused SnapMap config default_snap.cfg. In the game: bind F8 "resourceExec default_snap.cfg -s". Not yet confirmed in game.

Keywords: example, file replacement, cfile, Photo Mode, resourceExec, bin file, Beispiel, Datei ersetzen

How do I find asset names and editable paths?

With the command line in the extracted folder (add --title tnc for The New Colossus):

python\python.exe -m wolfsdk --title tnc list --type weapon --grep pistol
python\python.exe -m wolfsdk --title tnc cat weapon:<name>
python\python.exe -m wolfsdk --title tnc paths weapon:<name>

list shows asset names, cat prints an asset, paths lists the dotted paths that set can change, with their current values. types lists the asset types. In the WolfSDK Studio you can browse textures and texts and replace them directly. Paths of weapons, skins and enemies with examples: Modding Guide.

Keywords: find asset, asset names, paths, list, cat, types, command line, CLI, decl paths, Asset finden, Pfade finden, Kommandozeile

How do I check a mod before applying it?

In the loader: Check on the Mods page or Check mod set on the Overview page.
On the command line: python\python.exe -m wolfsdk check

The check builds every change in memory and checks asset names, decl paths, conflicts and the planned writes. It writes nothing. Results and errors appear under Checks & messages.

Applying starts from the original files every time and writes the whole ticked set, so a failed apply leaves the game original: when an apply fails, the previously applied mods are reverted and the loader says so.

Keywords: check mod, validate mod.json, dry run, test mod, Check, Check mod set, wolfsdk check, Mod prüfen, testen

mod.json errors when the loader reads a mod

These appear with ! under Checks & messages after Reload; the mod is not listed:

invalid JSON (...): a comma, quote or brace is wrong.
field 'id' is missing / field 'name' is missing, or must be a non-empty string.
'spiel' must be 'tno' or 'tnc'.
'priority' must be a whole number.
'assets' must be an object, asset key must look like 'type:name', ... has neither 'file' nor 'set', ... .set must be an object.
... .file points outside the mod folder.
'cvars' must be an object, cvar '...' needs a single value (text, number or true/false).
Duplicate mod id.

Keywords: mod.json error, invalid JSON, field missing, error message, broken mod, mod not loading, Fehlermeldung, Fehler in mod.json

mod.json errors when checking or applying

These come from Check, Check mod set or Apply mods:

asset does not exist in the game (...): wrong name, or the mod is for the other game (spiel).
unknown path(s): ...: the set path is not in this decl. It may sit in the parent decl (inherit); paths shows what exists.
file is missing: ...: the file is not in the mod folder.
... change the same textures ... please tick only one of them: two texture mods for the same asset.
the same asset is spelled differently: write the asset key the same way in every mod.
Not enough disk space: free space on the game's drive and apply again.

Keywords: apply error, check error, asset does not exist, unknown path, file is missing, same textures, disk space, Fehler beim Anwenden

mod.json of the apps vs the SDK schema

The SDK packages (pip, npm, cargo, go) use a different mod.json, defined in the repository's spec/mod.schema.json:

	Apps (Loader, Studio)	SDK schema
game	`spiel` only	`game`; `spiel` as legacy alias
`id`	required	not in the schema
`name`	required	optional (folder name)
`priority` default	`100`	`0`
equal priority	sorted by `id`	input order
asset entries at the top level	ignored	accepted when `assets` is missing
`cvars`, `author`	read	not in the schema
keys besides `set`/`file` in an asset	ignored	not allowed

Both apply file first and set on top. The SDK and its own wolfsdk -g command line: Modding Guide, part for programmers.

Keywords: SDK schema, mod.schema.json, game vs spiel, difference, SDK mod.json, pip package, compatibility, Unterschied, SDK

A mod.json that works in the apps and the SDK

Write it so both read it the same way:

id and name (the apps need both; the SDK accepts extra keys).
spiel for the game; the SDK reads it as the legacy name of game. If you also write game, give it the same value.
priority written out, because the defaults differ (100 vs 0).
Everything under assets, each entry with only set and/or file.
cvars only work in the apps.

Keywords: compatible mod.json, both formats, SDK and loader, portable mod, game and spiel, kompatibel, beide Formate

Which parts of the mod format are confirmed in game?

Applying and reverting mods with backups: Confirmed in game.
set on a The New Colossus decl: Confirmed in game (the Explosive Pistol's 30-round magazine).
file on a The New Colossus cfile: Confirmed in game (Sandbox Tools: god mode and infinite ammo).
cvars in The New Colossus via default.cfg, and in The New Order via start arguments and +toggle: Not yet confirmed in game.
The New Order: patched archives load without errors (measured, Modding Limits §4); what most single value changes do in game is Not yet confirmed in game.

Keywords: confirmed in game, tested, status, does set work, does file work, cvars work, im Spiel bestätigt, getestet

Mod Format

In plain wordsIn einfachen Worten

Technical detailsTechnische Details