Start here#

This guide shows you how to change BELOW THE IRON by editing its JSON files: new item bonuses, new creature behaviour, new spells and new terrain. You will have a working change in five minutes.

What modding means today#

Modding today means editing the JSON files in public/config/. The game reads and checks them every time it starts. If something is wrong, it refuses to start and names the file and the key at fault.

You cannot invent new kinds of things in JSON. You can combine the ones the game already knows: it knows 55 values, 50 events, 24 conditions and 33 actions. The catalogue lists them all.

What you can change#

• Items: affixes (the bonuses on a magic item), item sets, enchantments, forge catalysts, consumables. See Items.
• Creatures: how a monster fights, its traits, abilities, elite versions and variants. See Creatures.
• Magic: syllables, spells, reagents, statuses, reactions between spells, new damage elements. See Magic.
• Terrain: what a cell is made of, doors, devices, and how spells change cells. See Terrain.
• Shared rules: dodge limits, character attributes and progression, in combat.json and character.json.

Text shown to the player lives in public/config/locales/, one file per language.

The game reads fifteen files in public/config/. Each definition has one owner. Edit it there; copying it into another file is an error. A missing value never makes the game search another owner.

Your first mod in 5 minutes#

Goal: a ring and amulet bonus called "of the Gourmet" that makes you hungry more slowly. You reuse the existing satiety effect, which cuts the hunger you use up.

Step 1: Open the file#

Open public/config/equipment.json and find the affixes list. An affix is one bonus that can appear on an item.

Step 2: Paste the affix#

Add this object to the end of the affixes list (mind the comma after the previous entry):

{
  "id": "of-the-gourmet",
  "label": "AFFIX_NAME_OF_THE_GOURMET",
  "position": "suffix",
  "family": "satiety",
  "kinds": ["ring", "amulet"],
  "tiers": [[3, 5], [5, 8], [8, 12], [12, 16]],
  "weight": 5,
  "minLevel": 1,
  "group": "satiety"
}

• family names the effect that does the work. Here it is satiety.
• tiers gives one value range per quality step. A tier-1 item gets 3 to 5, a tier-4 item gets 12 to 16.
• weight is how often the affix is drawn compared with others.

Step 3: Name it in every language#

label is a text key, not text. Add "AFFIX_NAME_OF_THE_GOURMET" to each of the nine files in public/config/locales/, next to AFFIX_NAME_OF_THE_WELL. In English, for example: "AFFIX_NAME_OF_THE_GOURMET": "of the Gourmet",.

Step 4: Start the game#

Run npm run dev and open the address it prints. If the game starts, your file is valid. If not, the error names the file and the key to fix; Troubleshooting explains the messages.

Step 5: See the result#

In the game, open the Debug tab of the side window, then its Equipment sub-tab. Create a ring that carries the affix and equip it. The rules view ("active modifiers and listeners of the player, by source") now shows a source called affix:<item id> with a hunger.satiety modifier at the value of the tier that was drawn.

Where to go next#

• How it works

  The two ideas behind every rule: modifiers and listeners.

• Cookbook

  Ready-made recipes, grouped by what you want to achieve.

• Items

  Affixes, sets, enchantments and the forge.

• Creatures

  Change how monsters fight.

• Magic

  Spells, reagents and reactions.

• Terrain

  Cells, doors and devices.

• Troubleshooting

  Validator messages and how to fix them.

• Catalogue

  Every value, event, condition and action.