# Make your first mod

Kinbarrow is in development. [Discord](https://discord.gg/pNswDHccMD) gets builds first. Data formats may change. This reference's `latest` follows `main`.

The Embers starter adds Rain of Embers and an Ember Wand that casts it. It also renames the base bread to Emberbread. Download [embers.zip (1,234 bytes)](/modding/latest/downloads/embers.zip) and extract it into `mods/` beside your game's `data/` folder. It is disabled until you enable it.

## Put the files in place

A mod mirrors the `data/` layout. The loader looks for `mods/` beside the `data/` directory it resolved. The download contains:

```text
mods/
  embers/
    goods/bread.ron
    magic_items/ember_wand.ron
    spells/rain_of_embers.ron
```

## Enable it

Write this ordered list in `mods/enabled.ron`:

```ron
["embers"]
```

An unlisted folder does nothing. Later mods win when they replace the same base path. A listed folder must exist. An absent default manifest means vanilla.

For a separate list, set `RPGPT_MODS_MANIFEST` to a manifest file. A relative path resolves from the directory containing `data/`; an explicit missing file is an error. If `mods/enabled.dev.ron` exists, it takes precedence over `mods/enabled.ron`. The environment selector takes precedence over both.

## Read the mod

These files are read from the starter mod when this site builds.

### mods/embers/goods/bread.ron

```ron
Good(
    source: Original,
    id: "bread",
    name: "Emberbread",
    weight_lb: 1.0,
    satisfies: Some("hunger"),
    spoilage_days: Some(30),
    acquisition: None,
    quality_class: None,
    material: None,
    recipes: [
        Recipe(building: "ovens", rate: 0.7, ability: Some("int"), tool: Some("cooks_utensils"), tier: Apprentice, inputs: [(Good("flour"), 1)], hours: 2, yield: 1, requires_terrain: ["arable"]),
        Recipe(building: "ovens", rate: 0.7, ability: Some("int"), tool: Some("cooks_utensils"), tier: Apprentice, inputs: [(Good("grain"), 2)], hours: 2, yield: 1, forbids_terrain: ["arable"]),
    ],
)
```

### mods/embers/magic_items/ember_wand.ron

```ron
MagicItem(
    source: Original,
    id: "embers:ember_wand",
    name: "Ember Wand",
    rarity: Uncommon,
    equip_slots: [MainHand, OffHand],
    max_charges: 3,
    recharge: LongRest,
    activations: [MagicActivation(
        payload: Spell(spell: "embers:rain_of_embers"),
        consumption: Charge,
        slot_level: Some(2),
        save_dc: Some(13),
    )],
)
```

### mods/embers/spells/rain_of_embers.ron

```ron
Spell(
    source: Original,
    id: "embers:rain_of_embers",
    name: "Rain of Embers",
    level: 2,
    school: "evocation",
    classes: ["sorcerer", "wizard"],
    cast: Action,
    range: Feet(60),
    components: (verbal: true, somatic: true, material: false),
    delivery: Save(ability: "dex", on_save: Half, area: Some(Sphere(radius_ft: 20))),
    effects: [Damage(dice: "3d6", kind: "fire")],
    cantrip_steps: false,
    upcast: DicePerSlot("1d6"),
)
```

## Add or override

The new spell declares `embers:rain_of_embers`. The new item declares `embers:ember_wand`. The namespace is the mod folder's name; filenames stay bare because a colon is not portable in a filename. This rule applies to id-keyed collections such as spells and magic items. Tables have their own file layout in the [content tree contract](/modding/latest/content-tree/).

To override, match a base file's relative path exactly and keep its bare id. Our `goods/bread.ron` replaces the Original base file at that path. Only its display name changes. The loader replaces the whole file; it does not merge individual fields.

## Credit your work

Use `source: Original` and a plain `.ron` suffix for your own work. Reserve `.srd.ron` and `.srd52.ron` for material from those SRDs, with the matching `Srd51` or `Srd52` source and attribution. The runtime mod loader requires a source but does not enforce suffix agreement. This starter contains only Original content and overrides no SRD file.

## Refer to other content

The wand's `Spell` payload uses the full id `embers:rain_of_embers`. Base references stay bare: the spell names `wizard` and `sorcerer`; the bread recipes name `ovens` and `flour`. A reference must resolve in the effective tree or validation fails.

## Art and saves

For furnishing art, put files under your mod's `art/` folder. Art paths are relative to that folder. Enabled mods are searched in reverse load order, then `data/art/`. Missing furnishing art fails loading. This starter needs no images.

A save records the effective content hash. Changing files or enabled overrides can change that hash, and a mismatched save refuses to load. Keep the content used by a save together. Changing only the manifest list does not necessarily change the effective content.

## Validate it

From the repository root, with Embers enabled, run:

```sh
cargo run -q -p rpgpt-engine --bin validate_data
```

A packaged build has the same check at `rpgpt-server --check-data`. Here is the source command's output with only Embers enabled, captured on 23 Oct 2026. The counts grow with the base content. Machine paths are shortened; the warning lines are omitted.

```text
content: data_dir="<install>/data" manifest="<install>/mods/enabled.ron" mods=["embers"] dataset_hash=fe85ab0d4abaf020
mods enabled (load order): ["embers"]
data/ OK: 67 goods, 22 buildings, 19 professions, 12 backgrounds, 9 races, 38 weapons, 13 armor, 89 creatures, 12 classes, 4 feats, 84 spells, 19 conditions; 15 warning(s)
campaign "thornwood" OK: 1 town(s)
```

### If an id has no namespace

Changing the spell's id to `rain_of_embers` while leaving it in the mod produces this refusal. These lines were captured from a scratch copy with that one edit:

```text
data/ failed to load (2 error(s)):
  ERROR: magic_items/embers:ember_wand: activation spell "embers:rain_of_embers" not in data/spells
  ERROR: spells/embers:rain_of_embers.ron: id "rain_of_embers" != "embers:rain_of_embers" — a mod's new content declares its namespaced id (id: "embers:rain_of_embers"); only an override of a base file keeps the bare id
```

Restore `id: "embers:rain_of_embers"` and validate again.

## See the change

Start a fresh Thornwood world with Embers enabled. Greyharbor's Brined Gull starts with Emberbread where Bread was. The added spell and wand load as content. Enabling the mod alone does not put the wand in your inventory.
