Modding
Discord Wishlist on Steam

Getting started

mod.json and formats

mod.json says what a mod is and lists what it has. Every key but id may be left out, and a key a mod doesn't use is simply not there. The bench writes it; it is plain JSON, so any text editor can too.

json
{
  "id": "example",
  "title": "Blackened steel",
  "version": "1.0",
  "author": "Black Autumn",
  "description": "Blued blades and plate.",
  "format": 4,
  "weapons": [ { ... } ],
  "armour": [ { ... } ],
  "bodies": [ { ... } ],
  "sets": [ { ... } ],
  "sieges": [ { ... } ],
  "commands": [ { ... } ],
  "patches": [ { ... }, "patches/more.json" ],
  "graphs": [ "graphs/fire_sword.graph.json" ],
  "maps": [ { ... } ],
  "texts": { "cs": "texts/cs.json" },
  "requires": [ "roads_library" ]
}

The keys

keywhat it holdstold in
idthe mod's own name, lower-case letters, digits, - and _. Left out, it is the folder's namebelow
title, version, author, descriptionwhat players see on the Mods page and the Workshop
formatthe modding format the mod was made with; the bench writes itformats
weaponsnew weapons, and ours changedWeapons, Changing ours
armournew armour and clothes, and ours changed (armor is read too)Armour and clothes
bodieswhole bodies drawn instead of oursBodies
setswhole outfits, worn together on a stand in the Test MapBodies
siegesnew game modes made from the Šášov siegeSieges
commandschat commands for the dev role that dress a player in a kitBodies
patcheschanges to anything of the game's, new things, things placed in scenesPatches
graphsnode graphs: behaviourGraphs
mapsarena maps of the mod's ownThe map editor
textswords in a language: translations, new languagesWords and barks
requiresthe mods this one needsMods that need other mods
workshopits Workshop item, written by the bench when it is first publishedThe Workshop

Files under the mod's resources/ folder need no key: each stands in for one of the game's files at the same path (Files over ours). A thumb.png beside mod.json is the mod's picture on the Mods page, the bench and the Workshop. It is not part of what a server compares.

Names and ids

  • A mod's id is lower-case letters, digits, - and _. The game tells mods apart by it: a second folder with an id already found is left out, with a line in the log.
  • A thing's own name (a weapon, a piece, a body) is letters, digits and _. In the game it is <mod id>.<name>: the weapon BlackBlade of the mod example is example.BlackBlade, and its content id is thing/example.BlackBlade.
  • Things named in a mod (a siege's weapon, a patch's thing/...) are found among the mod's own first, then among the mods it requires, then among ours.
  • Pixels are always [x, y] counted from the picture's top left, as a painting program shows them.

Formats

The game reads mods up to the format it was built with, and the bench writes into every mod the oldest format that reads it right. A mod made with newer tools than the game has is listed on the Mods page but not loaded, with "update the game".

formatadded
2a gun's shot and sounds
3loadout points, a gun's magazine picture and heat, a saber's own sounds, bodies, sets and sieges
4patches, graphs (with functions), texts, requires, maps, files over ours

The ModKit's modkit.json says which format the game beside it reads.

Every file counts

Every file in a mod's folder is hashed into its stamp. Online, only players with the same mods and the same files meet, so a changed picture is a different mod. See Online.

Checking a file

Each of a mod's files has a JSON Schema, made from what the game reads, in the ModKit's schemas/ folder and on the web. An editor that knows JSON Schema checks a file as it is written when the file names its schema:

json
{ "$schema": "https://blackautumn.divinevtt.com/modding/schemas/mod.schema.json", "id": "my_mod", "title": "My mod" }
fileschema
mod.jsonmod.schema.json
a file of patchespatches.schema.json
a graphgraph.schema.json
a mapmap.schema.json
a brain filebrain.schema.json

The game itself is the last word: what it can't use is told on the Mods page.

A mistake is told, not hidden

Each problem is written on the Mods page and in the log, with the file and the entry it is in: patches/items.json #2: .... An entry with a mistake is left out whole; the rest of the mod still loads. A mod that can't be read at all (mod.json isn't JSON) isn't loaded, and says why.