Modding

Where the mods folder is

Open Mods from the main menu. The path is printed at the top of the screen, with a button beside it that opens the folder in your file browser.

It sits next to your saves, and it is the same folder whether you are installing somebody's mod or writing your own. Nothing is read while the game is running, so it does not matter whether the game is open while you move files around.

Installing one

A mod is a folder with mod.json at the top of it. Most downloads are that folder in a zip.

A mod you copied in is off until you say otherwise. The game refuses executables outright, but a data package can still change prices, items and people in ways you did not ask for, and one that turned up by itself inside a save in progress is a problem nobody wants to diagnose. So the game asks. It is one extra restart the first time, and never again for that package.

There is no launcher, no load-order file to edit and nothing to register. Load order is a number inside each package, chosen by its author.

Start a new run for a package that adds people, places or quests. A save already in progress keeps the world it was made with. Packages that only change numbers, pictures or colour are visible in a save you are already in. Audio and font files are validated, but no running package surface consumes them yet.

Did it load?

Mods, in the main menu. Every package it found is on one row, with a state in a word: loaded, off, not valid, in conflict, needs another mod, skipped.

A mod can also switch itself off, and it says why. The switch you set applies to the package you set it on, not to its name in the folder. Mod ids are chosen by their authors and nothing coordinates them, so two unrelated mods called northern_reach is an ordinary accident — and without this the second would inherit the first one's switch. If the mod under an id is not the one you turned on, the row says so: this is not the mod you turned on. Updating a mod in place keeps your switch; deleting it and copying a different one does not.

If you are a mod author and you see that line about your own package, you have an id collision with somebody else's mod. Pick a less obvious id.

Two of those words are about a restart you owe rather than about the package. On — restart to load means you switched it on and nothing has read it yet; Off — restart to unload means the opposite, and its content is still in the game until you restart. They are separate words on purpose: a screen that said "Loaded" the moment you flipped a switch would send you looking in the world for something that is not there yet.

When the state is not "loaded", the line under the row says why, in the language you are playing in and without an identifier you did not type — which file the game refuses to run, which package is missing, which version it wants. Under that, what the package's content did: how many entries went in, how many were refused. Show details opens the rest, which is the ids and the exact rule each refused record broke.

Two rows share a word on purpose: Needs another mod is the same problem to a player whether the package it needs is missing or is the wrong version, and the line under the row says which. And when two packages claim the same record, the higher load_order writes last and wins — but a takeover nobody declared is an error, not a note. Both rows are flagged and the loser's row names the winner, and the winner is still worked out rather than left to chance: a refusal must not also be a coin flip. When two mods want the same thing is how to declare one on purpose.

"Loaded" does not yet mean you can see it in the world. For that, read the counts under the row, and Now find it in the game says where each kind of thing turns up.

The counts always add up. Read is applied, plus rejected, plus replaced by another mod, plus waiting for its conditions — and the last two are named rather than left as a gap. A record another package writes last is not refused, because nothing is wrong with it, and not applied either, because it is not the one the game kept. It is the difference between reading one line and spending an evening looking for a bug in a file that does not have one. Show details says which record, and which package has it now.

One number sits beside that sum rather than inside it: files nobody read. A file whose family is not in content_types was never opened, so there is no record to account for and no way to know how many are in it. It is a count of files, not of records, which is exactly why it cannot be a sixth term: the sum starts at read, and these were never read.

Before you ask anyone for help

Open Mods and press Copy report. Paste the whole thing into your message, then say what you expected.

One plain text, ready for a forum, a Discord message or a bug report: the build you are on, the mods folder, every package with its version and load order and state, the reason behind every refusal, the counts for every kind of content, and which package won every clash.

the report the Mods screen copies

Bonemark mod report
game build: 0.0.0-dev
mods folder: C:/Users/you/AppData/Roaming/Godot/app_userdata/Bonemark/mods
packages: 2 found, 1 loaded

PACKAGES
  northern_reach  v0.1.0  order 100  active
    goods: 12 read, 12 applied, 0 rejected
  winter_roads  unreadable manifest
    - game_version must not be empty

CONTENT (1 families: 12 read, 12 applied, 0 rejected)
  goods: 12 read, 12 applied, 0 rejected

Nine times in ten the answer is in the block and nobody has to ask you a single question first. It reads nothing but the mod folder, changes nothing, and contains no personal information.

It is in English even when you are playing in another language. That is on purpose: whoever helps you may not read yours, and every fact in it — ids, versions, counts — is the same in every language anyway.

Taking one out again

Delete its folder and restart. That is the whole uninstall.

Nothing of yours is deleted with it. A save keeps ids it can no longer resolve, reports them, and hands the things back if the package is reinstalled. A session that cannot understand a save does not overwrite it either — the original file is left exactly as it was, which is the difference between an afternoon lost and a run lost. Saves is the full account.

If the game will not start at all after installing something, the way out does not need the game. Open the mods folder and move the last thing you added out of it. Packages are only read from that folder, so a folder that is not there is a package that cannot be loaded, and the next start is the start you had before. You do not need a menu, a console or a working launch to do it.

The game also tries by itself — If the game will not start is a bounded number of retries and then a way back in with no packages loaded — but that is the belt, and moving the folder is the braces.

What you can build today

Now, without asking anyone: goods and the merchants who sell them, items, people and where they stand, buildings and the services inside them, places on the map, conversations, scenes, quest plans, maps drawn in Tiled, pictures and colour, and the words for all of it in seven languages. Audio and font files are checked and read, but their package surfaces are not consumed yet; the status table says this plainly instead of calling them ready. Every family is the measured list, and its status column comes out of the build rather than out of a promise.

Not yet, and What you cannot do yet, and why says why for each: the quests family, package audio, package fonts, packaged total conversions, and a package that is a feature rather than content.

Never, by design: code. No scripts, no scenes, no resource files, nothing the game would have to execute. That is what makes a stranger's mod safe to download, and it is not a stage the project is passing through. What a mod can never do.

Time to the first thing you can see in the game: about ten minutes, most of it spent finding the folder. A mod in ten minutes is the whole path, and the sword at the end of it is real.

What you cannot do yet, and why

Written here, near the front, rather than left to be discovered on the way out. These are the things the build validates without currently putting them on a player-facing package surface, plus the things that are not package content at all.

A mechanic the game has never had is the fourth row wearing a different hat. A sword that hits harder is a number and it is yours; a weapon that fires a beam needs beam rules, and rules are code somebody writes and tests.

What a mod is

A folder of text files. You do not write code. You write lists of things you want in the game, and the game reads them when it starts.

The one rule everything else follows: you may add and change data. You may not make the game run code. That is what makes a mod safe to download — the worst a stranger's mod can do is put a silly sword in your game.

34 families are ready to use today, among them items, buildings, pois, npc_definitions, vendor_inventories, quest_plans, caravans and perks. Every family is the whole table with what each one is; The families, one by one gives every one of them its fields and a record you can copy.

Pick your path

This is the index of the whole guide — where a subject is written up, whether or not you are building it today. There is a second, shorter index at the top of Part 3: that one is the six tutorials, in the order they build on each other. If you are here to make something rather than to look something up, go straight to it.

Or by the thing you have in your head. This guide is arranged by the order the work happens in — manifest, then validation, then content, then reports — which is the order somebody who already knows the system would choose. Somebody who does not is thinking I want to add a merchant, and looking for the word merchant:

What you need

An editor that colours JSON shows you a missing comma while you are still looking at it, instead of the game telling you later that the file was unreadable.

Python is optional, and the console is optional. The game itself is enough: drop the package in, restart, and open Mods, which names every record it refused and why. The author checkout is public. Authors who want faster iteration or release automation can clone the public Bonemark source checkout and run the offline tools in Offline tools; players installing a released package do not need Python or Godot. The same public checkout is the source of the validator and the runtime's declarations, so the two sections below describe one toolchain. The tools use the same declarations as the game — the record schemas and the safety boundary are one source each — so they tell you sooner, never differently. A debug console is useful for inspecting a loaded package, but it is not required to write one.

Start from what you want to make

Everything below this line is arranged the way the work happens — manifest, then files, then families, then reports. That is the right order for looking something up and the wrong order for starting, because nobody starts with a manifest. They start with I want a merchant.

So: pick the sentence that sounds like what you are trying to do.

The six tutorials are one package, built up a piece at a time: a beeswax candle, the bundle a player carries, the chandler who sells it, her shop door, the pit behind the tannery where the tallow comes from, and finally a change to the candle the game already had. Do them in order and you finish with a mod somebody could download. Do one out of the middle and it works on its own.

Where the game's own numbers are

Every tutorial here prices a new thing against something the game already sells, because a number with nothing beside it is a guess, and a guess in an economy that trades between towns does not stay where you put it.

You cannot open the game's own files. Its records are Godot resources inside the packaged build — a different format from the JSON you write, with category = 1 where your file says "MANUFACTURED". There is no folder to copy from, and unpacking one is not a workflow anybody should document.

You do not need to. The catalogue publishes the game's own content, generated from those same records on every build: 270 items with their category, weight, value in coin and stack size, 49 weapons, 42 pieces of armour, 37 places. It is the reference this guide anchors to, it cannot drift from the game, and the field name is printed beside every row.

A dozen values worth knowing before you price anything:

If your new thing costs more than plate armour, something has gone wrong and the game will not tell you: it will quietly become the most profitable cargo in the world and every caravan will carry it.

A good to sell

You will have a trade good the economy knows how to price, anchored to the candle the game already sells, ready for a merchant to stock.

Screenshot: not taken yet. This slot stays empty until there is a real one — a drawing of what it might look like would be the only untrue thing on the page.

Read first: What a mod is · A mod in ten minutes · Names and ids

Copy from: the folder called chandlery, which is already in your mods folder. The game puts it there the first time it starts, switched off, and it is the finished result of these six tutorials — every record below is in it. It is also the package the repository's own test lane runs against the loader, so nothing here is a record the game would refuse. Turn it on to see it working, or copy the folder, rename it, and make it yours.

Where the files go:

where the files go

mods
└ chandlery
  ├ mod.json
  └ content
    └ economy
      └ goods
        └ goods.json

Start from the candle the game already has. It is called candle, it costs 3, it weighs 0.5, it is MANUFACTURED and PRESERVED, and the apothecary makes it. Yours is the same object made of better wax, so it keeps every one of those answers and changes two.

mod.json first:

mod.json

{
  "id": "chandlery",
  "name": "The Chandlery",
  "version": "0.1.0",
  "game_version": "0.0.0-dev",
  "dependencies": [],
  "load_order": 100,
  "content_types": ["goods"],
  "overrides": [],
  "canon_safe": true
}

Then content/economy/goods/goods.json:

a goods record

[
  {
    "id": "chandlery:beeswax_candle",
    "display_name": "Beeswax Candle",
    "category": "MANUFACTURED",
    "decay_tier": "PRESERVED",
    "base_price": 9,
    "weight": 0.4,
    "production_class": "chandler",
    "daily_consumption_class": "household",
    "tags": ["light", "household"]
  }
]

Done — now find it in the game. Restart, open Mods, and the line under your row says 1 entry added. That is the whole of what a good on its own does: it is priced and tradeable and it is on no counter anywhere, because nothing stocks it yet. That is not a failure and it is the thing that confuses everyone once. Carry on to A merchant who stocks it.

If it does not show up: Nothing showed up has the six reasons in order. The commonest by far is content_types — a family missing from that line means the folder is never opened, whatever is in it. Then Before you ask anyone for help, which is one button.

An item to carry

You will have the thing a player picks up, stacks in the pack and sells back, paired to the good you just wrote.

Screenshot: not taken yet.

Read first: A good to sell · Names and ids

Copy from: chandlery/content/inventory/items/items.json in your mods folder.

Where the files go:

where the files go

mods
└ chandlery
  ├ mod.json
  └ content
    ├ economy
    │ └ goods
    │   └ goods.json
    └ inventory
      └ items
        └ items.json

A good and an item are two halves of one thing. The good is the economy's view — what a town produces, what a caravan hauls, what a price is. The item is the player's view — what sits in the pack, what stacks, what a shop displays. Grain has a good and no item, because nobody carries a sack of grain around. Candles have both.

Add "items" to content_types in mod.json, then write content/inventory/items/items.json:

a items record

[
  {
    "id": "chandlery:beeswax_candle_bundle",
    "display_name": "Bundle of Beeswax Candles",
    "category": "MATERIAL",
    "rarity": "COMMON",
    "weight": 0.4,
    "max_stack": 20,
    "base_value": 10,
    "sellable": true,
    "tags": ["light", "household"]
  }
]

Done — now find it in the game. An item nothing hands out is loaded and reachable by nothing. In a debug build item chandlery:beeswax_candle_bundle puts one in your pack immediately, which is the fastest proof it loaded — but that command does not exist in the game people download, so it is a shortcut for you and never the answer for a player. The real answer is the next tutorial.

If it does not show up: Nothing showed up, then Before you ask anyone for help.

A merchant who stocks it

You will have a named woman standing in Old Seat with a stall, stock that refills every two days, and your candles on the counter.

Screenshot: not taken yet.

Read first: An item to carry · Now find it in the game

Copy from: chandlery/content/narrative/npcs/npcs.json and chandlery/content/world/vendor_inventories/vendors.json.

Where the files go:

where the files go

mods
└ chandlery
  ├ mod.json
  └ content
    ├ economy
    │ └ goods
    ├ inventory
    │ └ items
    ├ narrative
    │ └ npcs
    │   └ npcs.json
    └ world
      └ vendor_inventories
        └ vendors.json

This is the one where two families have to agree. The person carries the id of the stall, and the stall carries the id of the person, and each row of the stall carries the id of an item. Three ids, and every one of them has to be spelled the way you spelled it in the other file. It is the mistake that costs an evening, and the Mods screen names it: a row pointing at an id nothing supplies is listed as needs another mod that is not installed.

Add "npc_definitions" and "vendor_inventories" to content_types.

a npc_definitions record

[
  {
    "id": "chandlery:hesta",
    "display_name": "Hesta the Chandler",
    "title": "Candle Seller",
    "short_bio": "She renders fat behind the tannery and sells what burns longest.",
    "voice_tone": "brisk",
    "faction": "NONE",
    "role": "NONE",
    "settlement_id": "old_seat",
    "is_vendor": true,
    "vendor_inventory_id": "chandlery:candle_stall",
    "price_multiplier": 1.0,
    "personality_tags": ["brisk", "practical"],
    "offers_quest_ids": []
  }
]

a vendor_inventories record

[
  {
    "id": "chandlery:candle_stall",
    "display_name": "Chandler's Stall",
    "npc_id": "chandlery:hesta",
    "global_price_multiplier": 1.0,
    "buyback_rate": 0.35,
    "entries": [
      {
        "item_id": "chandlery:beeswax_candle_bundle",
        "kind": "misc",
        "daily_stock": 6,
        "price_multiplier": 1.0,
        "restock_days": 2,
        "min_standing": 0
      }
    ]
  }
]

Done — now find it in the game. Restart, travel to Old Seat, find Hesta, open the trade screen. If the stall is empty, it has not restocked yet: that is restock_days, not a bug. Three ways the chain can be broken and all three are on the Mods screen — the good with nothing stocking it, the stall pointing at an item id that does not exist, the person pointing at a stall id that does not.

She can also speak. A dialogue_graph whose speaker is her id gives her lines when a player clicks on her, and your package does not have to redefine anything the game already owns to get them — see Conversations of your own. A locales file gives her all of this in seven languages.

If it does not show up: check the three ids against each other first, then Nothing showed up, then Before you ask anyone for help.

A building service

You will have a door in a settlement with your own label and colour on it, opening onto an interior the game already has.

Screenshot: not taken yet.

Read first: A merchant who stocks it · What a mod can never do

Copy from: chandlery/content/world/buildings/buildings.json.

Where the files go:

where the files go

mods
└ chandlery
  └ content
    └ world
      └ buildings
        └ buildings.json

You are recombining, not building. A buildings record adds a new service with a label, a door colour and a routine role, and it may reuse an interior the game already has by naming it. It cannot ship an interior. An interior is a scene, a scene is code, and a package that names a res:// path or a .tscn is refused before this record is ever read. That is not a gap waiting to be filled — it is the line that makes a stranger's mod safe to install.

a buildings record

[
  {
    "id": "chandlery:chandlery",
    "label": "Chandlery",
    "role": "merchant",
    "color": { "r": 0.44, "g": 0.38, "b": 0.24 },
    "interior_service": "shop"
  }
]

Done — now find it in the game. Restart and walk into a settlement that has your service. A record with no settlement is loaded and placed nowhere, which looks exactly like a record that failed — the Mods screen will say 1 entry added and you will find nothing. Read the row before you look for the door.

If it does not show up: Nothing showed up · Before you ask anyone for help.

A place on the map

You will have a spot on the world map that a player can stumble on, with its own description and its own effect on the company's mood.

Screenshot: not taken yet.

Read first: A building service · Now find it in the game

Copy from: chandlery/content/world/pois/pois.json.

Where the files go:

where the files go

mods
└ chandlery
  └ content
    └ world
      └ pois
        └ pois.json

Coordinates are absolute and the world is generated around authored places. The map is 61 440 × 34 560 world pixels and Old Seat sits at the exact centre, (30720, 17280), in every run. The authored cities and villages keep their names and positions. The seed changes the terrain and biomes around them, the shortage of the year, the political arrangement and which roads are worth taking. A position is still a real, stable point; what is next to it changes every game. Two honest ways to use that: anchor near an authored settlement, so a player will pass it; or mean the emptiness, because a rendering pit nobody has walked past in years is supposed to be nowhere in particular.

a pois record

[
  {
    "id": "chandlery:tallow_pit",
    "kind": "RUINS",
    "display_name": "The Tallow Pit",
    "description": "A rendering pit behind the tannery. The smell reaches the road.",
    "world_position": { "x": 5400.0, "y": 3000.0 },
    "discovery_radius": 2.0,
    "one_time_loot": false,
    "morale_modifier": -1,
    "awareness_modifier": 0.0
  }
]

Done — now find it in the game. Travel there. There is no teleport command, in a debug build or out of it, so pick coordinates you are willing to walk to while you are testing.

If it does not show up: you are probably outside discovery_radius, or the position is somewhere the run's seed put an ocean. Nothing showed up.

Changing what is already there

You will have changed a record the game shipped — and declared it, so the change is visible to the player and to every other mod.

Screenshot: not taken yet.

Read first: Change what the game already has · When two mods want the same thing

Copy from: chandlery/content/economy/goods/goods.json, which adds a record and patches one of the game's in the same file.

Where the files go: nowhere new. A change to something the game already has lives in the same family folder your own records live in — the file says which record it means and what it is doing to it.

where the files go

mods
└ chandlery
  ├ mod.json          the change is declared here
  └ content
    └ economy
      └ goods
        └ goods.json  your record and the patch, in one file

Two rules before the file. A change to somebody else's record must be named in overrides in mod.json — a record landing on an id you did not declare is refused, so nothing can quietly rewrite something a player did not agree to. And patch, which changes one field and leaves the rest, needs "manifest_version": 2.

mod.json

{
  "id": "chandlery",
  "name": "The Chandlery",
  "version": "0.1.0",
  "game_version": "0.0.0-dev",
  "manifest_version": 2,
  "load_order": 100,
  "content_types": ["goods", "items", "npc_definitions", "vendor_inventories", "buildings", "pois"],
  "overrides": ["candle"],
  "canon_safe": true
}

a goods record

[
  {
    "op": "patch",
    "id": "candle",
    "changes": [
      { "op": "set", "field": "base_price", "value": 4 },
      { "op": "append_unique", "field": "tags", "value": "chandlery_touched" }
    ]
  }
]

Done — now find it in the game. The Mods screen names the record you took over. So does the other author's screen, if there is one: when two packages write the same id, the loser's row now reads replaced: candle — 'chandlery' writes it last, instead of silently showing one fewer entry than they wrote. Whoever has the higher load_order writes last and wins.

Winning is not the same as being allowed to. Two packages taking over one record, with neither naming the other in supersedes, is reported as undeclared_collision and the composition is not ok — the offline validator says the same thing and refuses:

typed into the debug console

ERROR: conflict on goods:candle: ['early', 'late'] each supply the whole record
and none declares the others under `supersedes`

The winner is still worked out, because a refusal must not also be a coin flip, but two authors who both meant it have to say so. When two mods want the same thing is that conversation.

If it does not show up: the usual cause is overrides — the id has to be in that list, spelled exactly, or the record is refused rather than applied. When two mods want the same thing · Nothing showed up.

A mod in ten minutes

1. Make a folder in the mods folder, named lower case with underscores: northern_reach. Everything happens inside it.

2. Write mod.json at the top of it:

mod.json

{
  "id": "northern_reach",
  "name": "The Northern Reach",
  "version": "0.1.0",
  "game_version": "0.0.0-dev",
  "dependencies": [],
  "load_order": 100,
  "content_types": ["items"],
  "overrides": [],
  "canon_safe": true
}

id must match the folder name. content_types lists the families you bring — a family missing from that line is never read, whatever is in the folder.

3. Make the folders content/inventory/items and put blades.json in them:

a items record

[
  {
    "id": "northern_reach:frost_blade",
    "display_name_key": "northern_reach.item.frost_blade.name",
    "display_name": "Frost Blade",
    "category": "weapon",
    "base_value": 240,
    "weight": 3
  }
]

The brackets are a list — add as many swords as you like, separated by commas. Every .json file in a family folder is read, so split them however you want.

240 is not a number picked for looking large. One-handed weapons in this game run from 50 to 300, so a frost blade at 240 is an expensive sword and not a legendary one, and a player can afford it about when they could afford the good ones the smith already sells. Where the game's own numbers are is the table to look at before choosing any number at all; a price with nothing beside it is a guess, and in an economy that trades between towns a guess does not stay where you put it.

4. Start the game and open Mods from the main menu. Your package gets exactly one state, and Did it load? has the six of them.

5. Read the line under the row for what was read, applied and refused, with the reason for each refusal. Show details has the ids.

6. Your sword is in the game. Everything after this is more of the same.

Now find it in the game

The report says applied. That means the record is loaded, and it is not the same thing as being able to walk up to it. This is where every guide stops and every author starts guessing.

settlement_id names an authored place. Settlement ids are authored and stable: Durnwall, Thorngate, Valdmere, Grentham and the twelve villages can all be named. The seed changes the terrain and biomes around them, the shortage of the year and the political arrangement, not the id. If you want a person somebody will definitely meet, use any authored settlement id and keep the name in your package's locale data.

Coordinates are absolute, and the world is generated around authored places. The map is 61 440 × 34 560 world pixels and Old Seat sits at the exact centre of it, (30720, 17280), in every run there has ever been. The authored cities and villages keep their names and positions. The seed changes the terrain and biomes around them, the shortage of the year, the political arrangement and which roads are worth taking. So a world_position of (6000, 2200) is a real, stable point in the far north-west of the map, and what is near it is different in every run: it might be a road, a forest or the middle of nowhere. Two ways to use that honestly:

• Anchor to the centre. A POI a few thousand pixels from (30720, 17280) is near Old Seat in every run, so it is a place a player will find.
• Mean the emptiness. A ruin nobody has walked past in a hundred years is supposed to be nowhere in particular. Absolute coordinates are exactly right for that, and the seed will decide what its neighbours are.

The console commands that save the most time. day [n] and hour [n] advance time, which is how you see a restock without living through it. item <id> [count] and gold <amount> put things in your hands. flag, quest_start and faction_rep move the state a condition might be waiting on. There is no teleport command: to reach a place, travel to it.

mod.json, field by field

A dependency may be an object instead of a name: {"id": "some_mod", "version": "", "optional": true}.

A value naming another package is a cross-mod reference and the reference has to be a declared dependency. If that dependency is optional, give the field a fallback, or the record is skipped when the dependency is absent:

a goods record

[
  {
    "op": "add",
    "id": "northern_reach:alloy",
    "display_name": "Alloy",
    "linked_item_id": "absent_helper:ore",
    "fallback": { "linked_item_id": "iron_ore" }
  }
]

Where each file goes

where the files go

northern_reach/
  mod.json                  the label
  content/assets/images/
    images.json             your art
  content/inventory/items/
    blades.json             your first record
  content/narrative/quest_plans/
    the_long_winter.json    your quest

Names and ids

An id is lower case letters, digits and underscores, and nothing else. frost_blade, not Frost Blade, not frost-blade and not frost.blade. It carries no separator of its own either, because a separator inside an id is the folder leaking into the name: move the file and the id disagrees with the disk. The : above is the one exception, and both halves of it obey the rule.

The part before the colon is your package id. It is how two mods can both add a Frost Blade without colliding.

Words a player reads

Text written into a record is text in one language. Point at a key instead:

a locale CSV

northern_reach.item.frost_blade.name
northern_reach.item.frost_blade.description

Keys are lower case, joined by dots, namespaced like ids. Ship the words in the locales family — a .csv under content/locale with a key column and one column per language. The families, one by one has the exact shape.

Write the plain display_name beside the key as well. A record with only a sentence has to be rewritten by hand the day you translate it, and by then there are four hundred of them.

The two ways of getting this wrong fail very differently, and only one of them tells you. A key nothing answers shows up as the key itself — northern_reach.item.frost_blade.name, on the screen, deliberately ugly so that somebody fixes it, and counted as a gap. A record carrying only text and no key never shows up at all: it works, in your language, for every player in every language. Nothing is refused and nothing is missing, so nothing reports it, and a player reading in Portuguese quietly reads your Italian. The first mistake you find. The second one finds your readers.

Translating a mod, and being translated

The game ships in seven languages, so a package with English baked into its records reads as English to six-sevenths of the people who install it. This is what it costs to avoid that, which is almost nothing if you do it on the first day and a rewrite if you do it on the four hundredth.

The languages there are

Seven, and this table is read out of the build rather than typed here, so a language arriving or leaving moves it the same day:

Two of the codes have a second spelling in the wild — pt-BR is what a storefront and this page use, pt_BR is what the engine standardises to — and both are accepted in a column header. Write whichever you copied.

Shipping words in more than one language

One CSV under content/locale, key first and one column per language:

a locale CSV

key,en,it,de
northern_reach:GOOD_FROST_SALT,Frost Salt,Sale di Brina,Frostsalz
northern_reach:ITEM_FROST_BLADE_NAME,Frost Blade,Lama di Brina,Frostklinge

When a key has no answer in the player's language the game works down a fixed ladder — the player's language, then the language your package declares it was written in, then the game's own catalogue, then the key itself. The last rung is ugly on purpose: an unresolved key has to look wrong so that somebody fixes it. A total conversion skips the game's catalogue, because Old Seat surfacing in a world set on another continent is not a small mistranslation, it is the base game showing through.

Writing text that can be translated at all

• No sentences built out of pieces. Word order is not the same in every language, so a name assembled at runtime from an adjective column and a noun column produces Oro Cervo in Italian. One authored entry per language, complete.
• A person's name is never translated and never inflected. Aldric is Aldric in every language. That also means a key must not put a name in an oblique position — "of {name}", "{name}'s" — because several languages decline proper nouns and the game does not.
• There is no character limit, and that is not the same as no limit. No field counts characters; what runs out is room on the screen. German runs about a third longer than English and is the language that breaks buttons; Chinese is far shorter and almost never does. If you test one translation, test German, and give a label the shortest wording that is still the right wording.

Somebody translating your package

They add a column and send you the file. That is the whole workflow, and it is why the format is CSV rather than something friendlier to a programmer: a translator can open it in a spreadsheet, and their tools already read it.

Two things make the difference between a package that gets translated and one that does not. Keep the keys stable — a renamed key is a lost translation, and the translator finds out when a player does. And say what a line is for: a key called NR_MSG_01 gets a guess, while northern_reach:VENDOR_HERB_GREETING gets a greeting from a herb seller.

If you are the one translating somebody else's package, the same rules bind you: the columns are the languages the game ships, the keys are theirs and not yours, and a name stays a name.

Change what the game already has

part of mod.json

"overrides": ["iron_sword"]

overrides is a promise. A record landing on an id you did not declare is refused, so you can never quietly change something a player did not know about.

a goods record

[
  {
    "op": "patch",
    "id": "iron_ore",
    "changes": [
      { "op": "set", "field": "base_price", "value": 14 }
    ]
  }
]

A patch names its changes one at a time:

• set — Write value at field, whatever was there before. Written with field and value.
• unset — Drop field from the record, so the reader sees whatever the family's default is. Written with field.
• append_unique — Add value to the list at field if it is not already there. Written with field and value.
• remove_value — Drop every occurrence of value from the list at field. Written with field and value.

• Name a field by path, never by position. tags.0 is refused. The third tag today is the second tag after somebody else's mod loads.
• A path is up to four lower-case names joined by dots. Anything with an operator in it is refused.
• append_unique is the one two mods can share. Both appending the same tag is not a conflict and does not double it.

Only sometimes

A record can say when it counts. Add a when next to the op, in a "manifest_version": 2 package:

a presentation_bindings record

{
  "op": "add",
  "id": "my_mod:snowy_cloak",
  "subject": "wool_cloak",
  "kind": "item",
  "slot": "icon",
  "cue": "my_mod:cloak_snowy",
  "when": { "season": { "is": "winter" } }
}

There is no operator and nothing to calculate. Everything a condition can say is in these two tables.

Four subjects at most in one when, two tests per subject. Two tests on one subject are a range: { "day": { "at_least": 10, "at_most": 30 } }.

Which families take which. Every family takes the three settled at load. Only presentation_bindings and effects take the four that move while playing, because only those two are rebuilt when the world changes. Naming season anywhere else is refused, and the message says which subjects that family does take.

The reason is saves. A record that decides an item, a person or a quest has to be the same record on the next load, and a condition that moves is exactly what makes it not be.

A seasonal look goes on the binding, not on the picture. Ship the image once, then two presentation_bindings records for it — one with a when, one without. images, audio and fonts refuse a when outright.

Withheld is not rejected. A condition that is not met withholds its record and the load report says so by name:

what the game prints back

WITHHELD my_mod:snowy_cloak from my_mod: season is winter, and it is spring

A package with fifty seasonal records is three-quarters withheld at any moment. That is the package working.

If every conditional presentation binding is withheld, the report still shows the family as declared and prints bound=0 together with each WITHHELD row; it does not misreport the package as having no presentation surface. If no unconditional binding supplies the same slot, it also prints NO_APPLICABLE kind/subject/slot with the unanswered condition, which means “nothing applies in this world state”, not “the record was malformed”. Test the condition in the host or runtime lane with the matching world state before assuming the binding was rejected.

Two versions of one thing. Ship two add records with the same id and different conditions. The one whose condition holds is the one that loads. If both hold, the second is refused as a duplicate — which is how overlapping conditions get reported instead of settled by file order.

Taking something out

remove means out of supply, not out of existence. The record keeps resolving and is marked: nothing new is offered, stocked, crafted or spawned from it, and everything a player already has that names it still reads exactly what it always did.

a goods record

{ "op": "remove", "id": "iron_ore" }

vendor_inventories is the only family that drops the record, and only because the save rules already say nothing points at that row.

A remove cannot carry a when. A withdrawal a save may name has to be settled, or an id resolves on one evening and not on the next.

A removal is final for one composition. A later patch, replace or second remove targeting the withdrawn ID is refused, even though a goods withdrawal keeps the old record resolvable through its tombstone. This prevents the save-facing report from saying "withdrawn" while a later package makes the record behave as supplied again. Add a new namespaced ID when you need a new record; do not rely on removal followed by silent resurrection.

When two mods want the same thing

Both load. Every change is composed before anything is built, so the game sees both.

Winning and being allowed are two different questions, and this is the part that surprises people. The game always works out which package writes last — leaving that to chance would make a refusal a coin flip as well as a refusal — and it still reports the pair as a collision nobody declared. The offline validator refuses the same pair outright, so you find out before a player does.

supersedes in your manifest is how you say you meant it. Name the other package's id and the clash becomes declared_replacement: recorded, with the reason, and no longer an error.

Give your package a load_order of its own. Two packages sharing a number is not refused, and the winner then falls out of alphabetical mod id — an order neither author chose and no player can read off the screen.

Pictures, sound, lettering, colour

Shipping a file and using it are two separate steps and you need both. A file with nothing pointing at it is read, checked, measured and never shown.

Ship the file

Each asset family is a descriptor file plus the files it names. The descriptor must be called after its family — images.json, audio.json, fonts.json.

where the files go

content/assets/images/
  images.json
  river_guard.png

a images record

[
  {
    "id": "northern_reach:river_guard",
    "file": "river_guard.png",
    "format": "png"
  }
]

Three rules that bite:

• The header is checked before anything decodes it. format is what the file is, not what the extension claims.
• A file name containing .. or ~, or starting /, \, res:// or user://, is refused on the name.
• An id that does not resolve gets a placeholder and a report, never silence.

Point at it

On a record you ship, with a field that takes an image id of yours:

On anything at all, including the base game's content, with a presentation_bindings record naming the subject, its kind and the slot:

a presentation_bindings record

[
  {
    "id": "northern_reach:iron_sword_icon",
    "subject": "iron_sword",
    "kind": "item",
    "slot": "icon",
    "cue": "northern_reach:river_guard",
    "alternative_key": "northern_reach_iron_sword_icon_alt"
  }
]

alternative_key is required where a slot carries information: it is the locale key that says the same thing for a player who cannot receive the picture.

Sound

role is a bound, not a label — each carries its own maximum length, its own limit on how many play at once, and the slider a player reaches for.

A compressed WAV is refused: decoding one needs a parser, and the parser is the thing being avoided.

Lettering

covers names the languages your face carries glyphs for, and the build refuses to install it for any other. A face that lacks a language does not fail — it draws boxes, and the screen reads as a half-finished translation with the text correct and the font at fault.

fallback_font is required: name another font id of yours or a system family (Segoe UI, Noto Sans). sizes is what the glyph cache is budgeted against.

One face, never a collection — a .ttc holds several and which one arrives depends on an index the descriptor cannot carry. Free faces with wide coverage: Google Fonts, Font Squirrel. Check the licence lets you redistribute the file; your package ships it.

Colour

Tokens, never a scene, a script or a resource path. The names are the game's: bg_deep, bg_mid, bg_button, bg_hover, border, border_hi, text, text_dim, accent, gold. A name this build does not know is named in the report rather than left looking applied.

a themes record

[
  {
    "id": "northern_reach:dusk",
    "tokens": {
      "bg_deep": { "kind": "colour", "value": "#12131a" },
      "text": { "kind": "colour", "value": "#e8e2d0" },
      "border": { "kind": "colour", "value": "#7f6ab0" }
    },
    "contrast_pairs": [
      { "text": "#e8e2d0", "background": "#12131a" }
    ]
  }
]

contrast_pairs are checked to a ratio of 4.5 and the theme is refused below it. WebAIM's checker tells you a pair's ratio before you ship.

Turn the package off and the interface takes its own colours and lettering back.

Art that fits

The build checks that a picture is a picture. It has nothing to say about whether it looks like it belongs, and in a world drawn in greys a bright, cheerful, high-resolution sword does not stop being wrong for passing every check. This is what is known today.

The full style guide is not published yet. What it will carry: the palette itself, the sizes each kind of thing is drawn at, and side-by-side examples of what sits in the world and what stands out of it. It is worth waiting for rather than guessing, because the failure it prevents is not a refused file — it is a package that installs perfectly and makes the game look like two games.

Until it exists, the reliable method is the one that needs no document: put your picture next to the game's own and look at the two of them together.

Maps of your own

Draw in Tiled, export .tmj, and index it in content/world/maps/maps.json.

a maps record

[
  {
    "id": "northern_reach:river_bend",
    "file": "river_bend.tmj",
    "name_key": "NORTHERN_REACH_RIVER_BEND",
    "world_origin": [4096, 2560],
    "region_id": "northern_reach:lowlands"
  }
]

A binding naming content another package owns — or the base game's — refuses the whole layout. modding_map_report names the layout and the rule that refused it.

Quests of your own

A quest is a set of records that only make sense together, in content/narrative/quest_plans.

a quest_plans record

[
  {
    "kind": "arc",
    "id": "northern_reach:the_long_winter",
    "stages": ["northern_reach:bring_the_grain"]
  },
  {
    "kind": "quest",
    "id": "northern_reach:bring_the_grain",
    "name_key": "northern_reach.quest.bring_the_grain.name",
    "giver": "northern_reach:the_reeve",
    "in_arc": "northern_reach:the_long_winter",
    "objectives": ["northern_reach:gather_grain"],
    "rewards": [
      { "grant": "receive_coin", "coin": 250 }
    ]
  },
  {
    "kind": "objective",
    "id": "northern_reach:gather_grain",
    "quest": "northern_reach:bring_the_grain",
    "goal": "collect_item",
    "target": "northern_reach:winter_grain",
    "count": 40
  },
  {
    "kind": "ending",
    "id": "northern_reach:the_barns_are_full",
    "arc": "northern_reach:the_long_winter",
    "requires": ["northern_reach:bring_the_grain"]
  }
]

• A plan is all or nothing. One wrong record and none install — the alternative is an arc that stops halfway with the player holding the sword and not the title.
• A reward is a grant, never a kind. kind says which of the four records this is. A reward written with kind reads perfectly and is refused.

Check yours with modding_quest_plan_report.

Conversations of your own

A conversation is three kinds of record in content/narrative/dialogue: the dialogue_graph that names it and says which beat it opens on, the dialogue_node beats that are the lines, and the dialogue_option choices standing on them.

Your line is your line, and nothing rewrites it. What a local model can do is answer a question the player types at the character, staying inside what your line says — and when it cannot stay inside it, it says it does not know. The player decides whether that surface exists at all; with the model off, the character says your sentence and stops. Translation of your line happens through the locale files, the same as everything else you write.

The graph names a speaker, and that is the whole trigger. Every character in the game asks this family what conversations stand on them when they are clicked, so you can give the blacksmith something to say without redefining the blacksmith.

a dialogue record

[
  {
    "kind": "dialogue_graph",
    "id": "northern_reach:gate_toll",
    "entry": "northern_reach:gate_open",
    "speaker": "gate_warden",
    "name_key": "TALK_PACK_GATE"
  },
  {
    "kind": "dialogue_node",
    "id": "northern_reach:gate_open",
    "graph": "northern_reach:gate_toll",
    "voice": "line",
    "speaker": "gate_warden",
    "line_key": "TALK_PACK_GATE_OPEN"
  }
]

You write the conversation, never the words: every line is a locale key, so the same package reads in every language the player has. A package that ships prose is refused at the file rather than at the screen.

A beat and a choice may each carry conditions, and a choice may carry commands. A condition decides whether the player is shown the thing at all; a command is what taking it does.

• A conversation naming something this build cannot do never opens. Not the choice that uses it — the whole conversation, before its first line. A talk that stops at the third option has already taken the player's coin.
• Nothing moves more than there is. Ask first with has_coin or has_item; a package that forgets cannot put the player at minus forty coins, because nobody agreed to a debt and no screen explains one.
• Every beat needs a way out. A beat a player can arrive at and never leave is refused when the graph loads.

Check yours with modding_dialogue_report.

Scenes of your own

A scene is the one kind of content that takes the controls away from the player, so it is also the one with a rule about ending. Scenes live in content/narrative/scenes and each names a where — the place it plays in. Walk into that place and the scene plays.

a scenes record

[
  {
    "id": "northern_reach:the_morning_after",
    "where": "northern_reach:waystation",
    "beats": [
      { "beat": "fade_in", "seconds": 1.5 },
      { "beat": "lock_player" },
      { "beat": "say", "actor": "gate_warden", "line_key": "SCENE_PACK_GREETING" },
      { "beat": "wait", "seconds": 1.0 },
      { "beat": "unlock_player" }
    ]
  }
]

• A scene that takes the controls must give them back. A sequence ending without unlock_player is refused, because the alternative ships a room the player can only close the game to leave.
• Beats play in order and a blocking beat is waited for. That is what makes a scene a scene rather than a list of things happening at once.

Check yours with modding_scene_report.

Screens of your own

A screen layout says which sections stand in which panel of a screen the game already has, and in what order. It arranges pieces this build draws; it cannot add one, because a section nobody wrote has nothing to render.

Layouts live in content/ui/screens. The families, one by one has the fields and a record to copy.

Check yours with modding_screen_report.

Nothing showed up

Read the state on the Mods screen first. Most of the states name the problem outright, on the row, and so does the commonest mistake of all — the one that used to be first on this list.

The family missing from content_types. You write goods.json, you leave "goods" off the manifest's list, and the folder is never opened: nothing is refused, because nothing was read. The package loads with nothing in it. The screen now says which file it walked past and what to add:

what the game prints back

content/economy/goods/goods.json was not read — add "goods" to content_types in mod.json

The offline validator prints the same sentence, so the two cannot disagree about it. Only if the row says loaded and names no unread file, work down this list. It is in order of how often each one is the culprit.

The reports never guess. A refused record is named, with what was wrong with it, and usually a code — see Every diagnostic code.

It showed up, and it is wrong

The harder case, because nothing is reported at all. Two things pass every check and still give you a record you did not write.

A field you left out is not an error — it is a default. Each family's schema says which fields a record cannot install without, and for most families that list is short. goods requires exactly one: id. Leave out base_price and it is 1. Leave out weight and it is 1.0. Leave out category and the good is a raw material. Nothing warns you, because nothing is wrong: you asked for a good and you got one.

A value that is not one of the choices is also a default. The reader upper-cases before it looks, so manufactured and MANUFACTURED are the same value and case is never the problem — do not go rewriting files over it. MANUFACTURED_GOODS is the problem: it is not a member, so it becomes RAW_MATERIAL. SLOW for a decay_tier becomes ETERNAL. The record installs, the screen says applied, and your candle is priced and spoils as something else.

Nothing in the game says so, because there is nothing to say: the field is declared as a string and a misspelt string is still a string. The validator is the only place it can be caught, and it now is:

typed into the debug console

$ python tools/quality/validate_mod_data.py --root mods/northern_reach
WARN: northern_reach:goods:goods.json#1: category is "MANUFACTURED_GOODS",
  which is not one of RAW_MATERIAL, MANUFACTURED, CONSUMABLE, AMMUNITION,
  EQUIPMENT. It loads as RAW_MATERIAL.
  ERROR=0 WARN=1

A warning and not an error, because the record does load and refusing it now would break packages that already work. --strict turns it into one, which is the whole reason to run --strict before you publish.

A field you left out stays silent, and that one cannot be caught: leaving category out and writing RAW_MATERIAL are the same request. So the field tables in The families, one by one mark Required and give the values column as the shape the loader checks. When a record loads and behaves like something else, read your fields against that table first: what you are looking for is a field you did not write, or a word the loader did not recognise.

Every family

One folder and one report per family. The status column is measured from the build, so it is never a promise the game does not keep. What it is is the opening line only, so that the table stays something you can run your eye down; each family's description in full, with its fields and a record to copy, is its entry in The families, one by one.

• Ready to use — published shape, the game installs your records, an example exists, and your ids survive a save and a reload.
• Validated, nothing consumes it yet — the loader reads and checks the family, but no player-facing package surface consumes it. Audio and font packages are in this rung: a clean report does not make a silent cue or an unused face appear in the game.
• Checked, not installed yet — the game recognises the family and checks your file, and nothing puts it into a running game. A package targeting one passes every check and loads nothing. It is on the page on purpose: the alternative is somebody spending an evening on it and never learning that they did nothing wrong.

Settled in full, with no family to carry them, so no manifest can ask:

These are not refusals. What a mod can never do is that list.

The families, one by one

Every family the build knows, what it accepts, and one record you can copy.

• Required fields are the ones a record cannot install without.
• The values column is the shape the loader checks, not a suggestion.
• Where a family says so, a field the table does not name is refused along with the record it is in. A typo in a field name is a record that does not load, and the family's report says so by name.

Each entry also says what happens to a save the day a player uninstalls you:

Nothing here is typed by hand. The fields come from each family's published schema. Every example is one of the packages the framework's own test matrix runs against the loader, re-namespaced to northern_reach, and checked against its schema again on the way onto this page: an example the game would refuse fails the build.

The world and the places in it

5 families: buildings, caravans, maps, pois, world_generation.

buildings

Building and settlement-service definitions: label, colour, role and a reused interior.

• Status Ready to use
• Walked through in A building service
• Folder content/world/buildings
• Records addressed by the id field
• Report modding_building_report
• If a player uninstalls you substitute_placeholder. A settlement with a hole where a service was is unplayable; a visibly missing building is legible and recoverable.

Fields. A field this table does not name is refused along with the record.

In a file called buildings.json, or any other .json name you like in that folder:

a buildings record, under content/world/buildings

[
  {
    "id": "northern_reach:guildhall",
    "label": "Guild Hall",
    "role": "reeve",
    "color": {
      "r": 0.4,
      "g": 0.34,
      "b": 0.26
    },
    "interior_service": "moot_hall"
  }
]

caravans

Trade routes a caravan runs: where it starts, where it is going, what it carries, how well it is guarded and how fast it moves.

• Status Ready to use
• Folder content/logistics/caravans
• Records addressed by the id field
• Report modding_caravan_report
• If a player uninstalls you preserve_inert_reference. A route whose package is gone keeps its name and carries nothing. Substituting a destination would send a player's goods somewhere they never agreed to.

Fields. A field this table does not name is refused along with the record.

In a file called caravans.json, or any other .json name you like in that folder:

a caravans record, under content/logistics/caravans

[
  {
    "id": "northern_reach:salt_road_run",
    "display_name": "Salt Road Run",
    "origin_settlement_id": "valdmere",
    "destination_settlement_id": "old_seat",
    "cargo_type": "salt",
    "cargo_value": 240,
    "guard_strength": "light",
    "daily_progress": 0.08,
    "initial_spawn_offset_days": 3
  }
]

maps

Layouts a package draws in Tiled, named by id: the file, where it sits in the world, and the language key it is known by. The index is the record; the layout beside it is read as data and never as a resource, normalised into canonical form, checked against the published kit and assembled before anything is placed. A layout that refuses places nothing at all, because half a map is a region the player walks into with no way to know which half arrived.

• Status Ready to use
• Folder content/world/maps
• Records addressed by the id field
• Report modding_map_report
• If a player uninstalls you drop_optional_presentation. No save names a layout. A save names the POI a layout moved, and that record keeps its own coordinate, so a withdrawn map costs the arrangement and never the content. Dropping it is what makes the world go back to what its records say instead of holding a position nothing supplies any more.

Fields. A field this table does not name is refused along with the record.

In a file called maps.json, or any other .json name you like in that folder:

a maps record, under content/world/maps

[
  {
    "id": "northern_reach:river_bend",
    "file": "river_bend.tmj",
    "name_key": "MAP_RIVER_BEND",
    "world_origin": [
      4096,
      2560
    ],
    "region_id": "northern_reach:lowlands"
  }
]

pois

Points of interest placed on the authored world map by coordinate.

• Status Ready to use
• Walked through in A place on the map
• Folder content/world/pois
• Records addressed by the id field
• Report modding_poi_report
• If a player uninstalls you preserve_inert_reference. A discovered place stays discovered. Quests and travel history point at the id.

Fields. A field this table does not name is refused along with the record.

In a file called pois.json, or any other .json name you like in that folder:

a pois record, under content/world/pois

[
  {
    "id": "northern_reach:drowned_mile",
    "kind": "RUINS",
    "display_name": "The Drowned Mile",
    "description": "A stretch of road the river took back. The milestones still stand, chest deep.",
    "world_position": {
      "x": 0.0,
      "y": 0.0
    },
    "discovery_radius": 3.0,
    "one_time_loot": true,
    "morale_modifier": -1,
    "awareness_modifier": 0.05,
    "narrative_significance_key": "POI_DROWNED_MILE_LORE"
  }
]

world_generation

Data-only generation profiles: weighted host-owned biome and placement selections.

• Status Ready to use
• Folder content/world/generation
• Records addressed by the id field
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. A save records the selected profile id. If its package is absent, preserving and reporting that id is safer than silently rebuilding the run with the base game's map.

Fields. A field this table does not name is refused along with the record.

In a file called profiles.json, or any other .json name you like in that folder:

a world_generation record, under content/world/generation

[
  {
    "kind": "generation_profile",
    "id": "northern_reach:ashen_reach",
    "stream": "northern_reach:world_stream",
    "tables": {
      "biomes": [
        {
          "id": "plains",
          "weight": 60
        },
        {
          "id": "forest",
          "weight": 30
        },
        {
          "id": "hills",
          "weight": 10
        }
      ],
      "settlements": [
        {
          "id": "northern_reach:hamlet",
          "weight": 100
        }
      ],
      "buildings": [
        {
          "id": "northern_reach:longhouse",
          "weight": 100
        }
      ],
      "pois": [
        {
          "id": "northern_reach:standing_stone",
          "weight": 100
        }
      ]
    }
  }
]

People, houses and what they can do

8 families: enemy_archetypes, enemy_variants, group_archetypes, mercenary_templates, noble_houses, npc_definitions, perks, relationships.

enemy_archetypes

Kinds of enemy the strategic layer knows about: tier, which variants they field, where they camp, how large the garrison is and how often they raid.

• Status Ready to use
• Folder content/threat/enemy_archetypes
• Records addressed by the id field
• Report modding_enemy_archetype_report
• If a player uninstalls you preserve_inert_reference. A camp still points at what settled it. Substituting would quietly change what is besieging a settlement; naming the absence is legible.

Fields. A field this table does not name is refused along with the record.

In a file called enemy_archetypes.json, or any other .json name you like in that folder:

a enemy_archetypes record, under content/threat/enemy_archetypes

[
  {
    "id": "northern_reach:salt_reavers",
    "display_name": "Salt Reavers",
    "description": "Coastal raiders who winter inland and burn what they cannot carry.",
    "tier": 2,
    "corruption_chance": 0.1,
    "preferred_camp_biomes": [
      "marsh",
      "coast"
    ],
    "camp_count": 3,
    "garrison_min": 8,
    "garrison_max": 16,
    "aggression": 0.4,
    "raid_cooldown_days": 5,
    "sortie_size_min": 4,
    "sortie_size_max": 9,
    "target_preferences": [
      "caravan",
      "settlement"
    ],
    "camp_glyph": "tent"
  }
]

enemy_variants

Stat blocks for a kind of enemy body on the field: class, tier, the five attributes and the weapon, off-hand and shield ids it carries.

• Status Ready to use
• Folder content/combat/enemy_variants
• Records addressed by the id field
• Report modding_enemy_variant_report
• If a player uninstalls you substitute_placeholder. A body already on the field with no stat block cannot be fought. A stable engine-owned stand-in keeps the battle resolvable and the original id is kept beside it.

Fields. A field this table does not name is refused along with the record.

In a file called enemy_variants.json, or any other .json name you like in that folder:

a enemy_variants record, under content/combat/enemy_variants

[
  {
    "id": "northern_reach:salt_reaver_archer",
    "archetype_id": "northern_reach:salt_reavers",
    "display_name": "Salt Reaver Archer",
    "variant_class": "archer",
    "tier": 2,
    "strength": 3.0,
    "agility": 5.0,
    "constitution": 3.5,
    "aim": 6.0,
    "will": 2.5,
    "main_weapon_id": "short_bow",
    "ai_behavior": "keeps distance and gives ground rather than trade blows"
  }
]

group_archetypes

Strategy tunables for a group that lives on the world map: alarm radius, target preference, member counts, supply and retreat thresholds.

• Status Ready to use
• Folder content/strategic/group_archetypes
• Records addressed by the id field
• Report modding_group_archetype_report
• If a player uninstalls you substitute_placeholder. The strategic AI has to read a threshold from somewhere. An engine-owned default answers, which is the same thing this family already falls through to.

Fields. A field this table does not name is refused along with the record.

In a file called group_archetypes.json, or any other .json name you like in that folder:

a group_archetypes record, under content/strategic/group_archetypes

[
  {
    "id": "northern_reach:pilgrim_column",
    "display_name": "Pilgrim Column",
    "kind": "nomad",
    "faction_id": "",
    "target_preference": "wandering",
    "aggression": "avoid_player",
    "alarm_radius_px": 300.0,
    "night_aggression_multiplier": 0.5,
    "min_members": 6,
    "max_members": 14,
    "behavior_profile_mix": [
      "coward",
      "balanced"
    ],
    "provisions_max": 6,
    "retreat_hp_pct": 0.6
  }
]

mercenary_templates

Hireable mercenary blueprints: name, class, background, starting health and morale, hire cost and the day they first appear.

• Status Ready to use
• Folder content/character/mercenaries
• Records addressed by the id field
• Report modding_mercenary_report
• If a player uninstalls you preserve_inert_reference. Mercenaries already hired live in the save as units; only the tavern list loses its blueprint. The id stays named so the roster's origin is still readable.

Fields. A field this table does not name is refused along with the record.

In a file called mercenaries.json, or any other .json name you like in that folder:

a mercenary_templates record, under content/character/mercenaries

[
  {
    "id": "northern_reach:ditchwater_sapper",
    "display_name": "Ditchwater Sapper",
    "class_id": "skirmisher",
    "background": "Dug siege trenches for whoever was paying, and stopped asking which side it was.",
    "hp_max": 24,
    "morale_start": 70,
    "hire_cost": 180,
    "available_from_day": 6
  }
]

noble_houses

Noble house seed data: the lord, the heir, which settlements answer to the house, and who it counts as rival or ally.

• Status Ready to use
• Folder content/politics/noble_houses
• Records addressed by the id field
• Report modding_noble_house_report
• If a player uninstalls you preserve_inert_reference. A player's standing with a house is recorded against its id. Substituting one would rewrite who they were loyal to without a word.

Fields. A field this table does not name is refused along with the record.

In a file called noble_houses.json, or any other .json name you like in that folder:

a noble_houses record, under content/politics/noble_houses

[
  {
    "id": "northern_reach:house_tidewatch",
    "display_name_key": "VALID_NOBLE_HOUSE_MOD_HOUSE_TIDEWATCH",
    "display_name": "House Tidewatch",
    "strength": "reduced",
    "alignment": "isolationist",
    "corruption_risk": "moderate",
    "is_minor": true,
    "lord_state": "ailing",
    "captain_initial_stance": "suspicious",
    "captain_initial_opinion": 35,
    "apex_ambition": 20,
    "apex_claim_legitimacy": 15,
    "house_power_base": 25,
    "lore_summary": "Kept the coast road open for two hundred years and was paid in salt for it."
  }
]

npc_definitions

Named NPC definitions.

• Status Ready to use
• Walked through in A merchant who stocks it
• Folder content/narrative/npcs
• Records addressed by the id field
• Report modding_npc_report
• If a player uninstalls you preserve_inert_reference. A named person the world remembers is not the same as one who never existed, and relationships point at the id.

Fields. A field this table does not name is refused along with the record.

In a file called npcs.json, or any other .json name you like in that folder:

a npc_definitions record, under content/narrative/npcs

[
  {
    "id": "northern_reach:wandering_herbalist",
    "display_name": "Wandering Herbalist",
    "title": "Travelling Healer",
    "role": "NONE",
    "settlement_id": "old_seat",
    "is_vendor": true,
    "vendor_inventory_id": "northern_reach:herb_stall",
    "personality_tags": [
      "gentle",
      "secretive"
    ]
  }
]

perks

Declarative perks: triggers and effects, with no script handler.

• Status Ready to use
• Folder content/character/perks
• Records addressed by the id field
• Report modding_perk_report
• If a player uninstalls you preserve_inert_reference. A character keeps what they earned. Dropping a perk silently rewrites a build the player spent a run on.

Fields. A field this table does not name is refused along with the record.

In a file called perks.json, or any other .json name you like in that folder:

a perks record, under content/character/perks

[
  {
    "id": "northern_reach:stoneskin",
    "skill": "armour",
    "name_key": "PERK_STONESKIN",
    "description_key": "PERK_STONESKIN_DESC",
    "kind": "lateral",
    "side": "L",
    "col": 0,
    "row": 7,
    "level": 100,
    "parents": [],
    "icon": "northern_reach:stoneskin_icon"
  }
]

relationships

Companion templates, bounded relationship policies, recruitment terms and declarative bonds.

• Status Ready to use
• Folder content/companion/relationships
• Records addressed by the id field
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. A companion's relationship seed remains attached to its id so removing a package cannot silently reset trust, grievances or departure history.

Fields. This family holds more than one kind of record, and each kind is checked against its own list. A field this table does not name is refused along with the record.

A record with kind: bond:

A record with kind: companion_template:

A record with kind: recruit_terms:

A record with kind: relationship_policy:

In a file called relationships.json, or any other .json name you like in that folder:

a relationships record, under content/companion/relationships

[
  {
    "id": "northern_reach:marsh_policy",
    "kind": "relationship_policy",
    "relation_kinds": [
      "comrade",
      "feud",
      "sworn"
    ],
    "bounds": {
      "floor": -100,
      "ceiling": 100
    },
    "bands": [
      {
        "name": "hostile",
        "from": -100,
        "to": -61
      },
      {
        "name": "cold",
        "from": -60,
        "to": -31
      },
      {
        "name": "wary",
        "from": -30,
        "to": -11
      },
      {
        "name": "neutral",
        "from": -10,
        "to": 10
      },
      {
        "name": "warm",
        "from": 11,
        "to": 40
      },
      {
        "name": "trusted",
        "from": 41,
        "to": 70
      },
      {
        "name": "devoted",
        "from": 71,
        "to": 100
      }
    ],
    "max_change_per_event": 12,
    "decay_per_day": 1
  },
  {
    "id": "northern_reach:hire_terms",
    "kind": "recruit_terms",
    "means": "hire",
    "cost": 240
  },
  {
    "id": "northern_reach:marsh_companion",
    "kind": "companion_template",
    "unit": "northern_reach:marsh_unit",
    "recruit": "northern_reach:hire_terms",
    "loyalty": "northern_reach:marsh_policy",
    "starting_regard": 8,
    "leave_below": -60
  }
]

Things, trade and the numbers behind a fight

5 families: combat_balance, goods, items, recipes, vendor_inventories.

combat_balance

Bounded combat balance values that tune existing resolver parameters without adding rules, operations or mechanics.

• Status Ready to use
• Folder content/combat/balance
• Records addressed by the id field
• Report modding_combat_balance_report
• If a player uninstalls you substitute_placeholder. Balance is host-owned definition data rather than player inventory. When its package is absent, the stable canonical combat balance answers and the next load does not carry a second tuning save path.

Fields. A field this table does not name is refused along with the record.

In a file called balance.json, or any other .json name you like in that folder:

a combat_balance record, under content/combat/balance

[
  {
    "id": "northern_reach:coastal_balance",
    "values": {
      "zone_penalty_head": 22,
      "crit_damage_mult": 1.75,
      "friendly_fire_redirect_chance": 0.2
    }
  }
]

goods

Tradeable goods and their economic properties.

• Status Ready to use
• Walked through in A good to sell
• Folder content/economy/goods
• Records addressed by the id field
• Report modding_goods_report
• If a player uninstalls you preserve_inert_reference. A stockpile that names a good nobody supplies is honest. Substituting one would silently change what a player owns.

Fields. A field this table does not name is refused along with the record.

In a file called goods.json, or any other .json name you like in that folder:

a goods record, under content/economy/goods

[
  {
    "id": "northern_reach:spiced_wine",
    "display_name": "Spiced Wine",
    "category": "consumable",
    "decay_tier": "preserved",
    "base_price": 12,
    "weight": 0.5,
    "tags": [
      "luxury",
      "drink"
    ]
  }
]

items

Inventory items, including weapons and armour.

• Status Ready to use
• Walked through in An item to carry
• Folder content/inventory/items
• Records addressed by the id field
• Report modding_items_report
• If a player uninstalls you preserve_inert_reference. The stash keeps naming what was in it, which is the only reason reinstalling gives it back.

Fields. A field this table does not name is refused along with the record.

In a file called items.json, or any other .json name you like in that folder:

a items record, under content/inventory/items

[
  {
    "id": "northern_reach:spiced_wine_bottle",
    "display_name": "Bottle of Spiced Wine",
    "category": "CONSUMABLE",
    "rarity": "UNCOMMON",
    "weight": 0.5,
    "max_stack": 10,
    "base_value": 14,
    "sellable": true,
    "tags": [
      "drink",
      "luxury"
    ]
  }
]

recipes

Crafting recipes: what is consumed, what comes out, where the work happens, what it costs and how likely it is to fail.

• Status Ready to use
• Folder content/economy/recipes
• Records addressed by the id field
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. Nothing in a save names a recipe: a save names the item a craft produced, and that item's own family answers for it. What a withdrawn recipe leaves is a station that no longer offers something, which is reported rather than repaired, because inventing a replacement recipe would put an item in a player's hands that no package supplies.

Fields. A field this table does not name is refused along with the record.

In a file called recipes.json, or any other .json name you like in that folder:

a recipes record, under content/economy/recipes

[
  {
    "id": "northern_reach:salt_cured_ration",
    "display_name_key": "VALID_RECIPE_MOD_SALT_CURED_RATION",
    "recipe_kind": "normal",
    "inputs": {
      "salt": 1,
      "dried_meat": 2
    },
    "output_item_id": "northern_reach:salt_cured_ration",
    "output_count": 3,
    "requires_service": "kitchen",
    "gold_cost": 4,
    "time_cost_minutes": 20,
    "success_chance": 0.95,
    "failure_policy": "lose_fuel",
    "quality_policy": "material_inputs",
    "legality": "legal"
  }
]

vendor_inventories

Vendor stock tables.

• Status Ready to use
• Walked through in A merchant who stocks it
• Folder content/world/vendor_inventories
• Records addressed by the id field
• Report modding_vendor_inventory_report
• If a player uninstalls you drop_optional_presentation. Stock regenerates. A vendor with an empty shelf is a legible state and nothing else points at the row.

Fields. A field this table does not name is refused along with the record.

In a file called vendors.json, or any other .json name you like in that folder:

a vendor_inventories record, under content/world/vendor_inventories

[
  {
    "id": "northern_reach:herb_stall",
    "display_name": "Herbalist's Stall",
    "npc_id": "northern_reach:wandering_herbalist",
    "global_price_multiplier": 1.0,
    "buyback_rate": 0.4,
    "entries": [
      {
        "item_id": "northern_reach:spiced_wine_bottle",
        "kind": "consumable",
        "daily_stock": 3,
        "price_multiplier": 1.1,
        "restock_days": 2,
        "min_standing": 0
      }
    ]
  }
]

Story, quests and the words a player reads

9 families: dialogue, locales, lore, mr_lines, progress, quest_metadata, quest_plans, quests, scenes.

dialogue

Conversations as records: the graph, its beats and the choices standing on them. Three kinds share the family and kind says which. A package writes the conversation, never the words — every line is a locale key — and every condition and consequence is a check or a command this build already performs.

• Status Ready to use
• Folder content/narrative/dialogue
• Records addressed by the id field
• Report modding_dialogue_report
• If a player uninstalls you preserve_inert_reference. A save records what a conversation did — a quest moved, an item changed hands, a truth learned — never the conversation itself, which is over by the time anything is written. When the package leaves, the consequences stay because they were never dialogue's to hold, and the conversation simply is not offered again. Substituting one would put words in a character's mouth that their author never wrote.

Fields. This family holds more than one kind of record, and each kind is checked against its own list. A field this table does not name is refused along with the record.

A record with kind: dialogue_graph:

A record with kind: dialogue_node:

A record with kind: dialogue_node:

A record with kind: dialogue_node:

A record with kind: dialogue_option:

In a file called gate_toll.json, or any other .json name you like in that folder:

a dialogue record, under content/narrative/dialogue

[
  {
    "kind": "dialogue_graph",
    "id": "northern_reach:gate_toll",
    "entry": "northern_reach:gate_open",
    "speaker": "gate_warden",
    "name_key": "TALK_PACK_GATE_TOLL_NAME",
    "description_key": "TALK_PACK_GATE_TOLL_DESC"
  },
  {
    "kind": "dialogue_node",
    "id": "northern_reach:gate_open",
    "graph": "northern_reach:gate_toll",
    "voice": "line",
    "speaker": "gate_warden",
    "line_key": "TALK_PACK_GATE_OPEN"
  },
  {
    "kind": "dialogue_option",
    "id": "northern_reach:opt_pay_the_toll",
    "node": "northern_reach:gate_open",
    "label_key": "TALK_PACK_OPT_PAY",
    "goto": "northern_reach:gate_paid",
    "commands": [
      {
        "step": "pay_coin",
        "coin": 25
      },
      {
        "step": "change_relation",
        "subject": "player",
        "target": "gate_warden",
        "delta": 4
      }
    ]
  }
]

The fixture holds 12 records; 3 are shown.

locales

The words a player reads, as CSV with a column per language: the package's own keys, and the game's own where the package declares the override.

• Status Ready to use
• Folder content/locale
• Report modding_locale_report
• If a player uninstalls you preserve_inert_reference. A save names the record, never the words for it, so a package withdrawn between sessions costs a translation rather than a thing. The key is kept and shows itself, which reads as a missing translation instead of as content that vanished.

Columns. A column this table does not name is refused along with the record.

In a file called words.csv. The file name is half the address and the row's own id is the other half, so two files may hold the same row id without a collision:

a locales file

key,en,it
word_pack:GOOD_FROST_SALT,Frost Salt,Sale di Brina

lore

Codex entries: places, people, events, customs and things a world tells stories about. A loaded entry is not a known entry.

• Status Ready to use
• Folder content/narrative/lore
• Records addressed by the id field
• Report modding_lore_report
• If a player uninstalls you preserve_inert_reference. A codex entry a player read is something they saw. Dropping it erases part of what they know about a world they spent time in, and quests and other entries point at the id.

Fields. A field this table does not name is refused along with the record.

In a file called lore.json, or any other .json name you like in that folder:

a lore record, under content/narrative/lore

[
  {
    "id": "northern_reach:the_drowned_causeway",
    "category": "place",
    "title_key": "STORY_PACK_DROWNED_CAUSEWAY_TITLE",
    "body_key": "STORY_PACK_DROWNED_CAUSEWAY_BODY",
    "era": "before_the_mark",
    "citation_key": "STORY_PACK_CAUSEWAY_CITATION"
  },
  {
    "id": "northern_reach:the_tide_watch",
    "category": "custom",
    "title_key": "STORY_PACK_TIDE_WATCH_TITLE",
    "body_key": "STORY_PACK_TIDE_WATCH_BODY",
    "relates_to": [
      "northern_reach:the_drowned_causeway"
    ]
  }
]

mr_lines

Structured medieval-realism lines, addressed by file and row id rather than by a JSON id field.

• Status Ready to use
• Folder content/medieval_realism/structured
• Report modding_mr_lines_report
• If a player uninstalls you drop_optional_presentation. A flavour line nothing refers to. Dropping it costs nothing and keeping it would show an empty string.

Columns. A column this table does not name is allowed, and has to be a plain value rather than a list or an object.

Every record needs at least one of public_line, public_label, public_summary_line.

These names are refused outright, whatever they hold: unsafe_example, unsafe_reason, audit_note, expected_block_reason, script, scene, resource_path. Some are the audit columns the people making the game write with and the rest are the code-shaped names What a mod can never do refuses everywhere. A record carrying one is refused rather than quietly cleaned up.

In a file called MR_L03_TAVERN_INN_LINES.csv. The file name is half the address and the row's own id is the other half, so two files may hold the same row id without a collision:

a mr_lines file

line_id,tavern_state,speaker_role,tone,public_line,mechanical_hint
northern_reach:tavern_extra_01,evening_rush,innkeeper,welcoming,"Warm bread and a clean cup if you've the coin for it, friend.",food_only

progress

Player progression records: achievements, safe difficulty profiles and run profiles within host rules.

• Status Ready to use
• Folder content/player/progress
• Records addressed by the id field
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. Earned achievements and selected run profiles remain named when their package is absent; silently dropping them would rewrite player history or the run contract.

Fields. This family holds more than one kind of record, and each kind is checked against its own list. A field this table does not name is refused along with the record.

A record with kind: achievement:

A record with kind: difficulty_profile:

A record with kind: run_profile:

In a file called progress.json, or any other .json name you like in that folder:

a progress record, under content/player/progress

[
  {
    "id": "northern_reach:hard_tide",
    "kind": "difficulty_profile",
    "name_key": "DIFF_HARD_TIDE",
    "description_key": "DIFF_HARD_TIDE_DESC",
    "modifiers": {
      "enemy_strength_percent": 140,
      "coin_gain_percent": 80
    },
    "permadeath": true
  },
  {
    "id": "northern_reach:tide_run",
    "kind": "run_profile",
    "name_key": "RUN_TIDE",
    "description_key": "RUN_TIDE_DESC",
    "difficulty": "northern_reach:hard_tide",
    "seed_stream": "tide"
  },
  {
    "id": "northern_reach:held_tide",
    "kind": "achievement",
    "name_key": "ACH_HELD_TIDE",
    "description_key": "ACH_HELD_TIDE_DESC",
    "condition": [
      {
        "when": "days_survived",
        "count": 30
      }
    ],
    "icon": "tower"
  }
]

quest_metadata

Quest metadata records, keyed by quest_id rather than id.

• Status Ready to use
• Folder content/narrative/quest_metadata
• Records addressed by the quest_id field
• Report modding_quest_metadata_report
• If a player uninstalls you preserve_inert_reference. Describes quests that may still be tombstoned themselves; dropping it would leave them undescribed rather than absent.

Fields. A field this table does not name is refused along with the record.

In a file called quests.json, or any other .json name you like in that folder:

a quest_metadata record, under content/narrative/quest_metadata

[
  {
    "quest_id": "northern_reach:tavern_errand",
    "world_reason": "settlement_shortage",
    "quest_role": "recovery",
    "difficulty_band": "standard",
    "urgency_band": "soon"
  }
]

quest_plans

Quest plans as records: the arcs, quests, objectives and endings a package writes out and the game builds into quests of its own. The record form of a quest, next to the authored resources rather than in place of them.

• Status Ready to use
• Folder content/narrative/quest_plans
• Records addressed by the id field
• Report modding_quest_plan_report
• If a player uninstalls you preserve_inert_reference. A plan builds the same quests the game runs, so a withdrawn one leaves the same hole an authored one would. Progress is the one thing a player cannot rebuild: an unresolvable quest is reported and never quietly completed or deleted.

Fields. This family holds more than one kind of record, and each kind is checked against its own list. A field this table does not name is refused along with the record.

A record with kind: arc:

A record with kind: ending:

A record with kind: objective:

A record with kind: quest:

In a file called the_long_winter.json, or any other .json name you like in that folder:

a quest_plans record, under content/narrative/quest_plans

[
  {
    "kind": "arc",
    "id": "northern_reach:the_long_winter",
    "name_key": "northern_reach.arc.the_long_winter.name",
    "stages": [
      "northern_reach:bring_the_grain"
    ]
  },
  {
    "kind": "quest",
    "id": "northern_reach:bring_the_grain",
    "name_key": "northern_reach.quest.bring_the_grain.name",
    "description_key": "northern_reach.quest.bring_the_grain.description",
    "giver": "northern_reach:the_reeve",
    "in_arc": "northern_reach:the_long_winter",
    "objectives": [
      "northern_reach:gather_grain",
      "northern_reach:pay_the_toll"
    ],
    "deadline_days": 30,
    "rewards": [
      {
        "grant": "receive_coin",
        "coin": 250
      },
      {
        "grant": "give_item",
        "item": "northern_reach:reeves_seal",
        "count": 1
      }
    ]
  },
  {
    "kind": "objective",
    "id": "northern_reach:gather_grain",
    "quest": "northern_reach:bring_the_grain",
    "goal": "collect_item",
    "target": "northern_reach:winter_grain",
    "count": 40,
    "name_key": "northern_reach.objective.gather_grain.name"
  }
]

The fixture holds 5 records; 3 are shown.

quests

Authored quest resources, loaded by path rather than parsed as records. A package that wants a quest of its own writes quest_plans.

• Status Checked, not installed yet
• Folder content/narrative/quests
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. Progress is the one thing a player cannot rebuild. An unresolvable quest is reported and never quietly completed or deleted.

This family is loaded by path rather than read as records, and a package cannot ship the file it wants; see What a mod can never do. Write quest_plans instead.

scenes

Staged scenes: the room, who is standing in it and the beats that play out in order. The only content that takes the controls away from the player, which is why a sequence that never reaches end is refused rather than played. Beats and props are names from published lists; nothing here loads a Godot scene, a resource or a script.

• Status Ready to use
• Folder content/narrative/scenes
• Records addressed by the id field
• Report modding_scene_report
• If a player uninstalls you preserve_inert_reference. A save records what a scene did — a name chosen, a quest moved, a door opened — never that it was watched. It is played and finished inside one session, so a package leaving costs the scene and never a consequence of having seen it. Substituting one would stage something the author never wrote under the name of something they did.

Fields. A field this table does not name is refused along with the record.

In a file called scenes.json, or any other .json name you like in that folder:

a scenes record, under content/narrative/scenes

[
  {
    "id": "northern_reach:tollhouse_wake",
    "name_key": "STAGE_PACK_TOLLHOUSE_WAKE",
    "stage": {
      "room": [
        880,
        600
      ],
      "light": "candle",
      "props": [
        {
          "prop": "bed",
          "at": "bedside"
        },
        {
          "prop": "storage",
          "at": "east",
          "label_key": "STAGE_PACK_BELONGINGS"
        },
        {
          "prop": "light_marker",
          "at": "north",
          "light": "candle"
        },
        {
          "prop": "walkway",
          "at": "bedside",
          "to": "door"
        }
      ]
    },
    "cast": [
      {
        "actor": "northern_reach:tollkeeper",
        "name_key": "STAGE_PACK_TOLLKEEPER",
        "sprite": "default",
        "at": "bedside"
      }
    ],
    "beats": [
      {
        "beat": "lock_player"
      },
      {
        "beat": "fade_in",
        "seconds": 2.0
      },
      {
        "beat": "say",
        "actor": "northern_reach:tollkeeper",
        "line_key": "STAGE_PACK_WAKE_1"
      },
      {
        "beat": "wait",
        "seconds": 0.8
      },
      {
        "beat": "say",
        "actor": "northern_reach:tollkeeper",
        "line_key": "STAGE_PACK_WAKE_2"
      },
      {
        "beat": "play_cue",
        "cue": "northern_reach:door_latch"
      },
      {
        "beat": "walk_to",
        "actor": "northern_reach:tollkeeper",
        "anchor": "door"
      },
      {
        "beat": "remove_actor",
        "actor": "northern_reach:tollkeeper"
      },
      {
        "beat": "show_exit"
      },
      {
        "beat": "unlock_player"
      },
      {
        "beat": "end"
      }
    ]
  }
]

How it all looks and sounds

7 families: audio, effects, fonts, images, presentation_bindings, screens, themes.

audio

Sounds a package ships, named by id: music, ambience, effects and voice, each pointing at a file inside its own folder and declaring the role that bounds it.

• Status Validated, nothing consumes it yet
• Folder content/assets/audio
• Records addressed by the id field
• Report modding_audio_report
• If a player uninstalls you preserve_inert_reference. A save names the subject and never the sound for it, so a package withdrawn between sessions costs an atmosphere rather than a thing. The reference is kept and reported: silence with nothing saying why is the state this family exists to avoid.

Fields. A field this table does not name is refused along with the record.

In the file audio.json, which is the one file this folder is read through:

a audio record, under content/assets/audio

[
  {
    "id": "northern_reach:hearth_hum",
    "file": "hearth_hum.wav",
    "codec": "wav",
    "role": "ambience",
    "duration_seconds": 0.25,
    "sha256": "23fc92432963f74bd638f38ea9d7ddb475853f022810bdc8b344269bf43d5830"
  }
]

effects

Weather, dust, sparks and lights, composed out of the templates the host implements. A package names a template and sets parameters inside declared ranges; there is no field anywhere that carries a shader, a scene or a script, which is what lets a stranger's package ask for fire without being able to ask for a program.

• Status Ready to use
• Folder content/assets/effects
• Records addressed by the id field
• Report modding_effect_report
• If a player uninstalls you preserve_inert_reference. Nothing in a save names an effect. The air goes back to what the base game draws when the package leaves, which costs a look and nothing a player owns.

Fields. A field this table does not name is refused along with the record.

In a file called effects.json, or any other .json name you like in that folder:

a effects record, under content/assets/effects

[
  {
    "id": "northern_reach:moor_drift",
    "template": "dust_drift",
    "parameters": {
      "amount": 64,
      "lifetime": 6,
      "scale": 2,
      "wind": 4,
      "colour": "#c8bfa8"
    },
    "priority": 40
  }
]

fonts

Typefaces a package ships, named by id: the file, the sizes it renders at, and the languages whose glyphs it carries. Coverage is declared rather than discovered, because a face missing a language's glyphs does not fail — it draws boxes, and the screen reads as a translation somebody left half finished.

• Status Validated, nothing consumes it yet
• Folder content/assets/fonts
• Records addressed by the id field
• Report modding_font_report
• If a player uninstalls you preserve_inert_reference. Nothing in a save names a font. The interface goes back to the toolkit's own face when the package leaves, which is the only typeface no author has to have chosen.

Fields. A field this table does not name is refused along with the record.

In the file fonts.json, which is the one file this folder is read through:

a fonts record, under content/assets/fonts

[
  {
    "id": "northern_reach:plain",
    "file": "plain.ttf",
    "format": "ttf",
    "sizes": [
      12,
      16,
      24
    ],
    "oversampling": 1,
    "covers": [
      "en"
    ],
    "fallback_font": "Segoe UI",
    "sha256": "613b1d24f9f8b0365a94f01214155af8e87ca72aa6633befd5e0ee05b3dc4122"
  }
]

images

Images a package ships, named by id: icons, portraits and sprite sheets, each pointing at a file inside its own folder.

• Status Ready to use
• Folder content/assets/images
• Records addressed by the id field
• Report modding_image_report
• If a player uninstalls you preserve_inert_reference. A save names items and people, never the picture of one, so an image that stops resolving costs a drawing rather than a thing. The reference is kept and reported: substituting another package's art would show a player something no author chose, and dropping the id silently would make the missing icon look like a rendering fault.

Fields. A field this table does not name is refused along with the record.

In the file images.json, which is the one file this folder is read through:

a images record, under content/assets/images

[
  {
    "id": "northern_reach:salt_pouch",
    "file": "salt_pouch.png",
    "format": "png"
  }
]

presentation_bindings

Which package asset fills which slot on which subject: the icon on an item, the sprite on a unit or a tile, the banner on a faction, for the package's own content and for the base game's alike.

• Status Ready to use
• Folder content/presentation/bindings
• Records addressed by the id field
• Report none of its own; modding_preflight_report covers it
• If a player uninstalls you preserve_inert_reference. A save names the subject — the item, the person, the tile — and never which picture dressed it, so a binding that stops resolving costs a drawing rather than a thing. The reference is kept and reported: the subject goes back to the art the build already had, which is the only answer no author has to have chosen.

Fields. A field this table does not name is refused along with the record.

In a file called bindings.json, or any other .json name you like in that folder:

a presentation_bindings record, under content/presentation/bindings

[
  {
    "op": "add",
    "id": "northern_reach:cloak_icon",
    "subject": "wool_cloak",
    "kind": "item",
    "slot": "icon",
    "cue": "northern_reach:cloak_plain",
    "alternative_key": "item_wool_cloak_icon_alt"
  },
  {
    "op": "add",
    "id": "northern_reach:cloak_icon_winter",
    "subject": "wool_cloak",
    "kind": "item",
    "slot": "icon",
    "cue": "northern_reach:cloak_snowy",
    "alternative_key": "item_wool_cloak_icon_alt",
    "when": {
      "season": {
        "is": "winter"
      }
    }
  }
]

screens

Screen layouts: which sections stand in which panel of a screen the game already has, and in what order. It arranges pieces this build draws and cannot add one — a new screen would need widgets, data sources and click handlers, which together are a programming language.

• Status Ready to use
• Folder content/ui/screens
• Records addressed by the id field
• Report modding_screen_report
• If a player uninstalls you preserve_inert_reference. Nothing in a save names a layout. It decides how a page is drawn while the package is loaded and the page goes back to the arrangement this build ships when it leaves, which costs a look and nothing a player owns.

Fields. A field this table does not name is refused along with the record.

In a file called screens.json, or any other .json name you like in that folder:

a screens record, under content/ui/screens

[
  {
    "id": "northern_reach:character_sheet",
    "screen": "character_sheet",
    "panels": {
      "header": [
        "header"
      ],
      "left": [
        "vitals",
        "combat"
      ],
      "middle": [
        "attributes",
        "skills"
      ],
      "right": [
        "service",
        "weight",
        "background"
      ]
    }
  }
]

themes

Interface palettes as tokens: named colours, sizes and spacings, with the pairs whose contrast a player has to be able to read. Never a scene, a script or a resource path.

• Status Ready to use
• Folder content/assets/themes
• Records addressed by the id field
• Report modding_theme_report
• If a player uninstalls you preserve_inert_reference. Nothing in a save names a theme. The interface goes back to the toolkit's own colours when the package leaves, which is the only palette no author has to have chosen.

Fields. A field this table does not name is refused along with the record.

In a file called themes.json, or any other .json name you like in that folder:

a themes record, under content/assets/themes

[
  {
    "id": "northern_reach:dusk",
    "tokens": {
      "bg_deep": {
        "kind": "colour",
        "value": "#12131a"
      },
      "bg_panel": {
        "kind": "colour",
        "value": "#1b1c26"
      },
      "bg_panel_hi": {
        "kind": "colour",
        "value": "#262838"
      },
      "text": {
        "kind": "colour",
        "value": "#e8e2d0"
      },
      "text_bright": {
        "kind": "colour",
        "value": "#f4efe2"
      },
      "text_mute": {
        "kind": "colour",
        "value": "#6f6a80"
      },
      "border": {
        "kind": "colour",
        "value": "#7f6ab0"
      },
      "border_dark": {
        "kind": "colour",
        "value": "#14151c"
      },
      "border_soft": {
        "kind": "colour",
        "value": "#4a4560"
      },
      "danger": {
        "kind": "colour",
        "value": "#d4564b"
      },
      "success": {
        "kind": "colour",
        "value": "#7fc46a"
      },
      "warning": {
        "kind": "colour",
        "value": "#e0b13c"
      },
      "accent_player": {
        "kind": "colour",
        "value": "#6f97e8"
      },
      "accent_enemy": {
        "kind": "colour",
        "value": "#c94a4a"
      }
    },
    "contrast_pairs": [
      {
        "text": "#e8e2d0",
        "background": "#12131a"
      },
      {
        "text": "#f4efe2",
        "background": "#1b1c26"
      },
      {
        "text": "#e8e2d0",
        "background": "#262838"
      }
    ]
  }
]

What the player controls, and what watches them

3 families: adaptive, input_bindings, settings.

adaptive

Profiles that watch how a run is going and suggest a different setting for it. The output is advice and never a change: a profile that could act would be the one thing a package ships able to alter a run without the player or the host asking, and in a diff it would look exactly like a tuning table. The inputs are a published list of in-game aggregates, every one a count or an average the run already keeps about itself.

• Status Ready to use
• Folder content/player/adaptive
• Records addressed by the id field
• Report modding_adaptive_report
• If a player uninstalls you drop_optional_presentation. No save names a profile. What a profile touched is a multiplier recomputed from the active mutators every time they change, so a withdrawn package stops being consulted and the run goes back to exactly what the player chose. Nothing is kept, so there is nothing to preserve.

Fields. This family holds more than one kind of record, and each kind is checked against its own list. A field this table does not name is refused along with the record.

A record with kind: adaptive_profile:

A record with kind: threshold_set:

In a file called adaptive.json, or any other .json name you like in that folder:

a adaptive record, under content/player/adaptive

[
  {
    "kind": "adaptive_profile",
    "id": "northern_reach:hard_roads",
    "name_key": "ADAPTIVE_HARD_ROADS",
    "description_key": "ADAPTIVE_HARD_ROADS_BODY",
    "policy": "pace_encounters",
    "reads": [
      "battles_won_ratio",
      "days_survived",
      "party_size"
    ],
    "fallback_policy": "event_cadence",
    "confidence_floor_percent": 60,
    "sample_days": 14
  },
  {
    "kind": "threshold_set",
    "id": "northern_reach:hard_roads_lines",
    "profile": "northern_reach:hard_roads",
    "name_key": "ADAPTIVE_HARD_ROADS_LINES",
    "thresholds": [
      {
        "signal": "battles_won_ratio",
        "above": 80,
        "advise": "raise"
      },
      {
        "signal": "battles_won_ratio",
        "below": 35,
        "advise": "lower"
      },
      {
        "signal": "party_size",
        "below": 3,
        "advise": "lower"
      },
      {
        "signal": "days_survived",
        "above": 60,
        "advise": "hold"
      }
    ]
  }
]

input_bindings

Actions of a package's own, with the key it would like. The player decides: a suggestion that lands on a chord they had already bound loses and the action arrives unbound, because a key that quietly does something else is worse than a key that does nothing.

• Status Ready to use
• Folder content/input
• Records addressed by the action_id field
• Report modding_input_report
• If a player uninstalls you preserve_inert_reference. A player's remap stays filed under the action id so reinstalling the package finds the key where they put it. The action itself is taken off the input map when the package leaves, so the binding screen never lists something nothing answers.

Fields. A field this table does not name is refused along with the record.

In a file called bindings.json, or any other .json name you like in that folder:

a input_bindings record, under content/input

[
  {
    "action_id": "northern_reach:call_scout",
    "label_key": "KEY_PACK_CALL_SCOUT",
    "context": "exploration",
    "suggested_keyboard": "f9"
  }
]

settings

Options a player can change, declared rather than drawn. A package says what the option is, what it may be, and where the value lives; the host builds the control. Nothing that crosses this boundary is a Control or a script, which is the only reason a settings menu can show a stranger's options without running their code.

• Status Ready to use
• Folder content/settings
• Records addressed by the key field
• Report modding_settings_report
• If a player uninstalls you preserve_inert_reference. A stored value stays under its key so reinstalling the package finds the player's choice where they left it. What the package leaves behind is a row in a profile nothing reads, which costs nothing and keeps a choice they made.

Fields. A field this table does not name is refused along with the record.

In a file called settings.json, or any other .json name you like in that folder:

a settings record, under content/settings

[
  {
    "key": "northern_reach:patrol_density",
    "type": "int",
    "default": 3,
    "minimum": 1,
    "maximum": 9,
    "scope": "campaign",
    "label_key": "OPTION_PACK_PATROL_DENSITY",
    "help_key": "OPTION_PACK_PATROL_DENSITY_HELP"
  },
  {
    "key": "northern_reach:show_road_names",
    "type": "bool",
    "default": true,
    "scope": "presentation",
    "label_key": "OPTION_PACK_SHOW_ROAD_NAMES"
  }
]

Console shortcuts

These are a shortcut, not a step. Everything below has a place on the Mods screen, which is where the normal path goes and where a player who downloaded your package will look. The console is faster when you are iterating and it is already open, and it exists only in a debug build: a released copy of the game has no console at all, so nothing a package author needs is allowed to live only here.

Start with modding_manifest_report — does the game see your package, and in what state — then modding_preflight_report for one verdict over everything installed. Then the per-family report.

modding_reload reads your files again without restarting. Edit, alt-tab, type it, look. It rebuilds what nothing is holding — bindings, effects and images — and names every family it left alone, because a run is standing on the records a save can name:

what the game prints back

HELD BY THE RUN items: edited files are read on the next load

modding_reload all reads everything and is for a title screen with no run going. modding_condition_report prints what the game can currently answer for a when, and what it cannot.

Offline tools

These tools are for authors and release automation. They are shipped in the public Bonemark source checkout; players installing a released mod do not need Python or Godot. If you are writing a mod, clone the matching build from github.com/tallowgames/Bonemark, keep your working package outside the live player mods folder, and run the commands below from that checkout. The game itself remains the final runtime authority.

Python 3.10 or newer; Godot only for the runtime lane. Keep your package outside the player mods folder and test a copy.

a command line

python tools/modding/new_mod.py --list
python tools/modding/new_mod.py --id my_mod --family goods --family items

Writes a package that validates before you have typed anything: a filled-in mod.json, one working record per family you asked for, and a README with the next two commands. The records come from the fixtures the build already checks for those families, so a starter that stops working fails the same check the fixture does instead of rotting in a template. It refuses to write inside a folder called mods.

a command line

python tools/quality/validate_mod_data.py --root "<mod-root>"
python tools/quality/validate_mod_data.py --strict --root "<mod-root>"

Checks mod.json, family folders, ids, schemas, references, bounds and blocked payloads. --strict turns warnings into failures.

Compare the versioned modding surface

When the game changes, compare the checked-in surface snapshot before updating a package. It contains one digest plus the fields and operations for every public family, so the result says which family changed and why:

a command line

python tools/quality/modding_surface_contract.py --json
python tools/quality/modding_surface_contract.py --before "<previous-build>/game/games/bonemark/modding/data/mod_surface_contract.json" --json

The diff is unchanged, additive or breaking. Breaking reasons are explicit: field_removed, required_added, type_changed, default_changed, constraint_changed, operation_removed and root_changed, format_changed, id_field_changed, catalogue_changed, family_removed and contract_major_changed_without_new_id. Compatible changes name field_added, required_removed, operation_added or family_added. The command without --before also audits the checked-in baseline. If the current surface moved, the audit fails until a maintainer reviews the exact before/after digests in tools/quality/modding_surface_contract_changes.json; a breaking change must also record every reason, the decision, the migration note and the reviewer. Promoting an intentionally reviewed snapshot is explicit:

a command line

python tools/quality/modding_surface_contract.py --write-baseline

This is a maintainer/release check; mod authors only need the --before comparison, and players installing a released package do not need to run it.

a command line

python tools/modding/mod_test_host.py --root "<mod-root>" --repo-root "<framework-root>" --json

Reads the manifest, dependencies, compatibility and load order without launching Godot and without executing anything from your package.

It never opens a content file. That is the division of labour — the host answers will these packages load together, the validator answers is this record right — but it means a package the validator refuses can still compose cleanly here. Measured on fourteen deliberately broken packages, the two disagree on every refusal: the host stages all fourteen, refused empty, including one carrying scripts/payload.sh that only the validator finds. Composing is not the same as being safe to install. Run both before you publish. Repeat --root when your test set is split across folders; the host then composes the complete set in one deterministic plan.

a command line

python tools/modding/mod_test_matrix.py --repo-root "<framework-root>" --root "<mod-root>" --godot "<godot-exe>" --require-runtime --report "mod_test_matrix.json"

Runs the validator, the test host, every ready-to-use family fixture and the Godot runtime lane. Drop --require-runtime if you have no Godot; the report then says runtime proof was skipped rather than passed.

For a composed set, repeat the option:

a command line

python tools/modding/mod_test_matrix.py --repo-root "<framework-root>" --root "<mod-a>" --root "<mod-b>" --godot "<godot-exe>" --require-runtime

The report keeps one result per root and adds composed_set for the complete set. That block is where cross-package conflicts, duplicate IDs and dependency errors are proven. A package being clean on its own is not proof that the set will load together. The report also includes surface_contract, the current per-family contract version and digest audit, so a matrix cannot be green while the repository's compatibility snapshot is stale. With --require-runtime, read runtime.reachability.loaded_families and runtime.reachability.reachable_families. The first says that the composed records were loaded; the second is only populated when a real player-facing route in the Godot probe consumed them. runtime.reachability.observations keeps the package, family, record id, route and status for each row, while unreachable lists loaded rows that still have no route. A family can be validated and staged yet still be absent from reachable_families — “loaded” is not the same as “a player can reach it”.

Every command above is checked against the tools themselves when this page is built: the script must exist and every option must be one it accepts.

Every diagnostic code

Never read this in order. It is here so a code you meet in a report is a question with an answer — one short lower-case word like asset_missing. Paste one into the search box at the top of this page.

Some codes belong to machinery a package cannot reach yet. They are here anyway: a code you cannot trigger costs a line you never read, and a code that is missing costs an evening.