# Ravenswatch Mod Manager — Mod authoring

Everything needed to build a Ravenswatch mod with the Ravenswatch Mod
Manager (RSMM), as one plain-text file. Ravenswatch has no official mod
support: RSMM is the toolchain, and the format below is the only one the
game will load.

Three rules that override any assumption carried in from other games:

1. A mod ships DATA, not code — a `manifest.toml` with `[[content]]` and
   `[[patch]]` blocks, plus assets the SDK emits. A bespoke script is never
   the deliverable, and `rsmm lint` fails any `*.py` in a mod that is not a
   sanctioned lifecycle hook.
2. Mod Lua never touches engine internals — no raw game addresses, no
   `_internal`, no `peek`/`poke`/`read_*`/`write_*`. Only the high-level
   `R.*` API. Also lint-enforced.
3. Content kinds carry confidence ratings. Registering a kind rated below
   `confirmed` requires opting in with `sdk.Mod(..., experimental=True)`.

Verify with `rsmm lint`, install with `rsmm apply`, roll back with
`rsmm restore --all`. Every command that names a mod takes its ID, not a
path: `rsmm lint MyMod`, never `rsmm lint mods/MyMod`.

Two facts that are wrong in most models' priors, stated here because they
are what a wrong answer is built on:

- Ravenswatch is NOT a Unity game. Native C++ engine, no mono runtime, no
  `Assembly-CSharp.dll`. BepInEx, Harmony and DLL plugins do not apply.
- A mod's Lua entry point is `init.lua` at the mod root, and the API is
  `R.*` (`local R = require "rsmm"`). There is no `rsmm.call()`.

Reverse-engineering notes on the game engine are NOT included here; they are in https://docs.rsmm.me/llms-full.txt.
Page index: https://docs.rsmm.me/llms.txt · Source: https://docs.rsmm.me


---

# Architecture

> How RSMM applies mods without fighting anti-tamper — the threat model and design.

Source: https://docs.rsmm.me/architecture/overview/

:::note
Where this document mentions `tools/<script>.py`, the current location is
`src/rsmm/cli/<script>.py` or `src/rsmm/engine/<script>.py`; the CLI
surface is `./rsmm <name>`. See also [SETUP.md](/contributing/setup/) for the repo
layout.
:::

## Threat model / scope

Two goals, in priority order:

1. **Don't break the game.** Mod application must be deterministic and
   fully reversible.
2. **Don't fight anti-tamper.** Ravenswatch.exe has a protector. Asset mods
   never touch the running game: they replace files at install time, so no
   anti-tamper code path runs. Only Lua mods need the optional loader, which
   hooks the game at function entries (see
   [Anti-tamper protector](/reverse-engineering/protector/)).
3. **Treat a downloaded mod as hostile input.** A mod archive comes from
   a third party over the network. It must not be able to write outside
   `mods/`, delete anything, ship an executable, or exhaust the disk.

### Untrusted archives

Everything that unpacks a downloaded mod — `rsmm install`, `rsmm update`
and the desktop bridge's `json install-mod` — goes through one extractor,
`rsmm.sdk.archive`. It was previously three separate copies that had
drifted apart, which is why the rules now live in a single module:

| Guard | What it stops |
|-------|---------------|
| Component-wise containment check (`is_relative_to`, not `startswith`) | Zip-slip, including escapes into a sibling dir sharing the prefix (`mods/` → `mods-evil/`) |
| Members read with `ZipFile.open` and written as regular files | A symlink member becoming a real symlink that a later member writes through |
| `safe_dir_name` on every id/slug joined onto `mods/` | An archive whose members all start with `../` yielding the mod id `..`, which `--force` then deletes |
| Entry count / uncompressed size / compression-ratio caps | Decompression bombs |
| `DANGEROUS_EXTENSIONS` refusal | Mods shipping `.exe` / `.dll` / `.ps1` / `.sh` payloads — including under `_root/`, which has no exemption |
| Every `_root/` member reported | Silently overwriting files in the game install root |
| Staged unpack + swap into place | A corrupt or rejected download destroying a working install as a side effect of failing |

Transport is https-only (`file://`, and plain HTTP against loopback, are
allowed for offline installs and local development). Downloads are size
capped and time bounded. Integrity is SHA-256 from `repo.json` plus an
optional Ed25519 signature — see `rsmm.sdk.repo`.

## How v1 works

The engine loads every cooked asset from
`<install>/DarkTalesResources/_Cooking/<encoded>`. `<encoded>` is the
asset's filename run through a fixed Caesar substitution cipher (decoder:
`tools/find_iyg.py`). The cooked bytes have no checksum, signature, or
embedded path; any byte-compatible file at the encoded path is accepted.

Therefore v1 is purely an *install-time file applier*:

1. `tools/find_iyg.py` builds the `encoded -> decoded` map by walking
   `DarkTalesResources/UsedRscList.ot` and applying the cipher.
2. `tools/apply_mods.py` walks `mods/`, parses each manifest, collects
   override files, and resolves each decoded path to its encoded path.
3. For each new override: back up the original cooked file to
   `<file>.rsmm.bak`, copy the mod's file into place.
4. For each previously-active override no longer wanted: restore from
   `.rsmm.bak`, delete the backup.
5. State persists in
   `<install>/DarkTalesResources/_Cooking/.rsmm_state.json`.

```mermaid
flowchart LR
    A["mods/&lt;id&gt;/<br/>manifest.toml + assets"] --> B["apply_mods.py"]
    M["UsedRscList.ot"] -->|"Caesar cipher<br/>(find_iyg.py)"| C["asset_map.json<br/>decoded → encoded"]
    C --> B
    B -->|"back up original"| D["&lt;file&gt;.rsmm.bak"]
    B -->|"copy override"| E["_Cooking/&lt;encoded&gt;"]
    B --> F[".rsmm_state.json"]
    G["./rsmm restore --all"] -->|"restore from .bak"| E
```

No DLL is loaded into the game process. No engine API is hooked. No
anti-tamper code path runs. Removing the manager is `--restore-all`.

## Mod format

```
mods/<id>/
  manifest.toml
  assets/
    <decoded path>/<file>      e.g. Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt
```

```toml
[mod]
id          = "..."
name        = "..."
version     = "..."
author      = "..."
description = "..."
enabled     = true
```

## State + backups

```
DarkTalesResources/_Cooking/.rsmm_state.json
{
  "version": 1,
  "active": {
    "<encoded path>": {
      "mod":       "<mod id>",
      "src_sha1":  "<sha1 of mod file>",
      "orig_sha1": "<sha1 of original cooked file>"
    },
    ...
  }
}
```

Backups live next to their originals as `<file>.rsmm.bak`. The applier
diffs the wanted set against the active set on every run; a no-op run is
a no-op.

## Asset map

`asset_map.json` is generated by `tools/find_iyg.py`. The cipher is in
that script (`LOWER`, `UPPER`, `SYMBOLS` tables). Confirmed clean as of
2026-05-14: 40,687 paths, no inconsistencies. Regenerate after a game
update if `UsedRscList.ot` changes.

## What v1 cannot do

- **Edit top-level uncooked files** (ApplicationSettings.ot,
  EngineSettings.ini, UsedRscList.ot). These are loaded from outside
  `_Cooking/` and are special-cased by the engine; v1 doesn't manage
  them. Manual edits work, no tooling around them yet.
- **Build a cooked file from nothing.** New items, heroes, enemies and
  the like are made by the SDK content kinds, which cook a copy of a shipped
  file and edit it (see [Authoring mods](/guides/modding/)). A free-form
  text-`.ot` -> binary-`.gen` re-encoder for arbitrary classes is still
  not built.
- **Toggle mods in-game.** v1 is install-time only.

## v2: in-game UI (research)

The end goal is a Mods entry inside the game's actual book menu, opening
a native-styled mod list. Path forward:

1. `tools/ot_decoder.py` is structural (header + class table + section
   ranges) but does not decode object bodies. Extending it requires the
   per-class serialization schemas. Best Rosetta we have:
   `ApplicationSettings.ot` (text) and the 523 `*.UsedRscCache.ot` files
   (per-asset cooking-pipeline manifests with plaintext bucket / path /
   root-class triples).
2. Build a text-`.ot` -> binary-`.gen` re-encoder, round-trip a known
   simple file (e.g. one of the 224-byte `EnemyCampDifficultyDefinition`
   files: two floats, that's the whole body).
3. Modify the MainMenu cooked asset
   (`_Cooking/Oi/KgxqJdv/HgdzHqzw.lqkql.ri.KgxqFiuqgx.yqz`,
   decoded `Ot/GameUis/MainMenu.level.ot.GameStream.gen`). The menu is
   an `oCGameStream` containing one `BOOK_SPAWNER` referencing
   `Book_Menu\Book_Mesh_Controller.entity.ot`. The actual tab/page
   logic lives in `Book_Mesh_Controller`, which contains
   `oCDtEntityCpnt3DBookControllerSettings` and 74 other classes.
4. Inject a "Mods" tab entry; route the click event back into either an
   external manager or (further out) a DLL we re-introduce once we have
   a viable injection path that survives anti-tamper.

See `FINDINGS.md` for the full reverse-engineering record.

## The loader, and a parked subsystem

- `src/loader/` — winhttp.dll proxy + MinHook + Lua 5.4. This is the runtime for
  Lua-scripted mods, installed with `rsmm install-loader` and updated with
  `rsmm update-loader`. Asset-only mods do not need it.
- `layer/` — Vulkan implicit layer that surfaces an ImGui overlay
  without in-process hooks. Parked: it builds, but pressure-vessel strips
  `VK_LAYER_PATH` so the user must drop the manifest into
  `~/.local/share/vulkan/implicit_layer.d/`. Gated by `RSMM_OVERLAY=1`
  via `enable_environment` in the layer manifest.

---

# Content kinds (registries)

> How RSMM registers new content by cloning vanilla bases — the Minecraft registry analog.

Source: https://docs.rsmm.me/concepts/content-kinds/

A **content kind** is a typed builder that clones a vanilla **base** and emits
a new definition. This is RSMM's analog of a Minecraft registry: you don't
hand-author engine bytes, you declare *"a new item like `Knife`"* and the SDK
materializes it.

```python
import rsmm.sdk as sdk
m = sdk.Mod(id="RubyMod", name="Ruby Mod")
m.item("RubyDagger", base="Knife", name="Ruby Dagger")
m.enemy("FastRat", base="Rat", name="Fast Rat")
m.commit()
```

Available kinds include `item`, `enemy`, `boss`, `hero`, `map`, plus the
asset kinds `texture` and `model`, and the grouping kind `tag`. The full,
current list and signatures are in the generated
[SDK reference](/reference/sdk-api/builder/).

## Confidence — the RSMM twist

Minecraft registries always work; RSMM kinds describe a **reverse-engineered**
byte format, so each kind carries a confidence:

| Confidence | Meaning | Requirement |
|---|---|---|
| `confirmed` | Emitted bytes verified in-game | usable directly |
| `experimental` | Plausible, not fully verified | needs `Mod(..., experimental=True)` |
| `guess` | Schema partially understood | needs `experimental=True`; may crash |

`rsmm lint` enforces the opt-in gate, so you can't accidentally ship a `guess`
kind without acknowledging the risk.

:::tip[Minecraft analogy]
`m.item(base="Knife")` ≈ `DeferredRegister` registering an item that copies an
existing one's properties. The `base` is the vanilla prototype; `**fields`
override specific values. See [Coming from Minecraft](/concepts/from-minecraft/).
:::

## Common problems

:::caution
- **`kind 'x' is 'experimental'` error.** Add `experimental=True` to your
  `Mod(...)` — and expect to test in-game.
- **New content doesn't appear in-game.** Most kinds also need engine-side
  registration (e.g. a versiondef / UsedRscList entry). The applier handles
  the confirmed pipelines; experimental kinds may not be wired end-to-end.
- **Unknown base.** The `base` must name a real vanilla definition. Browse
  candidates with the relevant `rsmm` listing command.
:::

## Related

- [Tags](/concepts/tags/) — group content across mods.
- [Mods ship data, not code](/concepts/data-not-code/) — why this is declarative.
- [Authoring mods](/guides/modding/) — the full how-to.

---

# Mods ship data, not code

> Why RSMM mods are declarative manifests, and where discovery scripts belong.

Source: https://docs.rsmm.me/concepts/data-not-code/

The central RSMM rule, and the biggest departure from Minecraft modding:

> **A mod's deliverable is data — a `manifest.toml` plus assets the SDK emits
> — never a bespoke script.**

This is the data-pack / datagen philosophy taken all the way. Minecraft splits
mods into "code mods" (Forge/Fabric jars) and "data packs"; RSMM aims to make
*everything* expressible as data, with scripted behaviour as the narrow
exception (Lua via the loader).

## What this means in practice

- A finished mod is a `manifest.toml` with `[[content]]` / `[[patch]]` blocks
  plus cooked assets — produced by `rsmm apply`, not by a script you ship.
- One-off Python to reverse a byte layout is fine as throwaway **discovery**,
  but the capability must then graduate into `rsmm.sdk` (a kind builder, an
  engine cooker, or the apply pipeline) and the mod re-expressed declaratively.
- `rsmm lint` enforces this: any `*.py` in a mod that isn't a sanctioned
  lifecycle hook (e.g. `on_disable.py`) fails CI.

```mermaid
flowchart LR
    D["throwaway discovery script<br/>(reverse a byte layout)"] -->|"graduate"| S["rsmm.sdk capability<br/>(kind / cooker / pipeline)"]
    S --> M["declarative manifest.toml"]
    M -->|"rsmm apply"| G["cooked assets installed"]
```

:::tip[Why bother]
Declarative mods are inspectable, mergeable (two mods can `[[patch]]` the same
file), survive game updates better, and don't run arbitrary code on a user's
machine at install time. The full custom-item pipeline already lives in the
SDK end-to-end, so a new item is *manifest + `rsmm apply`* with no script.
:::

## Common problems

:::caution
- **`rsmm lint` fails on a `.py` in my mod.** Move the logic into the SDK and
  delete the script, or rename it to a sanctioned hook if it truly is one.
- **"But I need custom behaviour at runtime."** That's the loader's job:
  Lua + the [event bus / symbol map](/concepts/mappings/), not a Python file
  in the mod.
:::

See [Authoring mods](/guides/modding/) and the
[SDK design notes](/guides/sdk/).

---

# Coming from Minecraft modding

> A Rosetta stone mapping Forge/Fabric/NeoForge concepts to their RSMM equivalents.

Source: https://docs.rsmm.me/concepts/from-minecraft/

RSMM was deliberately shaped around the Minecraft modding mental model. If
you have written a Forge, Fabric, or NeoForge mod, most of what you know
transfers — only the words and the file formats change.

:::tip[The one big difference]
Minecraft mods ship **code** that runs inside a modded game. RSMM mods ship
**data** that RSMM bakes into the game's own cooked-asset files — no modded
runtime required for most content. Scripted behaviour is the exception, via
the optional loader DLL. See [Mods ship data, not code](/concepts/data-not-code/).
:::

## Rosetta table

| Minecraft modding | RSMM equivalent | Notes |
|---|---|---|
| `fabric.mod.json` / `mods.toml` | `manifest.toml` | Mod metadata + declared content. |
| Registries / `DeferredRegister` | [Content kinds](/concepts/content-kinds/) (`Mod.item`, `Mod.enemy`, …) | Register a definition cloned from a vanilla base. |
| Tags (`#minecraft:logs`) | [Tags](/concepts/tags/) (`Mod.tag`) | Cross-mod, append-only named groups. |
| Mappings (Yarn / MCP / Mojmap / SRG) | [Symbol map](/concepts/mappings/) (`data/symbols.json`) | Semantic names → engine functions/globals. |
| Access Transformers / Access Wideners | `callable` symbols (`engine::Name()`) | Exposes raw engine functions as typed calls. |
| Mixins (SpongePowered) | Loader DLL hooks + [event bus](/reference/symbols/) (`R.on`) | Runtime behaviour injection (MinHook + Lua). |
| Data generation (datagen) | SDK emitters (`engine/*_cook`) | RSMM materializes cooked bytes at `apply` time. |
| Data packs | Declarative `[[content]]` / `[[patch]]` | No code; merged by the applier. |
| Resource packs | Texture/asset overrides | Work **without** the loader DLL. |
| Lang files (`en_us.json`) | i18n (`lang/<locale>.toml`) | Merged into the game's text banks. |
| Mod loader (Fabric Loader / Forge) | RSMM + `winhttp.dll` loader | Asset mods need only RSMM; Lua needs the loader. |
| Game-version compat (`1.20.1`) | `target_game_build` + pattern resolver | Byte-pattern resolution survives game updates. |
| Inter-mod APIs (`@ApiStatus`, IMC) | `R.api.expose` / `R.api.require` | Version-gated published APIs. |
| Dependencies (`depends`/`recommends`/`suggests`/`breaks`) | `requires` / `recommends` / `suggests` / `conflicts` | Semver ranges + load-order, cycle & conflict checks before apply. |

## How the analogies hold up

### Registries → content kinds

In Forge you `register` a new `Item` into a registry. In RSMM you clone a
vanilla **base** and register a new definition:

```python
import rsmm.sdk as sdk
m = sdk.Mod(id="RubyMod", name="Ruby Mod")
dagger = m.item("RubyDagger", base="Knife", name="Ruby Dagger")
m.commit()
```

Like a registry, each kind validates and de-dupes ids. Unlike Minecraft,
each kind carries a **confidence** (`confirmed` / `experimental` / `guess`)
because the byte format is reverse-engineered — see
[Content kinds](/concepts/content-kinds/).

### Mappings → the symbol map

Minecraft's obfuscated names are made readable by a mappings file. RSMM's
engine functions read as `FUN_140xxxxxxx` in a fresh disassembly;
`data/symbols.json` is the canonical map to semantic names, and — like a
*refmap* — it resolves by **byte pattern**, not fixed address, so names
survive game patches. See [Mappings](/concepts/mappings/).

### Mixins → loader hooks

Where you would write a Mixin, RSMM detours the function natively in the
loader DLL or subscribes to a generated event from Lua
(`R.on("<event>", cb)`). Both are opt-in and only load when the loader is
present.

### Dependencies → manifest deps + load order

`fabric.mod.json`'s `depends` / `recommends` / `suggests` / `breaks` map
one-to-one onto manifest fields, with the same hard/soft severities and the
same npm-style semver ranges (`>=1.2 <2.0`, `1.2.x`, `^1.2`, `~1.2`, `*`):

```toml
[mod]
id = "RubyExpansion"
version = "1.3.0"
requires   = ["RubyCore >=1.2 <2.0"]   # depends:    hard — apply refuses if unmet
recommends = ["BetterLoot ^1.0"]        # recommends: warn only
suggests   = ["SoundPack"]              # suggests:   info only
conflicts  = ["OldRubyMod"]             # breaks:     hard — refuse if both enabled
replaces   = ["RubyMod"]                # auto-disables the older mod
load_order = 90                          # lower loads earlier (default 100)
```

Before the applier touches the game, RSMM builds the dependency graph: it
errors on a missing/out-of-range `requires`, a hard `conflicts`, a `requires`
cycle, or a duplicate id; warns on a missing `recommends`; and computes a
deterministic load order (`load_order`, then `priority`). Run `rsmm doctor` to
see the report. This is the loader's "won't launch with unsatisfied
dependencies" check, done ahead of time.

## Where to go next

- [Your first mod](/getting-started/first-mod/) — the Minecraft "make a
  block" equivalent.
- [Authoring mods](/guides/modding/) — the full how-to.
- [Concepts](/concepts/content-kinds/) — the understanding-oriented pages.

---

# The symbol map (mappings)

> data/symbols.json maps semantic names to engine functions — RSMM's Yarn/MCP/Mojmap.

Source: https://docs.rsmm.me/concepts/mappings/

Disassemble `Ravenswatch.exe` and every function reads as `FUN_140xxxxxxx`.
RSMM's **symbol map** (`data/symbols.json`) is the canonical, human-authored
map from semantic names (`MagicalObject_SpawnAllObjects`) to those engine
functions, globals, and events. It is exactly the role Yarn / MCP / Mojang
mappings play for Minecraft.

```mermaid
flowchart LR
    S["data/symbols.json<br/>(canonical, hand-authored)"]
    S -->|"rsmm symbols gen"| H["loader C++ (Sym::, engine::Name())"]
    S -->|gen| L["Lua resolver"]
    S -->|gen| P["Python constants"]
    S -->|gen| D["docs/SYMBOLS.md + site"]
    S -->|"ghidra-export"| G["your Ghidra DB names"]
```

## Why it survives game updates

Minecraft mappings break when names change between versions; RSMM resolves by
**byte pattern**, not fixed address — like a Mixin refmap that re-finds its
target. Each symbol's `status` tells you how solid it is:

| Status | Meaning |
|---|---|
| `ok` | Resolvable now by byte pattern (survives updates) |
| `va` | Base-relative absolute address (data globals) |
| `unverified` | Documented in an older corpus, address not re-confirmed |

Resolution forms, most to least version-resilient: **raw** (byte pattern),
**anchor** (parent pattern + offset for inlined routines), **va**
(base-relative absolute).

## Layers built on top

Like Forge/Fabric build APIs over mappings, RSMM generates:

- **Typed calls** — a symbol with a `cabi` gets `engine::Name(...)` in C++
  and a Lua resolver entry (the Access-Transformer analog).
- **Event bus** — `kind="event"` symbols generate `R.on("<lua_event>", cb)`
  hooks (the Mixin analog).
- **High-level Lua** — `R.engine.resolve(name)` / `R.engine.call(name, …)`.

:::note[Don't hardcode addresses]
Add a symbol and reference `Sym::Name` / `ADDR["Name"]` instead of baking an
address into the loader or SDK. To stop functions reading as `FUN_xxxxxxxx`
in your own Ghidra, run `rsmm symbols ghidra-export`.
:::

Full generated table: [Engine symbol reference](/reference/symbols/).

---

# The mod lifecycle

> How a mod goes from staged files to installed bytes and back, safely.

Source: https://docs.rsmm.me/concepts/mod-lifecycle/

RSMM is, at its core, a reversible **install-time file applier**. Knowing the
lifecycle explains why mods are safe to add and remove at will.

```mermaid
flowchart LR
    A["mods/&lt;id&gt;/<br/>manifest.toml + assets"] --> B["rsmm apply"]
    B -->|"back up original"| K["&lt;file&gt;.rsmm.bak"]
    B -->|"install override"| C["_Cooking/&lt;encoded&gt;"]
    B --> S[".rsmm_state.json"]
    R["rsmm restore --all"] -->|"restore from .bak"| C
    R --> S
```

## The stages

1. **Stage** — you author a mod under `mods/<id>/` (a `manifest.toml` plus
   assets). The SDK can emit cooked assets for you; see
   [Mods ship data, not code](/concepts/data-not-code/).
2. **Apply** — `rsmm apply` resolves each decoded asset path to its encoded
   cooked path, backs the original up as `<file>.rsmm.bak`, then copies the
   override into place. The applier is transactional.
3. **Track** — active overrides are recorded in
   `<install>/DarkTalesResources/_Cooking/.rsmm_state.json`.
4. **Restore** — `rsmm restore --all` copies every `.rsmm.bak` back and
   deletes the backups, returning the game to vanilla.

:::note[Why this is safe]
The engine accepts any byte-compatible file at the encoded path — no
checksum, signature, or embedded path. RSMM never patches `Ravenswatch.exe`
and loads no DLL for asset mods, so no anti-tamper code path runs. Full
threat model: [Architecture overview](/architecture/overview/).
:::

## Common problems

:::caution
- **Game updated and a mod vanished.** A patch re-cooked the file your
  override replaced; re-run `rsmm apply`. Backups are per-file, so this is
  safe.
- **Leftover `.rsmm.bak` files.** Means a restore was interrupted. Run
  `rsmm restore --all` again — it is idempotent.
- **`apply` reports a path it can't resolve.** Your `decoded_path` isn't in
  `data/asset_map.json`; check the exact path (forward slashes) against the
  [glossary](/reference/glossary/) entry for `asset_map.json`.
:::

---

# Tags

> Cross-mod, append-only named groups — the Minecraft

Source: https://docs.rsmm.me/concepts/tags/

A **tag** is a named, cross-mod-extensible group of content — directly modeled
on Minecraft's `#namespace:path` tags (e.g. `#minecraft:logs`). Several mods,
or several call sites, can grow the same tag.

```python
import rsmm.sdk as sdk
m = sdk.Mod(id="Blades", name="Blades")
dagger = m.item("RubyDagger", base="Knife")
m.tag("daggers", [dagger, "VanillaKnife"])
m.commit()
```

## How they behave

- **Append, not replace.** Calling `tag()` again with the same id adds to it
  (de-duped, order preserved). Mod B can extend a tag Mod A created.
- **Members are ids.** Pass id strings or the handles returned by
  `item()`/`enemy()`/… directly — they deref to raw ids.
- **Stored as data.** Tags are written to `mods/<id>/tags.json`; downstream
  tooling and mods aggregate them across all enabled mods (same model as
  `skinpacks.json`).

:::tip[Minecraft analogy]
Exactly like data-pack tags: `#c:ingots` is grown by every mod that adds an
ingot. RSMM tags are the same contract, expressed in the SDK.
:::

## Common problems

:::caution
- **My tag is missing a member from another mod.** Aggregation only includes
  **enabled** mods — check the other mod is applied.
- **Order matters for me, but it changed.** Order is insertion order across
  mods; don't rely on it for correctness, only for display.
:::

See the generated [`Mod.tag` reference](/reference/sdk-api/builder/) for the
exact signature.

---

# Using the app

> Find mods, switch them on, play, and undo everything. A tour of every screen in the RSMM app.

Source: https://docs.rsmm.me/getting-started/desktop-app/

This page walks you through the RSMM app: how to get a mod, play with it, and go
back to the normal game. If you haven't installed the app yet, start with
[Install the app](/getting-started/install/).

## The window at a glance

**Down the left side** are the app's pages:

| Page | What it's for |
| --- | --- |
| **Library** | The mods you have. Switch them on and off, change their settings, update them. |
| **Browse** | Every mod shared on [rsmm.me](https://rsmm.me/registry). Search and install from here. |
| **Profiles** | Saved sets of mods. Make a new one, switch between them, share one with a friend. |
| **Conflicts** | Only appears when two of your switched-on mods change the same thing. |
| **Commands** | Buttons for the less common jobs: health check, repair, restore the original game. |
| **Log** | What script mods wrote while the game was running. Useful when something breaks. |
| **Settings** | At the bottom. Game folder, language, look and feel, and the app's version. |

**Along the top** are the profile you're using and the two buttons you'll press
most:

- **Launch Modded** starts the game **with** your switched-on mods.
- **Launch Vanilla** starts the game **without** any mods.

Press **Ctrl+K** anywhere to open a search box that jumps to any page, mod or
action.

## Install a mod and play

1. Open **Browse**.
2. Find a mod you like. Use the search box, or the **Filters** for categories
   and ratings. Click a mod to read its description and see pictures.
3. Press **install**. The mod downloads and is added to your current profile,
   already switched on.

   Your very first install also creates a profile called **My Mods** and switches
   to it. That's because the **Default** profile is kept as the plain, unmodded
   game.
4. Press **Launch Modded** at the top.

That's it. The game starts with your mods.

### What Launch Modded actually does

1. It writes your switched-on mods into the game's files, keeping a copy of every
   original file first.
2. It starts Ravenswatch through Steam.
3. When you quit the game, it puts every original file back.

So the mods are only in the game **while you play from the app**. If you start
Ravenswatch straight from Steam, you get the normal game. If you want mods,
always start the game with **Launch Modded**.

:::note
Keep the RSMM app open while you play. It's what notices that the game closed
and cleans up afterwards.
:::

## Switch mods on and off

Every mod in the **Library** has a switch. Turn a mod off and it won't be used
the next time you press **Launch Modded**. The mod stays on your computer, so you
can turn it back on later.

- **Change how the list looks** with the three buttons at the top of the
  Library: cards, a compact list, or a view of every mod's settings at once.
- **Remove a mod for good** with its trash-can button. This deletes it from your
  computer.
- **Some mods need other mods** to work. If one is missing, the mod shows a red
  *missing deps* tag. Install the mods it names from **Browse**.

## Change a mod's settings

Some mods have options, like how strong an effect is or which items to ban.
Those mods have a **settings** button on their card (an icon of sliders).

1. Open the mod's settings and change what you like.
2. Press **Save**.
3. The change takes effect the next time you start the game. If the game is
   already running, quit it completely and press **Launch Modded** again.

## Keep your mods up to date

When a newer version of a mod you have comes out, the **Library** shows an
updates box at the top. Press **Update** next to one mod, or **Update all**. A
number next to **Library** in the sidebar tells you how many updates are
waiting.

## Profiles

A **profile** is a saved set of mods. For example, you could keep:

- **My Mods** for your everyday setup,
- **Silly Run** with chaos mods for playing with friends,
- **Default** for the plain game. Default can never hold mods.

On the **Profiles** page you can:

- **New profile**: start an empty one.
- **Activate**: switch to a profile. The Library then shows that profile's mods.
- **Duplicate**: copy a profile, mods included, to try changes without losing
  the original.
- **Export**: copy a short code you can send to a friend. They paste it under
  **Import** to get the same mod list.
- **Backup**: save or restore every profile and setting at once.
- **Open folder**: open the folder on your computer where that profile's mods
  are stored.

You can also switch profiles quickly from the name at the top left of the
window.

## Add a mod from a file

Got a mod as a `.zip` from a friend, or made one in the
[web editor](/guides/web-editor/)? Here's how to add it:

1. Unzip it. You should end up with a folder that has a `manifest.toml` file
   inside.
2. Open **Profiles**, find the profile you want (not Default), and press
   **Open folder**.
3. Move the mod's folder into the folder that opened.
4. Go to the **Library**. A banner says a mod is *on disk but not in this
   profile*. Press **Add to profile**.
5. Press **Launch Modded**.

## Conflicts

Sometimes two mods change the same part of the game, for example two mods that
both replace the same hero's look. Only one of them can win. When that happens:

- a red **conflicts** count appears at the top of the window,
- the **Conflicts** page appears in the sidebar and lists which mods clash.

Turn one of the clashing mods off, or leave it: the mod that loads **later** wins.

## Commands

The **Commands** page has buttons for jobs you won't need every day:

| Button | What it does |
| --- | --- |
| **Doctor** | Checks that the game, the mods and the loader are set up correctly. Run this first when something's wrong. |
| **Doctor + repair** | The same check, then fixes whatever it safely can. |
| **Apply mods** | Writes your mods into the game **without** starting it, and leaves them there. Useful if you want to start the game from Steam with mods. |
| **Restore originals** | Puts every original game file back and removes the loader. The "undo everything" button. |
| **Build** | Rebuilds generated mod files and applies them. Mostly for mod makers. |
| **Run vanilla** / **Run modded** | The same as the Launch buttons at the top. |

## Log

The **Log** page shows what script mods wrote while the game was running. Tick
**problems only** to see just errors and warnings. The drop-down lets you look at
earlier game sessions.

If a mod crashes the game three times in a row while it's starting up, RSMM skips
that mod on the next start and the Log page tells you which one. Press **Try
again** once you think it's fixed.

To ask someone for help, press **Share link**. It uploads the log and gives you a
link to paste into Discord or a GitHub issue. Read the preview first: personal
details like your user name are hidden, but anyone with the link can read it.
More in [Troubleshooting](/getting-started/troubleshooting/#share-your-log).

## Overlays

Some mods show a small window on top of the game, like a damage meter or a run
timer. Those mods have an **Overlay** button on their card. Press it to show the
window, and press it again to hide it.

- Drag the window by its top bar. Drag the **bottom-right corner** to resize it.
- **Compact** hides the footer.
- **Click-through** lets your clicks go through to the game. Press
  **Ctrl+Alt+O** to turn it off again, since you can't click a window that lets
  clicks through.
- Lost the window off-screen? **Shift-click** the Overlay button to put it back
  in the middle.
- Overlays can only sit on top of the game if Ravenswatch runs in **borderless
  windowed** mode, not exclusive fullscreen.

## Settings

| Tab | What's in it |
| --- | --- |
| **General** | Where the game is installed (**Game install**), where your mods are kept (**Mods folder**), mod sources and app updates. |
| **Appearance** | Language, font, text size, spacing and animations. |
| **Game** | Online server, loader features, and **Disable GPU acceleration** if the app draws badly or crashes your graphics driver. |
| **Diagnostics** | The app's own log and crash reports. |
| **About** | The app's version, release notes and credits. |

### Language

**Settings → Appearance → Language** switches the app between English and
简体中文 (Simplified Chinese). It changes right away, no restart needed. On first
start the app picks Chinese if your computer is set to Chinese, otherwise English.

Some text always stays in its original language: messages from the `rsmm`
command-line tool, text that mods write themselves, and the game's own text.

## Where your files are

| | Windows | Linux / Steam Deck |
| --- | --- | --- |
| Your mods | `%APPDATA%\rsmm\mods\profiles\<profile>\` | `~/.local/share/rsmm/mods/profiles/<profile>/` |
| Copies of the original game files | Next to each file in the game folder, with `.rsmm.bak` added to the name | Same |

You can move the mods folder under **Settings → General → Mods folder**. The quickest way to open a
profile's mods folder is the **Open folder** button on the **Profiles** page.

## Windows and Linux

The app works the same on both. The differences:

| | Windows | Linux / Steam Deck |
| --- | --- | --- |
| How it's installed | `x64-setup.exe` installer | AppImage, `.deb`, or the AUR |
| Mods that change looks, numbers, text | ✅ | ✅ |
| Script (Lua) mods | ✅ | Experimental, needs a [Steam launch option](/getting-started/install/#script-mods-on-linux-and-steam-deck) |
| Finding the game automatically | Every Steam library on every drive | Normal and Flatpak Steam, plus `/mnt` |

:::note[For translators]
A new app language is a file under `apps/desktop/src/locales/`. The
`coverage.test.ts` test fails the build if a translation is missing, unused, or
drops a `{placeholder}`.
:::

---

# Frequently asked questions

> Short answers about safety, co-op, Steam Deck, saves, game updates and making mods.

Source: https://docs.rsmm.me/getting-started/faq/

## Using mods

### Is RSMM free?

Yes. RSMM is free and open source under the MIT licence. All of its code is on
[GitHub](https://github.com/Ovilli/RavenswatchModManager).

### Is it safe? Windows warned me about it.

Windows shows **"Windows protected your PC"** for programs that haven't paid for
a code-signing certificate, which is common for small free projects. Click
**More info**, then **Run anyway**. Download RSMM only from the official
[release page](https://github.com/Ovilli/RavenswatchModManager/releases/latest).

Mods on [rsmm.me](https://rsmm.me/registry) are scanned for malware before they
appear on the site. Mods you get anywhere else haven't been checked, so treat
them like any other download.

### Can I get banned for using mods?

RSMM doesn't change `Ravenswatch.exe` and doesn't try to get around anything that
protects the game. Most mods only swap data files on your own computer, like
pictures, numbers and text. Online, be considerate: don't bring mods that change
gameplay into strangers' games.

### Can I play co-op with mods?

It depends on the mod.

- **Mods that only change what *you* see or hear**, such as new looks, sounds,
  translations, a damage meter or a camera tweak, are fine. Your friends don't
  need them.
- **Mods that change the game itself**, such as stronger items, new enemies or
  different rules, should be installed by **everyone** in the group. Otherwise
  the game can behave differently for each player.

A mod's description should say which kind it is. If you have the modding tools,
`rsmm modpack` lists your mods in those two groups.

### Does it work on Steam Deck? On Mac?

**Steam Deck:** yes, with the Linux AppImage. See
[Install the app](/getting-started/install/).
**Mac:** no, macOS isn't supported.

### Will mods break my save?

Mods change the game's files, not your save files. Your saves are in the `_Save`
folder inside the game folder. Mods that add brand-new things (new items, new
enemies) carry the most risk, so copy `_Save` somewhere safe before you try one of
those.

### How do I get the normal game back?

- **For one session:** press **Launch Vanilla** in the app.
- **For good:** in the app, open **Commands** and run **Restore originals**.
- **To be extra sure:** in Steam, right-click Ravenswatch → **Properties** →
  **Installed Files** → **Verify integrity of game files**.

When you play with **Launch Modded**, RSMM already puts the original files back
when you close the game.

### Ravenswatch updated and my mods stopped working.

A game update replaces game files, which switches your mods off. The app notices
and shows **Ravenswatch updated — your mods were disabled by the game update**.
Press **Repair**, then **Launch Modded** as usual.

If a mod still doesn't work after that, it may need an update from its author.
Check the **Library** for updates.

### What's the difference between "Apply" and "Launch Modded"?

- **Launch Modded** puts your mods in, starts the game, and takes them out again
  when you quit. This is what you want almost every time.
- **Apply mods** (on the **Commands** page) puts your mods in and **leaves them
  there**, so you can start the game from Steam with mods. Use **Restore
  originals** to take them out.

### Some mods say "experimental". What does that mean?

RSMM works by understanding the game's files, and some kinds of changes aren't
fully understood yet. An **experimental** mod may not work completely, and could
crash the game. They're safe to try, since RSMM can always restore the original
files, but expect rough edges.

### What does "script mod" or "Lua mod" mean?

Most mods are **data**: they swap pictures, numbers or text. A few also include a
small program written in a language called **Lua**, which can react to things
happening in the game, such as showing a damage meter. Script mods need the
**loader**, which the app installs for you. On Linux and Steam Deck they're
experimental and need
[one Steam setting](/getting-started/install/#script-mods-on-linux-and-steam-deck).

## Making mods

### Do I need to know how to code?

No. The [web editor](/guides/web-editor/) changes items, talents and abilities
by clicking, and most mods are a short text file called `manifest.toml`. Code
(Lua) is only needed for script mods. Start with
[Make your first mod](/getting-started/first-mod/).

### What can a mod change?

| Area | Examples |
| --- | --- |
| **Look and sound** | Textures, 3D models, audio |
| **Balance** | Hero and enemy stats, talent values, magical object values |
| **Text** | Any text in the game, including whole translations |
| **New content** | New magical objects. Enemies, maps, shops and rewards work but are still experimental. |
| **Scripted gameplay** | Lua scripts that run inside the game |

### Do I need the app to make mods?

No. You can make mods with the web editor or the [modding tools](/getting-started/modding-tools/)
alone. The app is the easiest way to *play* them, and to see your mod the way
players will.

### How do I share my mod?

Run `rsmm pack MyMod` to make a `.zip`, then upload it on
[rsmm.me/publish](https://rsmm.me/publish). See
[Share your mod](/getting-started/first-mod/#share-your-mod).

## Getting help

### Where can I ask for help?

Open an issue on [GitHub](https://github.com/Ovilli/RavenswatchModManager/issues).
Include your operating system, your RSMM version (**Settings → About**), and a
[shared log link](/getting-started/troubleshooting/#share-your-log). First, try
the [troubleshooting page](/getting-started/troubleshooting/): it covers the most
common problems.

---

# Make your first mod

> A beginner's walkthrough. Rename an item, see it in the game, and undo it, in your browser or with the modding tools.

Source: https://docs.rsmm.me/getting-started/first-mod/

import { Steps, Aside, Tabs, TabItem, LinkCard, CardGrid } from '@astrojs/starlight/components';

In this tutorial you'll make a small mod that **renames a magical object** and
then see your new name in the game. It's a tiny change, but it's the whole journey
every mod takes: make a change, put it in the game, check it worked, undo it.

There are two ways to do it. Pick one:

| | **Way 1: in your browser** | **Way 2: with the modding tools** |
| --- | --- | --- |
| What you need | A web browser on a computer, and the [RSMM app](/getting-started/install/) | The [modding tools](/getting-started/modding-tools/) |
| Typing commands | None | A few |
| What it can make | Items, talents, abilities, maps | Everything RSMM supports |
| Best for | Trying it out, quick balance changes | Bigger mods, sharing on rsmm.me |

You can start with Way 1 and move to Way 2 later. The mods are the same either way.

## Way 1: In your browser

The **web editor** runs on this website and reads the game files straight from
your computer. Nothing gets uploaded and nothing needs installing.

<Steps>
1. **Open the [web editor](/editor/).** The first visit downloads about 12 MB, so
   give it a moment. It works in Chrome, Edge, Firefox and Safari on a computer,
   but not on a phone.

2. **Choose your Ravenswatch folder.** To find it, in Steam right-click
   **Ravenswatch** → **Manage** → **Browse local files**.

   Your browser will ask whether to "upload" the folder. That's just the
   browser's standard wording for letting a page *read* a folder. The files stay
   on your computer.

3. **Pick an item.** The **Items** tab opens first. Search the list on the left
   for an item you know from the game and click it.

4. **Rename it.** Leave **Replace this item** selected. That changes the real
   item rather than adding a new one. In **Name**, type something you'll
   recognise instantly, like `My Very First Item`.

   Want to change what it does too? Each of the item's numbers is listed below
   the name. Change one and the card preview updates as you type.

5. **Check it.** Press **Check** at the bottom. You should see *Everything
   builds*.

6. **Save it as a mod.** At the bottom, the mod list says **New mod…**. Press
   **Create mod…** and fill in the form:
   - **Mod id**: a short name with no spaces, like `my-first-mod`.
   - **Name**: the name people will see, like `My First Mod`.
   - **Author**: your name or nickname.

   Press **Create mod**. Your browser downloads `my-first-mod.zip`.

7. **Add it to the app.** Unzip the file, then follow
   [Add a mod from a file](/getting-started/desktop-app/#add-a-mod-from-a-file).
   In short: **Profiles** → **Open folder** → move the `my-first-mod` folder in →
   **Library** → **Add to profile**.

8. **Play.** Press **Launch Modded**. In the game, open the compendium and find
   your item. It now has your name. 🎉
</Steps>

**To undo it**, switch the mod off in the **Library**, or just press **Launch
Vanilla**.

To keep working on the mod later, open the web editor and press **Open a mod
folder…**. More in the [web editor guide](/guides/web-editor/).

## Way 2: With the modding tools

This way you'll write the mod yourself. It's still only a few lines of text.

**Before you start**, follow [Set up the modding tools](/getting-started/modding-tools/).
Open a terminal in the `RavenswatchModManager` folder with the environment
switched on, so the line starts with `(.venv)`.

### 1. Create the mod

```sh
rsmm new MyFirstMod
```

This makes a new folder, `mods/MyFirstMod/`, with a few starter files:

| File | What it's for |
| --- | --- |
| `manifest.toml` | **The important one.** Says what your mod is called and what it changes. |
| `init.lua` | A script, for mods that need one. Ours doesn't, so you can ignore it. |
| `config_schema.toml` | Settings players can change in the app. Optional. |
| `lang/EN.toml` | Text in different languages. Optional. |
| `README.md` | A description for people reading your mod's files. |

### 2. Fill in the basics

Open `mods/MyFirstMod/manifest.toml` in a text editor. It looks something like this:

```toml title="mods/MyFirstMod/manifest.toml"
#:schema https://docs.rsmm.me/manifest.schema.json

[mod]
id          = "MyFirstMod"
name        = 'MyFirstMod'
version     = "0.1.0"
author      = "you"
description = ''
enabled     = true
sdk_version = ">=3.0,<4"
tags        = []
license     = ""
```

Change `name`, `author` and `description` to your own. Everything else can stay.

<Aside type="tip" title="How to read this file">
Each line is `setting = value`. Text goes in quotes. Lines starting with `#` are
notes for humans and are ignored. `[mod]` starts the section that describes the
mod itself.
</Aside>

### 3. Add your change

Add these lines to the **end** of the file:

```toml
multiplayer_scope = "deterministic-shared"

[[content]]
kind = "item"
mode = "replace"
id   = "Damage_Attack"
base = "Damage_Attack"
name = "My Very First Item"
```

Line by line:

- `multiplayer_scope` tells co-op players that everyone in the game needs this mod,
  because it changes how an item works. It belongs to `[mod]`, so it goes right
  under the lines you just edited.
- `[[content]]` starts a block that changes one thing in the game.
- `kind = "item"` says that thing is a magical object.
- `mode = "replace"` changes the real item instead of adding a new one.
- `id` and `base` say which item. `Damage_Attack` is the game's internal name for
  **Ace of Spades**.
- `name` is the new name the game will show.

Your whole file should now look like this:

```toml title="mods/MyFirstMod/manifest.toml"
#:schema https://docs.rsmm.me/manifest.schema.json

[mod]
id          = "MyFirstMod"
name        = "My First Mod"
version     = "0.1.0"
author      = "Sam"
description = "Renames Ace of Spades so I can see my mod working."
enabled     = true
sdk_version = ">=3.0,<4"
tags        = ["items"]
license     = "MIT"
multiplayer_scope = "deterministic-shared"

[[content]]
kind = "item"
mode = "replace"
id   = "Damage_Attack"
base = "Damage_Attack"
name = "My Very First Item"
```

<Aside type="tip" title="Want a different item?">
`rsmm items list` shows every item's internal name. Or skip the typing entirely:
`rsmm editor` opens the same editor as Way 1, and its **Add to mod** button writes
this block into your mod for you.
</Aside>

### 4. Check it for mistakes

```sh
rsmm lint MyFirstMod
```

`lint` reads your mod and points out problems before you start the game:

- **`[OK]   MyFirstMod`** at the end means it's ready.
- **`[WARN]`** lines are suggestions, such as a missing description. Your mod still
  works.
- **`[FAIL]`** lines must be fixed. They say what's wrong, and often suggest the
  right spelling (`did you mean …?`).

### 5. Put it in the game and play

```sh
rsmm apply
rsmm run
```

`apply` writes your mod into the game's files, keeping a copy of each original.
`run` starts Ravenswatch through Steam. Open the compendium and look for
**My Very First Item**. 🎉

### 6. Undo it

```sh
rsmm restore --all
```

This puts every original file back. The game is vanilla again, and your mod is
still safe in `mods/MyFirstMod/` for next time.

### Changing things and trying again

Edit `manifest.toml`, then run `rsmm apply` again and restart the game. Or leave
this running in a second terminal, and it re-applies every time you save:

```sh
rsmm watch
```

## Share your mod

When you're happy with it:

1. Pack it into a single file:
   ```sh
   rsmm pack MyFirstMod
   ```
   This creates `dist/MyFirstMod.zip`.
2. Upload it on [rsmm.me/publish](https://rsmm.me/publish) (you'll need an
   account). Every upload is scanned for malware before it appears on the site.

Prefer the command line? Create an API token on your
[account page](https://rsmm.me/account), then:

```sh
rsmm publish login
rsmm publish MyFirstMod
```

## What next?

<CardGrid>
  <LinkCard title="First mod, by kind" href="/guides/first-mod-by-kind/" description="A small, working example for every kind of change: talents, enemies, maps, and more." />
  <LinkCard title="Example mods" href="/guides/examples/" description="Complete mods to copy, including script (Lua) mods." />
  <LinkCard title="Modding guide" href="/guides/modding/" description="Everything a manifest can do, in detail." />
  <LinkCard title="Build a mod with an AI assistant" href="/guides/ai-assistant/" description="Point ChatGPT, Claude or a coding agent at the real docs." />
</CardGrid>

---

# Install the app

> Download and install Ravenswatch Mod Manager on Windows, Linux or Steam Deck, step by step.

Source: https://docs.rsmm.me/getting-started/install/

import { Tabs, TabItem, Steps, Aside, LinkCard, CardGrid } from '@astrojs/starlight/components';

This page gets the Ravenswatch Mod Manager app onto your computer. It takes a few
minutes and you don't need to type any commands.

**Before you start**, make sure Ravenswatch is installed through Steam and that
you've started it at least once. RSMM works on **Windows 10/11**, **Linux** and
**Steam Deck**. macOS is not supported.

## 1. Download and install

All downloads are on the
[latest release page](https://github.com/Ovilli/RavenswatchModManager/releases/latest).
Scroll down to **Assets** and pick the file for your system.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    <Steps>
    1. Download the file that ends in **`x64-setup.exe`**, for example
       `Ravenswatch.Mod.Manager_5.9.9_x64-setup.exe`. The version number will be
       whatever is newest.
    2. Double-click it and follow the installer.

       Windows may show a blue box saying **"Windows protected your PC"**. That
       happens with small projects that haven't paid for a code-signing
       certificate. Click **More info**, then **Run anyway**.
    3. Open **Ravenswatch Mod Manager** from the Start menu.
    </Steps>

    <Aside type="tip">
    If the app doesn't open at all, install
    [Microsoft WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
    (choose the *Evergreen Bootstrapper*) and try again. Windows 11 already has it.
    </Aside>
  </TabItem>
  <TabItem label="Linux" icon="linux">
    There are two choices. **If you're not sure, use the AppImage.** It works on
    almost every distribution and updates itself.

    **AppImage (recommended)**

    <Steps>
    1. Download the file that ends in **`.AppImage`**.
    2. Move it somewhere you'll keep it, such as `~/Applications`.
    3. Make it runnable. Right-click it, open **Properties → Permissions**, and
       tick **Allow executing file as program**. Or, in a terminal:
       ```sh
       chmod +x ~/Applications/Ravenswatch.Mod.Manager_*.AppImage
       ```
    4. Double-click it to start the app.
    </Steps>

    **Debian / Ubuntu package**

    Download the file that ends in **`.deb`** and open it with your software
    installer, or run `sudo apt install ./Ravenswatch.Mod.Manager_*_amd64.deb` in
    the folder you downloaded it to.

    A `.deb` install can't update itself. When an update comes out, the app
    offers a one-click **Install to ~/Applications**, which switches you over to
    a self-updating AppImage.

    **Arch Linux**

    There is an [AUR package](https://aur.archlinux.org/packages/rsmm):
    `yay -S rsmm`.

    <Aside type="caution">
    **Gray, empty window on Debian or Ubuntu?** Start the app from a terminal
    like this instead:
    ```sh
    WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 ./Ravenswatch.Mod.Manager_*.AppImage
    ```
    </Aside>
  </TabItem>
  <TabItem label="Steam Deck">
    <Steps>
    1. Hold the power button and choose **Switch to Desktop**.
    2. Open the release page in the browser and download the file that ends in
       **`.AppImage`**.
    3. Open the **Downloads** folder, right-click the file, open
       **Properties → Permissions** and tick **Is executable**.
    4. Double-click it to start the app.
    </Steps>

    Mods that change looks, numbers and text work on Steam Deck. Script (Lua)
    mods need one extra setting, explained in
    [Script mods on Linux and Steam Deck](#script-mods-on-linux-and-steam-deck).
  </TabItem>
</Tabs>

## 2. First start

When the app opens, it looks through your Steam libraries for Ravenswatch and
runs a quick health check. **If nothing pops up, everything is fine** and you
can skip to the next page.

If something needs fixing, a **First-run setup** box appears at the top of the
**Library** page and lists what's wrong:

<Steps>
1. If there's a button like **Repair 2 automatically**, press it. That fixes
   most problems.
2. If it says the game wasn't found, press **Open Settings** and fill in
   **Game install** with the folder that contains `Ravenswatch.exe`.

   Not sure where that is? In Steam, right-click **Ravenswatch** →
   **Manage** → **Browse local files**. The folder that opens is the one you
   want.
3. Go back to the **Library** and press **Re-check**. When every check passes,
   the box goes away.
</Steps>

You're ready. Go to [Using the app](/getting-started/desktop-app/) to install
your first mod.

## Updates

The app checks for new versions by itself. When one is ready you'll see a
message with a **Restart & update** button. That's all you need to do.

The app also keeps the **loader** (the small extra file that script mods need)
up to date in your game folder each time it starts.

## Script mods on Linux and Steam Deck

On Linux, Ravenswatch runs through Steam's Proton. Script (Lua) mods need Steam
to load RSMM's loader file, which takes one launch option:

<Steps>
1. In Steam, right-click **Ravenswatch** → **Properties**.
2. Under **General → Launch Options**, paste:
   ```
   WINEDLLOVERRIDES="winhttp=n,b" %command%
   ```
3. Close the window. Steam saves it automatically.
</Steps>

Script mods on Linux are still experimental. Mods that only change looks, numbers
or text don't need this.

## Uninstall

1. In the app, open **Commands** and run **Restore originals**. This puts every
   original game file back.
2. Uninstall the app the normal way: **Settings → Apps** on Windows, or delete
   the AppImage on Linux.

To be extra sure the game is clean, right-click Ravenswatch in Steam →
**Properties → Installed Files → Verify integrity of game files**.

## Next steps

<CardGrid>
  <LinkCard title="Using the app" href="/getting-started/desktop-app/" description="Find mods, switch them on, and play." />
  <LinkCard title="Make your first mod" href="/getting-started/first-mod/" description="Change an item in your browser, no tools needed." />
  <LinkCard title="Troubleshooting" href="/getting-started/troubleshooting/" description="If something didn't work." />
  <LinkCard title="Modding tools" href="/getting-started/modding-tools/" description="The rsmm command-line tool, for mod makers." />
</CardGrid>

---

# Set up the modding tools

> Install the rsmm command-line tool step by step, even if you've never used a terminal.

Source: https://docs.rsmm.me/getting-started/modding-tools/

import { Tabs, TabItem, Steps, Aside, LinkCard, CardGrid } from '@astrojs/starlight/components';

The **modding tools** are a program called `rsmm` that you use by typing commands.
You need them to make mods beyond what the [web editor](/guides/web-editor/) can
do, to test mods quickly, and to publish them.

**Only want to play with mods?** You don't need any of this. Use
[the app](/getting-started/install/) instead.

Setting up takes about 15 minutes the first time. You'll install two free
programs (Python and Git), download RSMM's tools, and check that everything works.

## Before you start: the terminal

A **terminal** is a window where you type a command and press **Enter**, instead
of clicking buttons. Every code box on this page is something to type (or paste)
into it.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    Press the **Start** button, type `cmd`, and open **Command Prompt**.

    Use Command Prompt for everything on this page. PowerShell works too, but it
    blocks one of the steps by default (see the note in step 4).
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    Press **Ctrl+Alt+T**, or open **Terminal** (called **Konsole** on Steam Deck
    and KDE) from your app menu. On Steam Deck, switch to Desktop mode first.
  </TabItem>
</Tabs>

<Aside type="tip">
To paste into a terminal, right-click it (Windows) or press **Ctrl+Shift+V**
(Linux). Plain Ctrl+V doesn't always work.
</Aside>

## 1. Install Python

`rsmm` is written in Python, so your computer needs Python **3.11 or newer**.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    <Steps>
    1. Download the latest Python from
       [python.org/downloads](https://www.python.org/downloads/).
    2. Run the installer. On the first screen, **tick "Add python.exe to PATH"**
       at the bottom. This is easy to miss and important.
    3. Click **Install Now**.
    4. Close any open Command Prompt windows and open a new one. Then check it
       worked:
       ```cmd
       python --version
       ```
       You should see something like `Python 3.13.1`.
    </Steps>
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    Most Linux systems already have Python. Check the version:
    ```sh
    python3 --version
    ```
    If it says 3.11 or higher, you're set. On **Debian or Ubuntu**, also install
    the part that makes private Python environments, which step 4 needs:
    ```sh
    sudo apt install python3-venv
    ```
  </TabItem>
</Tabs>

## 2. Install Git

Git downloads RSMM's tools and keeps them up to date.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    Download Git from [git-scm.com](https://git-scm.com/downloads/win) and run
    the installer. The default answer on every screen is fine. Then open a
    **new** Command Prompt.
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    Git is usually already installed. If `git --version` says *command not
    found*, install it with your package manager, for example
    `sudo apt install git` on Debian or Ubuntu.
  </TabItem>
</Tabs>

## 3. Download RSMM's tools

This makes a folder called `RavenswatchModManager` in your Documents folder and
moves the terminal into it.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    ```cmd
    cd %USERPROFILE%\Documents
    git clone https://github.com/Ovilli/RavenswatchModManager.git
    cd RavenswatchModManager
    ```
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    ```sh
    cd ~/Documents
    git clone https://github.com/Ovilli/RavenswatchModManager.git
    cd RavenswatchModManager
    ```
  </TabItem>
</Tabs>

`cd` means "change directory", which is the terminal's way of opening a folder.

## 4. Install the `rsmm` command

This creates a private Python environment (a folder called `.venv`) so RSMM
doesn't mix with anything else on your computer, then installs `rsmm` into it.

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    ```cmd
    python -m venv .venv
    .venv\Scripts\activate
    pip install -e .
    ```

    <Aside type="caution" title="Using PowerShell?">
    If `.venv\Scripts\activate` fails with *running scripts is disabled on this
    system*, either switch to Command Prompt, or run this once and try again:
    ```powershell
    Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
    ```
    </Aside>
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    ```sh
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -e .
    ```
  </TabItem>
</Tabs>

When the environment is switched on, your terminal shows **`(.venv)`** at the
start of the line.

## 5. Check that it works

```sh
rsmm doctor
```

`rsmm doctor` is a health check. It looks for your game and checks your setup,
then prints one line per check:

- **`[OK]`** means that part is fine.
- **`[WARN]`** is worth reading but won't stop you.
- **`[FAIL]`** needs fixing. The line under it usually says how.

**If it can't find your game**, tell it where Ravenswatch is. Use the folder that
contains `Ravenswatch.exe` (in Steam: right-click **Ravenswatch** → **Manage** →
**Browse local files**):

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    ```cmd
    setx RSMM_GAME_DIR "D:\SteamLibrary\steamapps\common\Ravenswatch"
    ```
    Then close the terminal, open a new one, and repeat the "every time" steps
    below.
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    ```sh
    echo 'export RSMM_GAME_DIR="$HOME/.local/share/Steam/steamapps/common/Ravenswatch"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </TabItem>
</Tabs>

Change the path in quotes to your own game folder.

## Every time you come back

A new terminal window starts fresh, so before using `rsmm` again, go back to the
folder and switch the environment on:

<Tabs syncKey="os">
  <TabItem label="Windows" icon="seti:windows">
    ```cmd
    cd %USERPROFILE%\Documents\RavenswatchModManager
    .venv\Scripts\activate
    ```
  </TabItem>
  <TabItem label="Linux / Steam Deck" icon="linux">
    ```sh
    cd ~/Documents/RavenswatchModManager
    source .venv/bin/activate
    ```
  </TabItem>
</Tabs>

If you see `'rsmm' is not recognized` or `rsmm: command not found`, this is
almost always the step you skipped.

## Get the newest tools

From the `RavenswatchModManager` folder:

```sh
git pull
```

## Script (Lua) mods

Mods that only change looks, numbers or text work as they are. Mods with a Lua
script also need the **loader**, a small file that goes next to the game:

```sh
rsmm install-loader
```

On **Linux and Steam Deck**, Steam also needs a launch option to load it. Close
Steam completely, then run:

```sh
rsmm run --set-launch-options --no-launch
```

## A good text editor

A mod is mostly a text file called `manifest.toml`. Any text editor can open it,
but [Visual Studio Code](https://code.visualstudio.com/) with the
[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
extension is worth it: it suggests the right names as you type and underlines
mistakes before you even run the game.

## Commands you'll use most

| Command | What it does |
| --- | --- |
| `rsmm new MyMod` | Create a new, empty mod called `MyMod` |
| `rsmm editor` | Open the item, talent and ability editor in your browser |
| `rsmm lint MyMod` | Check `MyMod` for mistakes |
| `rsmm apply` | Put every switched-on mod into the game |
| `rsmm run` | Start the game through Steam |
| `rsmm restore --all` | Undo every mod and put the original files back |
| `rsmm watch` | Re-apply your mods every time you save a file |
| `rsmm doctor` | Check that everything is set up |
| `rsmm --help` | List every command |

Every command explains itself with `--help`, for example `rsmm lint --help`. The
full list is in the [CLI reference](/reference/cli/).

<Aside type="note" title="Two separate mods folders">
Mods you make with `rsmm` live in the `mods` folder inside `RavenswatchModManager`.
The app keeps its own mods somewhere else. To try one of your mods in the app,
copy its folder in as described in
[Add a mod from a file](/getting-started/desktop-app/#add-a-mod-from-a-file).
</Aside>

## Next

<CardGrid>
  <LinkCard title="Make your first mod" href="/getting-started/first-mod/" description="A step-by-step walkthrough that ends with your change in the game." />
  <LinkCard title="Troubleshooting" href="/getting-started/troubleshooting/#modding-tools" description="If a step on this page didn't work." />
</CardGrid>

---

# New to modding? Start here

> What mods are, what RSMM does, and which page to read next. No experience needed.

Source: https://docs.rsmm.me/getting-started/start-here/

import { Card, CardGrid, LinkCard, Aside } from '@astrojs/starlight/components';

Never modded a game before? That's fine. This page explains the basics in plain
words and then points you to the one page you need next.

## What is a mod?

A **mod** (short for *modification*) is a small add-on that changes something in
a game. A Ravenswatch mod might:

- give a hero a new look,
- make an item stronger or weaker,
- change what the game's text says, or translate it,
- add something new, like a magical object that doesn't exist in the normal game,
- show extra information on screen, like a damage meter.

The game without any mods is called **vanilla**. You'll see that word a lot.

## What is RSMM?

**RSMM** stands for **Ravenswatch Mod Manager**. It's a free program that puts
mods into the game for you and takes them out again. You never have to copy game
files around by hand.

It comes in a few pieces. You only need the ones that match what you want to do:

| Piece | What it is | Who it's for |
| --- | --- | --- |
| **The app** | A normal desktop program for Windows and Linux. Find mods, switch them on, press play. | Everyone who wants to **play** with mods |
| **[rsmm.me](https://rsmm.me/registry)** | The website where people share mods. The app shows the same list. | Everyone |
| **The web editor** | A page in your browser that changes items, talents and abilities. Nothing to install. | People who want to **make** a simple mod |
| **The modding tools** | A command-line program called `rsmm`, for making and publishing mods. | People who want to **make** mods |

## Is it safe?

Yes, and it's built to be easy to undo.

- **Everything can be undone.** Before RSMM changes a game file, it saves a copy
  of the original. When you play through the app with **Launch Modded**, it puts
  every original file back as soon as you close the game.
- **It doesn't touch the game's program.** RSMM never changes `Ravenswatch.exe`
  and doesn't try to get around any protection in the game. Most mods only swap
  data files, like pictures, numbers and text.
- **Uploaded mods are scanned.** Every mod uploaded to rsmm.me is checked for
  malware before it shows up on the site.

<Aside type="tip">
If you ever want the plain game back, press **Launch Vanilla** in the app. It
restores the original files and starts the game without mods.
</Aside>

## What do you want to do?

<CardGrid>
  <Card title="I want to play with mods" icon="rocket">
    Install the app, pick some mods, press **Launch Modded**. No typing commands,
    no editing files.

    [Install the app →](/getting-started/install/)
  </Card>
  <Card title="I want to make a mod" icon="pencil">
    Start in your browser with the web editor, then move on to the modding tools
    when you want more.

    [Make your first mod →](/getting-started/first-mod/)
  </Card>
</CardGrid>

## Words you'll see

You don't need to learn these up front. Come back here when one trips you up, or
see the full [glossary](/reference/glossary/).

| Word | What it means |
| --- | --- |
| **Vanilla** | The game exactly as it comes from Steam, with no mods. |
| **Apply** | Write your switched-on mods into the game's files. The app does this for you when you press **Launch Modded**. |
| **Restore** | Put the original game files back, undoing every mod. |
| **Profile** | A saved set of mods. You can keep one for a normal run, another for a silly run, and switch between them. |
| **Load order** | The order mods are applied in. When two mods change the same thing, the later one wins. |
| **Conflict** | Two switched-on mods that change the same file. The app warns you and shows a **Conflicts** page. |
| **Loader** | A small extra file RSMM puts next to the game so that *script* mods (written in Lua) can run. Mods that only change looks, numbers or text don't need it. |
| **Manifest** | The `manifest.toml` file inside every mod. It's a short text file that says what the mod is called and what it changes. |
| **CLI / terminal** | A window where you type commands instead of clicking buttons. Only needed for the modding tools, never for playing. |

## Still have questions?

<CardGrid>
  <LinkCard title="Frequently asked questions" href="/getting-started/faq/" description="Bans, co-op, Steam Deck, saves, game updates and more." />
  <LinkCard title="Something isn't working" href="/getting-started/troubleshooting/" description="Fixes for the most common problems, by symptom." />
</CardGrid>

---

# Troubleshooting

> Fixes for the most common problems, sorted by what you're seeing.

Source: https://docs.rsmm.me/getting-started/troubleshooting/

Find what you're seeing below. Each answer starts with the most likely fix.

## Try this first: the health check

Most problems are found by RSMM's own health check.

- **In the app:** open **Commands** and press **Doctor**. If it finds problems it
  can fix, press **Doctor + repair**.
- **With the modding tools:** run `rsmm doctor`, or `rsmm doctor --fix` to repair
  what it safely can.

Each line it prints is `OK`, `WARN` (worth reading) or `FAIL` (needs fixing), and
a failing line usually says how to fix it.

## The app

### The app won't open (Windows)

Install [Microsoft WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
(the *Evergreen Bootstrapper*) and try again. Windows 11 and most Windows 10
computers already have it.

### The app won't open, or the window is gray (Linux)

If the window is **gray or empty** (common on Debian and Ubuntu), start the app
from a terminal with these settings:

```sh
WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 ./Ravenswatch.Mod.Manager_*.AppImage
```

If that fixes it, the cause is your graphics driver or desktop, not RSMM.

If the app **doesn't open at all**, make sure WebKitGTK 4.1 is installed:

```sh
sudo apt install libwebkit2gtk-4.1-0     # Debian / Ubuntu
sudo dnf install webkit2gtk4.1           # Fedora
sudo pacman -S webkit2gtk-4.1            # Arch
```

### The app can't find my game

1. In Steam, right-click **Ravenswatch** → **Manage** → **Browse local files**.
   Copy the address of the folder that opens.
2. In the app, open **Settings → General** and paste it into **Game install**.

If Ravenswatch has never been started, start it once through Steam first.

### "Permission denied" (Linux)

RSMM can't write to the game folder. This happens most often with a Steam library
on a second drive. Give your user ownership of the game folder:

```sh
sudo chown -R $USER "/path/to/Ravenswatch"
```

### An error mentions Python

The app carries its own copy of everything it needs, so you never install Python
for it. An error like this means the app's files are damaged. Reinstall the app.

### The PC freezes or blue-screens while the app is open (Windows)

The app draws with your graphics card, like a web browser does. That's enough to
expose a broken **graphics driver**, and a driver crash takes down the whole
computer, not just the app.

1. **Reinstall your graphics driver** from NVIDIA, AMD or Intel. If the crashes
   started after a driver update, go back to the previous version.
2. **Close overlays** that hook into graphics, such as Discord's overlay,
   GeForce Experience or MSI Afterburner, while you test.
3. **As a workaround**, open **Settings → Game** and tick **Disable GPU
   acceleration (software rendering)**, then restart the app. The app stops using
   your graphics card. This hides the problem in RSMM, but the driver is still
   broken for other programs.

<details>
<summary>Want to confirm it's the driver?</summary>

Run this in PowerShell:

```powershell
Get-WinEvent -FilterHashtable @{LogName='System'; Id=41,1001,6008} -MaxEvents 5 | Format-List
```

A crash named `VIDEO_SCHEDULER_INTERNAL_ERROR` (`0x119`), `VIDEO_TDR_FAILURE`
(`0x116`) or `DPC_WATCHDOG_VIOLATION` comes from the display driver. Normal
programs can't cause these by themselves. To see which driver, open
`C:\Windows\Minidump\*.dmp` in WinDbg and run `!analyze -v`: `IMAGE_NAME` names it.

</details>

## Mods

### My mods don't show up in the game

Check these in order:

1. **Did you start the game with Launch Modded?** If you start Ravenswatch from
   Steam, you get the normal game, because RSMM takes the mods out again when the
   game closes. (Want mods when starting from Steam? Use **Commands → Apply
   mods**.)
2. **Are you in the right profile?** The profile name is at the top left. The
   **Default** profile is always the plain game. Switch to the profile that has
   your mods.
3. **Is the mod switched on?** Check its switch in the **Library**.
4. **Did you change a mod's settings while the game was running?** Quit the game
   completely and press **Launch Modded** again.
5. **Run the health check:** **Commands → Doctor**.

### The game crashes or won't start

1. **Press Launch Vanilla.** If the plain game also crashes, the problem isn't a
   mod. Verify the game in Steam: right-click Ravenswatch → **Properties** →
   **Installed Files** → **Verify integrity of game files**.
2. **Find the mod that causes it.** Switch off half your mods and try again. If
   the crash is gone, the culprit is in the half you switched off. Keep halving
   until you find it.
3. **Check the Log page.** If a script mod crashes the game three times in a row
   while it's starting, RSMM skips it on the next start and the **Log** page says
   which mod. Press **Try again** once it's fixed.

With the modding tools, `rsmm safe-mode` switches off every mod and re-applies, so
you can start from a clean slate.

### "Conflicts" appeared in the sidebar

Two of your switched-on mods change the same part of the game. Open the
**Conflicts** page to see which. Only one can win (the one that loads later), so
switch off the one you want less.

### A mod shows "missing deps"

The mod needs another mod to work. Its page names the missing one. Install it from
**Browse**.

### The game updated and my mods stopped working

A game update replaces files and switches your mods off. The app shows **Ravenswatch
updated — your mods were disabled by the game update**. Press **Repair**, then
**Launch Modded**.

Still broken? The mod may need an update from its author. Check the **Library**
for updates.

With the modding tools: `rsmm restore --all`, verify the game files in Steam,
then `rsmm apply`.

### I want the plain game back

- **For one session:** press **Launch Vanilla**.
- **For good:** **Commands → Restore originals**, or `rsmm restore --all`.
- **To be extra sure:** verify the game files in Steam.

`rsmm restore --all` is safe to run as often as you like. If you see leftover
files ending in `.rsmm.bak` in the game folder, a restore was interrupted; run it
again.

## Script (Lua) mods

### Script mods don't do anything

Script mods need the **loader**, a file called `winhttp.dll` that sits next to
`Ravenswatch.exe`.

- **Windows, with the app:** the app installs and updates the loader each time it
  starts. Run **Commands → Doctor** to check it's there.
- **With the modding tools:** run `rsmm install-loader`. Note that
  `rsmm restore --all` removes the loader, so install it again afterwards.
- **Linux and Steam Deck:** Steam needs a launch option to load it. See
  [Script mods on Linux and Steam Deck](/getting-started/install/#script-mods-on-linux-and-steam-deck).

Then check the **Log** page for errors from the mod.

### Reading the log

The **Log** page shows what script mods wrote while the game was running.

- **problems only** shows just the lines where something failed (`err`) or looked
  wrong (`warn`). A line without a tag isn't necessarily fine; it just wasn't
  sorted.
- **Earlier sessions:** the drop-down lists the last 20 game sessions, so a crash
  from a few launches ago is still there.

With the modding tools: `rsmm log` shows the latest log, `rsmm log -f` follows it
live, `rsmm log --errors` shows only problems, and `rsmm log --list` lists earlier
sessions.

### Share your log

Logs are long. Pasting one into Discord or a GitHub issue cuts it off and scrambles
it. Share a link instead:

1. Open **Log**.
2. Press **Share link**.
3. Write what went wrong, check the preview, and press **Upload and get link**.
4. Paste the link where you're asking for help.

The upload always starts with a short header naming your app version and
operating system, because those are the first things anyone helping you will
ask. Three switches in that window are on by default:

- **include mod list** adds which mods are installed and switched on.
- **include app log** adds the app's own log, which matters when the app itself
  misbehaves rather than the game.
- **hide personal details** replaces your Windows user name, home folder, email
  addresses, IP addresses, Steam IDs and player names with placeholders.

**Read the preview before uploading.** Hiding personal details works by searching
the text for patterns, so it's a good safety net, not a guarantee. Anyone with
the link can read the page, so treat it as public. It's deleted automatically
after 30 days.

## Modding tools

### `'python' is not recognized`, or typing `python` opens the Microsoft Store

Python isn't installed, or Windows can't find it. Reinstall Python from
[python.org](https://www.python.org/downloads/) and **tick "Add python.exe to
PATH"** on the first screen. Then close the terminal and open a new one.

If the Microsoft Store still opens, go to **Windows Settings → Apps → Advanced app
settings → App execution aliases** and switch off the two **python** entries.

### `'rsmm' is not recognized` or `rsmm: command not found`

The terminal isn't in the right folder, or the environment isn't switched on. Do
the [every-time steps](/getting-started/modding-tools/#every-time-you-come-back)
again. The line should start with `(.venv)`.

### `running scripts is disabled on this system` (PowerShell)

Use **Command Prompt** instead, or run this once in PowerShell:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

### `error: externally-managed-environment` (Linux)

You ran `pip install` without switching the environment on. Run
`source .venv/bin/activate` in the `RavenswatchModManager` folder, then try again.

### `ensurepip is not available` or `No module named venv` (Linux)

Install Python's environment support, then create the environment again:

```sh
sudo apt install python3-venv
python3 -m venv .venv
```

### `rsmm` can't find the game

Tell it where the game is with the `RSMM_GAME_DIR` setting, as shown in
[Set up the modding tools](/getting-started/modding-tools/#5-check-that-it-works).
For a single command you can also add `--game-dir "path\to\Ravenswatch"`, for
example `rsmm doctor --game-dir "D:\Games\Ravenswatch"`.

### `rsmm lint` shows `[FAIL]`

Read the line: it says what's wrong and often suggests the right spelling
(`did you mean 'value'?`). `[WARN]` lines are only suggestions and don't stop
your mod from working.

### `rsmm apply` can't resolve a path

The file path in your mod doesn't match a file the game has. Check the spelling
and use forward slashes (`/`). `rsmm assets search <word>` finds the right path,
for example `rsmm assets search Juliet`.

### Two of my own mods overwrite each other

When two mods replace the same file, the later one wins. `rsmm diff MyMod` lists
the game files a mod changes and which other mods touch them too. Mods that use
`[[patch]]` blocks can change different values in the same file without clashing;
see [Two override strategies](/guides/modding/#two-override-strategies).

## Still stuck?

Open an issue on [GitHub](https://github.com/Ovilli/RavenswatchModManager/issues)
and include:

- your operating system,
- your RSMM version (**Settings → About**),
- your Ravenswatch version,
- what you did and what happened,
- a [shared log link](#share-your-log), which is far more useful than a pasted
  excerpt,
- any error messages or screenshots.

---

# Build a mod with an AI assistant

> How to point ChatGPT, Claude, or a coding agent at RSMM so it builds a mod that actually loads.

Source: https://docs.rsmm.me/guides/ai-assistant/

Ravenswatch ships no official mod support — no Workshop, no loader, no
documented file format. An assistant asked "write me a Ravenswatch mod" with
nothing else to go on will either refuse or invent a plausible-looking mod
format that the game will never load. This page is how to give it the real one.

## The short version

Paste this at the start of the conversation:

```text
I'm modding Ravenswatch with the Ravenswatch Mod Manager (RSMM).
Read https://docs.rsmm.me/llms-mods.txt first — it is the complete
mod-authoring documentation in one file. Follow it exactly; do not
invent a mod format. Then help me build: <what you want>.
```

Any assistant that can fetch a URL will then be working from the real
manifest grammar, the real content kinds, and the real CLI.

## The machine-readable entry points

| URL | What it is | When to use it |
|-----|-----------|----------------|
| [`rsmm.me/llms.txt`](https://rsmm.me/llms.txt) | What RSMM is, and the shortest path from "I want a mod" to a working one | An assistant that has never heard of RSMM |
| [`docs.rsmm.me/llms-mods.txt`](https://docs.rsmm.me/llms-mods.txt) | Every authoring page, full text, one fetch | **Building a mod** |
| [`docs.rsmm.me/llms.txt`](https://docs.rsmm.me/llms.txt) | Link index of every docs page, grouped by section | Picking specific pages to read |
| [`docs.rsmm.me/llms-full.txt`](https://docs.rsmm.me/llms-full.txt) | The above plus ~30 pages of engine reverse-engineering notes | Working on RSMM itself |

Use `llms-mods.txt`, not `llms-full.txt`, to build a mod. The full corpus is
mostly vtable layouts and crash triage written for people extending RSMM's
engine support; feeding it to an assistant spends most of its context on
material it cannot act on, and dilutes the rules that matter.

## Rules an assistant gets wrong by default

These are the assumptions carried in from modding other games. State them
explicitly if your assistant starts drifting.

**A mod ships data, not code.** The deliverable is a `manifest.toml` with
`[[content]]` and `[[patch]]` blocks plus assets the SDK emits — never a Python
script that pokes at game files. `rsmm lint` fails any `*.py` in a mod that
isn't a sanctioned lifecycle hook, so a script-shaped answer doesn't just
violate convention, it fails CI. See [Mods ship data, not
code](/concepts/data-not-code/).

**Mod Lua never touches engine internals.** No literal game addresses, no
`_internal`, no `peek`/`poke`/`read_*`/`write_*`, no `engine.resolve`. Only the
high-level `R.*` API. Also lint-enforced. If the capability you want doesn't
exist in `R.*` yet, that's an RSMM change, not a mod change.

**Don't guess at content kinds.** The list of what can be modded is fixed and
each kind carries an honesty rating — `confirmed`, `experimental`, or `guess`.
Registering a kind rated below `confirmed` raises unless the mod opts in with
`sdk.Mod(..., experimental=True)`. An assistant will happily invent a kind name
that sounds right; `rsmm lint` will reject it. See [Content
kinds](/concepts/content-kinds/).

**Ravenswatch is not a Unity game.** This one is worth stating out loud,
because a model that doesn't know the engine reaches for the most common one.
Ravenswatch is native C++ (FMOD, Epic Online Services, D3D12) — there is no
`Ravenswatch_Data/`, no `Assembly-CSharp.dll`, no mono runtime, and **BepInEx,
Harmony, MelonLoader and DLL plugins will not load**. RSMM's loader is a
`winhttp.dll` proxy with MinHook and an embedded Lua 5.4 VM.

**A mod's Lua entry point is `init.lua` at the mod root**, and the API is `R.*`
via `local R = require "rsmm"`. Engine calls go through
`R.engine.call(name, ...)` by semantic name against a hand-curated symbol map.
There is no `rsmm.call()`, and the map is a few hundred named symbols — not the
tens of thousands of raw game functions an assistant may claim are exposed.

**Don't hand-edit the game folder.** Cooked asset paths under
`DarkTalesResources/_Cooking/` are ciphered, and RSMM tracks what it replaced
so it can roll back. Hand-edits there corrupt that state. Every change goes
through `rsmm apply` / `rsmm restore --all`.

## Verify what it produced

An assistant's mod is a hypothesis until the toolchain agrees. Three commands,
in order — each one catches a different class of wrong:

```sh
rsmm lint            # manifest grammar, asset paths, the rules above
rsmm apply           # install into the game (rsmm restore --all rolls it back)
rsmm pack <mod-id>   # zip it for the registry
```

`rsmm schema <kind>` lists the vanilla ids available to clone; `rsmm items
list` does the same for magical objects specifically. Run one and paste the
output back rather than letting the assistant guess.

Every command that names a mod takes its **id**, not a path — `rsmm lint MyMod`,
not `rsmm lint mods/MyMod`, which fails with `no such mod`.

## Related

- [Your first mod](/getting-started/first-mod/) — the same loop, by hand.
- [Mod authoring guide](/guides/modding/) — scaffold through shipping.
- [CLI reference](/reference/cli/) — every command.

---

# Custom enemies

> Clone, restat, and (eventually) spawn your own enemies and bosses.

Source: https://docs.rsmm.me/guides/custom-enemies/

import { Aside, Badge, Steps, LinkCard, CardGrid } from '@astrojs/starlight/components';

Custom enemies are a **clone-and-patch** kind: you start from a vanilla enemy,
change its stats/assets, and register it as a new definition. <Badge text="Confirmed" variant="success" />

<Aside type="tip" title="Proven in game (2026-09-24)">
A clone spawns in real camps: a Gnolls-tribe clone wearing a Mud Crab body
appeared in Storm Island gnoll camps. The def joins its tribe's roster when it
loads, and camps pick from that roster. Keep the clone's **tribe** set to one
the target biome's camps use. Keep its **body** (`entity`) to a creature that
biome streams. Leave **`power`** near vanilla: it is the enemy's cost against
the camp's power budget, not its spawn odds, and a clone priced above the budget
is never picked.
</Aside>

## Author one

The enemy kind is confirmed, so no `experimental` opt-in is needed.

```python title="build.py"
from rsmm import sdk

with sdk.Mod("MyEnemies") as mod:
    mod.enemy(
        "Frost_Goblin",
        base="Goblins/Goblin_Warrior",   # vanilla donor to clone
        name="Frost Goblin",
        # **fields override stat-block values on the clone
    )
```

Equivalent declarative form:

```toml title="mods/MyEnemies/manifest.toml"
[mod]
id = "MyEnemies"

[[content]]
kind = "enemy"
id   = "Frost_Goblin"
base = "Goblins/Goblin_Warrior"
name = "Frost Goblin"
```

`Mod.boss(...)` takes the same shape. Bosses are **not** a separate class — they
are ordinary enemies tagged into the boss flag-list and gated by the boss-timer
controller.

Run `./rsmm apply` to cook and register the definition.

## How enemies spawn

Spawning is **selector-driven**, not a direct "place enemy X" call. The chain:

```mermaid
flowchart LR
    E["oCDtEnemyDefinition<br/>(one stat block)"] --> T["oCDtEnemyTribeDefinition<br/>(group / faction)"]
    T --> S["Camp spawn selector<br/>(flag-list, tag-filtered)"]
    C["oCDtEnemyCampTierDefinition<br/>(camp difficulty tier)"] --> S
    S --> R["runtime spawn in a camp"]
```

An enemy reaches a run by being a member of a **tribe**, which a **camp
selector** picks via tags/flags at the right difficulty tier. So registering a
definition is necessary but not sufficient — something must select it.

<Aside type="note" title="Known scaffold bug">
The early scaffold patched the *tribe definition* directly (`tribe_patch`) to
inject the new enemy. That's the wrong layer — selection happens through the
flag-list selector, not the tribe table. The open task is confirming the
selector resolves the new enemy from the runtime library, then driving the
membership from there.
</Aside>

### Class map

The full camp/enemy machinery, for when you need the internals:

| Class | UID | Library | Purpose |
|---|---|---|---|
| `oCDtEnemyDefinition` | `0x176debb7` | `0x1414118c0` | one enemy stat block |
| `oCDtEnemyTribeDefinition` | — | `0x141411200` | tribe = group / faction |
| `oCDtEnemyCampTierDefinition` | `0x176e18f8` | `0x141411560` | difficulty tier of one camp |
| `oCDtEnemyCampDifficultyDefinition` | — | `0x141411710` | global difficulty curve |
| `oCDtEnemyCampEntitySelectorToSpawnEntityCpntSettings` | `0x16b7d175` | — | per-camp spawn selector |
| `oCDtEnemyCampEntitySelectorToSpawnTribeEntrySettings` | `0x16b81d80` | — | one tribe entry inside a camp |
| `oCDtEnemyFlagListEntitySelectorToSpawnEntityCpntSettings` | `0x17019bf9` | — | tag-filtered enemy selector |

`oCDtEnemyDefinition` is fully registered (size `0x350`, factory `FUN_14030a190`).
The runtime spawn primitive itself — the `vftable[3]` call that constructs an
entity at a position — is documented in [Spawning](/reverse-engineering/spawning/).

## Going deeper

<CardGrid>
  <LinkCard title="Spawning (RE)" href="/reverse-engineering/spawning/" description="The engine's runtime entity-creation primitive." />
  <LinkCard title="Mod hooks (RE)" href="/reverse-engineering/mod-hooks/" description="Enemies, bosses, and the level-load pipeline." />
  <LinkCard title="SDK: Mod.enemy" href="/reference/sdk-api/builder/" description="Generated API reference for the enemy builder." />
  <LinkCard title="Authoring mods" href="/guides/modding/" description="The full content-kind authoring guide." />
</CardGrid>

---

# Custom items

> Clone a vanilla magical object into your own item — the guided CLI flow, end to end.

Source: https://docs.rsmm.me/guides/custom-items/

import { Aside, Badge, Steps } from '@astrojs/starlight/components';

Custom magical objects are the one **confirmed** clone-and-patch kind: verified
in-game, no experimental opt-in, no loader required. <Badge text="Confirmed" variant="success" />

An item mod is a `manifest.toml` and nothing else. You pick a vanilla item to
clone, rename it, repoint its icon, and retune its numbers; `rsmm apply` cooks
the definition and registers it.

## The guided flow

<Steps>

1. **Scaffold from a real base.**

   ```sh
   ./rsmm new IronCrabHide --kind item --base Common/Armor_Per_Object \
       --name "Iron Crab Hide" --desc "Bonus armor per rare object collected."
   ```

   Run it without `--base` at a terminal and you get a searchable picker of
   every vanilla item instead. Both spellings of a base work — the bare
   `Armor_Per_Object` or the rarity-qualified `Common/Armor_Per_Object`.

2. **Read what it wrote.**

   ```toml title="mods/IronCrabHide/manifest.toml"
   [[content]]
   kind          = "item"
   id            = "IronCrabHide_item_1"
   base          = 'Common/Armor_Per_Object'
   name          = 'Iron Crab Hide'
   description   = 'Bonus armor per rare object collected.'
   rarity        = 'Common'
   icon          = 'Objects\UI_Object_GreenArmor.png'
   value_patches = [['Armor per Object Value', 2.0, 2.0]]
   ```

   The icon, rarity and every `value_patches` entry are **read out of the base
   you chose**, not templated. The third number in each patch is the one you
   change; it starts equal to the current value, so the scaffold applies
   unchanged.

3. **Retune and check.**

   ```sh
   ./rsmm items show Common/Armor_Per_Object   # every editable label + default
   ./rsmm lint IronCrabHide
   ./rsmm apply
   ```

</Steps>

## Choosing a base

```sh
./rsmm items list --rarity Common --grep armor
./rsmm items icons --grep crab      # usable icon stems
./rsmm items show Damage_Power      # labels, defaults, [shadowed] markers
```

The base decides the item's *mechanic* — cloning is a byte-level copy with the
name, description, icon and magnitudes rewritten. There is no way to author a
brand-new effect from the manifest; pick the vanilla item whose behaviour you
want and retune it.

## Why some fields don't get seeded

`rsmm new` deliberately leaves two classes of value field out of the scaffold,
and prints a note for each it skipped:

- **Shadowed labels.** The inline float is overridden by a selector (a card
  count, a stack counter), so patching it changes nothing. `set_value_after_label`
  refuses these outright, and `rsmm items show` marks them.
- **Labels whose default doesn't round-trip.** `rsmm items show` discovers
  value fields best-effort, and occasionally reports a `(label, default)` pair
  that can't be re-found for patching. Seeding one would make the scaffold fail
  its own lint, so it's dropped.

<Aside type="tip">
Patches are anchored on **both** the label and the expected current value, and
the edit is 4 bytes to 4 bytes. That means a wrong "current" is an error rather
than a corrupted asset — if `rsmm lint` reports `expected value X not found`,
re-read the real default with `rsmm items show`.
</Aside>

## What ships

`rsmm apply` writes the cooked entity under
`EntitySettings/Objects/Magical_Objects/<rarity>/`, appends the name and
description to the `Magical_Objects~GAM.xls` text bank, and registers the new
path so the engine loads it — the same `UsedRscList.ot` registration every new
asset goes through. Removing the mod is `./rsmm restore --all`.

<Aside type="caution">
A clone keeps the base's registered node GUIDs. Its identity GUID is distinct,
but if the player also owns the base item in the same run, the hero's owned-set
can dedup the clone at grant time. Cloning a rarely-rolled base avoids it.
</Aside>

---

# Custom skills (talents)

> Relabel, restat, and bind behaviour to a hero's level-up talents.

Source: https://docs.rsmm.me/guides/custom-skills/

import { Aside, Badge, Steps, LinkCard, CardGrid } from '@astrojs/starlight/components';

<Aside type="tip" title="New to talent modding?">
Start with [Talent modding, step by step](/guides/talent-tutorial/). It walks
through changing a talent's numbers, name and description from scratch.
</Aside>

A hero's **skills** are the talents on the level-up cards and in the Skill Menu.
The `skill` kind makes a custom talent **visible** by overriding the per-hero
text bank. <Badge text="Confirmed" variant="success" />

<Aside type="caution" title="What works today">
**`mode="relabel"` works now** — it overrides an existing skill's display text
(name + description) in place, so your talent shows on that skill's real card and
menu slot. Count-neutral and reliable.

Adding a **net-new** skill row is **not** supported: `mode="clone"` is refused,
because an added herodef row crashed the game twice, and a hero's talent count
is fixed. `mode="repoint"` is refused too — renaming a herodef row was
playtested and changes nothing visible (the shown name comes from the hero
entity's controller key).
</Aside>

## Author one

`skill` is a `confirmed` kind, so no experimental opt-in is needed.

```python title="build.py"
from rsmm import sdk

with sdk.Mod("MySkills") as mod:
    mod.skill(
        "rsmm_lightning_dash",
        hero="Aladdin",
        source="Attack Dive",        # an existing skill to repurpose
        name="Lightning Dash",       # shown on the card / menu
        description="A dash that crackles with lightning.",
        # mode="relabel" is the default
    )
```

Equivalent declarative form:

```toml title="mods/MySkills/manifest.toml"
[mod]
id = "MySkills"

[[content]]
kind        = "skill"
id          = "rsmm_lightning_dash"
hero        = "Aladdin"
source      = "Attack Dive"
name        = "Lightning Dash"
description = "A dash that crackles with lightning."
mode        = "relabel"
```

Run `./rsmm apply` to write the text override into the live install. The display
name resolves against the hero's text bank, so **apply must see a Ravenswatch
install** — `emit` errors out if no install is reachable.

<Aside type="note" title="Identifying a source skill">
`source` accepts either the skill's controller suffix (`Attack Dive`) or its
text-key base (`Skill_Attack_Dive`). The two name the same row.
</Aside>

## Modes

| `mode` | What it edits | Status | Use it for |
|---|---|---|---|
| `relabel` *(default)* | Hero text bank values only (`Skill_<src>_Name` / `_Desc`) | **Works** — visible & count-neutral | Repurposing an existing talent's name/description |
| `repoint` | Would rename the herodef row + remint its GUID | **Refused** — playtested, changes nothing visible | — |
| `clone` | Would add a NET-NEW herodef row | **Refused** — crashed the game twice | — |

## Bind behaviour

Relabelling changes only the **text**. To make the talent *do* something custom,
bind logic in a loader Lua script keyed on the talent's identity:

```lua title="mods/MySkills/scripts/lightning_dash.lua"
R.talent.on_pick("rsmm_lightning_dash", function(ctx)
  -- runs when this talent card is picked
end)

-- or define on a hero:
R.talent.define{ hero = "Aladdin", pickable = true, on_pick = function(ctx) ... end }
```

Behaviour binds on `POWER_UP_COLLECT_REQUEST` via the gameplay event bus — it
does not require any herodef edit. See [Mod hooks](/reverse-engineering/mod-hooks/)
for the identity-offset details.

## Net-new skills

Not supported, by decision: a hero's talent count is fixed. An added herodef
row crashed the game, and a talent injected at runtime drew on top of its
source in the Book grid, because the grid places a talent by its identity
rather than by list position. For something genuinely additive, ship a
pickable magical-object card, whose pool does grow.

## How a skill is wired

| Layer | Where | Purpose |
|---|---|---|
| Display name / desc | `Text/Hero_<Hero>_Common~GAM.xls.LocalText.gen`, keys `Skill_<Suffix>_Name` / `_Desc` | What the player reads on the card / menu |
| Skill row (identity) | `Definitions/Heroes/<Hero>.herodef.ot.DtHeroDefinition.gen` | The list of skills the hero owns + each row's GUID |
| Behaviour | gameplay event bus (`POWER_UP_COLLECT_REQUEST`) | Custom code on pick |

The name a player sees comes from the hero ENTITY's controller text key, not
from the herodef row, which is why relabel works and renaming the row does not.

## Going deeper

<CardGrid>
  <LinkCard title="Skills system (RE)" href="/reverse-engineering/skills-system/" description="How skills are stored, the crash mechanism, and the grid-layout wall." />
  <LinkCard title="Mod hooks (RE)" href="/reverse-engineering/mod-hooks/" description="The loader detours, env flags, and skill-injection path." />
  <LinkCard title="Custom enemies" href="/guides/custom-enemies/" description="The other clone-and-patch content kind." />
  <LinkCard title="SDK: Mod.skill" href="/reference/sdk-api/builder/" description="Generated API reference for the skill builder." />
  <LinkCard title="Authoring mods" href="/guides/modding/" description="The full content-kind authoring guide." />
</CardGrid>

---

# Example mods

> Real, working mods you can copy — from a one-liner to a custom item.

Source: https://docs.rsmm.me/guides/examples/

import { Tabs, TabItem, Steps, Aside, LinkCard, CardGrid } from '@astrojs/starlight/components';

Every example below is a complete mod. Copy the files into `mods/<id>/`, set
`enabled = true`, and run `./rsmm apply`. Source lives in
[`docs/ExampleMods/`](https://github.com/Ovilli/RavenswatchModManager/tree/main/docs/ExampleMods).

<Aside type="note">
Examples ship `enabled = false` so they don't apply by accident. Flip it to
`true` (or enable them in the desktop app) before `apply`.
</Aside>

## Pick a starting point

<CardGrid>
  <LinkCard title="Hello (Lua)" href="#hello--smallest-lua-mod" description="The minimal SDK mod: log on ready, count ticks." />
  <LinkCard title="Magic item (data)" href="#magic-item--declarative-content" description="A custom magical object via a [[content]] block — no code." />
</CardGrid>

## Hello — smallest Lua mod

The minimum to prove the loader + SDK work: log once when the game is ready and
count ticks. No assets, just `manifest.toml` + `init.lua`.

<Tabs>
  <TabItem label="manifest.toml">
    ```toml title="mods/ExampleSdkHello/manifest.toml"
    [mod]
    id          = "ExampleSdkHello"
    name        = "Example: SDK hello"
    version     = "0.2.0"
    author      = "rsmm-examples"
    description = "Smallest possible mod using SDK v3. Logs once on ready + bumps a counter every tick."
    enabled     = false
    sdk_version = ">=3.0,<4"
    ```
  </TabItem>
  <TabItem label="init.lua">
    ```lua title="mods/ExampleSdkHello/init.lua"
    -- Smallest possible mod using SDK v3.
    -- Demonstrates: require "rsmm", R.health.checkpoint, R.on, R.log, R.kv.

    local R = require "rsmm"
    R.health.checkpoint("per_mod:ExampleSdkHello")

    R.on("ready", function()
        R.log("[Hello] loaded; SDK ready")
    end)

    R.on("tick", function()
        local n = R.kv.inc("tick_count")
        if n == 1 or n % 20 == 0 then
            R.log("[Hello] tick #" .. n)
        end
    end)
    ```
  </TabItem>
</Tabs>

<Aside type="caution">
Lua mods need the loader DLL (`winhttp.dll`). Texture/asset mods do **not** —
see [Set up the modding tools → Script (Lua) mods](/getting-started/modding-tools/#script-lua-mods).
</Aside>

## Magic item — declarative content

A custom magical object, cloned-and-patched from a vanilla rare item. **No
code** — the `[[content]]` block tells the SDK to cook a new item end-to-end.

```toml title="mods/ExampleMagicItem/manifest.toml"
[mod]
id          = "ExampleMagicItem"
name        = "Example: Magic Item"
version     = "0.3.0"
author      = "rsmm-examples"
description = "Declarative custom magical object via [[content]] block."
enabled     = false
sdk_version = ">=3.0,<4"

[[content]]
kind        = "item"
id          = "Iron_Crab_Hide"
base        = "Common/Armor_Per_Object"
name        = "Iron Crab Hide"
description = "Bonus armor per rare object collected."
rarity      = "Common"
```

The `kind = "item"` builder resolves the `base` donor, cooks the new item, and
`rsmm apply` syncs the game-side registration (versiondef + UsedRscCache). You
write the manifest; the SDK does the rest. See
[Authoring mods](/guides/modding/) for every `[[content]]` kind.

## React to in-game events

The loader bridges the game's named events to the Lua bus, so a mod subscribes
by name — `enemy_killed`, `unlock_hero`, `game_start`, `level_up_reach`, … (one
hook re-publishes every named analytics event; browse the list in the
[event systems reference](/reverse-engineering/event-systems/#analytics-firehose)).
Needs the loader DLL. Both event buses are armed by default; the loader
skips publishing entirely when no mod has subscribed.

```lua title="mods/ExampleEvents/init.lua"
local R = require "rsmm"

R.on("enemy_killed", function(ev)
    R.kv.inc("kills")                          -- persists across restarts
    R.log(("kill #%d"):format(R.kv.get("kills")))
end)

-- Take a whole family at once, and stop listening when you're done.
local h = R.on_match("^gameplay:ABILITY_", function(ev, name)
    R.log("ability event:", name)
end)
R.once("run:end", function() R.off(h) end)
```

Not sure what fires? Let the loader tell you — it records every event it sees
with its payload keys:

```lua
R.on("ready", function()
    R.schedule.after(120, function() R.events.dump() end)  -- play, then read _log.txt
end)
```

These events are observation-grade: they fire after the action and carry the
event name + sequence, not a live entity handle.

## Call engine functions

`data/symbols.json` maps semantic names to engine functions and records each
one's `cabi`, so a mod calls them like methods — no addresses, no signatures.
Browse with `rsmm symbols list` or `R.engine.names()`.

```lua
local res = R.engine.fn.Resource_LookupByPath(path, 0, 0, 0)
-- equivalent: R.engine.call("Resource_LookupByPath", path, 0, 0, 0)
```

## Persistent state

`R.kv` stores per-mod scalars (string/number/boolean) to
`<mod_dir>/.rsmm_state`, reloaded on the next launch. Loaded lazily, flushed
automatically on `exit`, or on demand with `R.kv.save()`.

```lua
R.kv.inc("runs_played")          -- survives a game restart
R.kv.set("last_hero", "Scarlet")
local n = R.kv.get("runs_played", 0)
```

## Recording what a playtest proved

Some questions can only be answered by the running game, and a playtest is
expensive: you play, then somebody reads the log. `R.exp` turns one run into
several answers by recording verdicts instead of prose.

```lua
-- answerable on the spot
R.exp.run("tiles_registered", "does the engine register a mod tiledef?", function()
    local n = count_tiledefs()
    R.exp.observe("tiles_registered", "tiledefs", n)
    return n > 237, n .. " tiledefs"
end)

-- the answer arrives later, from a handler
R.exp.case("tile_placed", "is a mod tile ever placed?")
R.on("gameplay:OPEN_CHEST", function() R.exp.verdict("tile_placed", true, "seen") end)
```

Read them back after the run:

```sh
./rsmm exp
```

Each case is `PASS`, `FAIL`, or `NO-DATA` — and `NO-DATA` is a result too: it
says the code path never ran. Verdicts are written as they resolve, so a crash
part-way through a run keeps everything answered up to that point. They are
stored in `R.kv`, so keep observations to a handful per case.

A mod with no Lua at all can still ask a question. Declare it in
`manifest.toml` and it shows up as `NO-DATA` before the run:

```toml
[[experiment]]
id       = "icon_replaced"
question = "do teleporter minimap icons become the shrine icon?"
```

Some answers are only ever on the screen. Quit the game — the loader rewrites
the state file when it exits — and record what you saw:

```sh
./rsmm exp answer minimap-icon-test icon_replaced pass -m "shrine icon on every teleporter"
```

Those are marked `(reported by you)` in the table, because a verdict somebody
typed is a different grade of evidence from one the game measured.

Guard `R.exp` if your mod ships to other people: a newer mod meets an older
planted SDK whenever someone updates the mod before running
`rsmm update-loader`, and an unguarded call stops the whole mod from loading.

```lua
local exp = R.exp or { case = function() end, observe = function() end,
                       verdict = function(_, p) return p end,
                       run = function(_, _, fn) pcall(fn) end }
```

## Apply any example

<Steps>
1. Copy the example folder into your `mods/` directory.
2. Set `enabled = true` in its `manifest.toml`.
3. Apply and launch:
   ```sh
   ./rsmm apply
   ./rsmm run
   ```
</Steps>

## More examples in the repo

- `ExampleEvents` — subscribe to in-game events (`enemy_killed`, `unlock_hero`, …) and count them.
- `ExampleEngineCall` — call named engine functions via `R.engine.fn` / `R.engine.call`.
- `ExampleSeedPin` — pin the run RNG seed via the `R._internal` escape-hatch + per-mod config (`R.config.get`).
- `ExampleSdkAll` — exercises the full SDK surface.
- `ExampleCustomSkill` — relabels one of Aladdin's skills into a custom talent (visible on his level-up cards & Skill Menu). See [Custom skills](/guides/custom-skills/).
- `HyperAggro` — a gameplay tweak mod.

Browse them all in [`docs/ExampleMods/`](https://github.com/Ovilli/RavenswatchModManager/tree/main/docs/ExampleMods).

---

# First mod, by kind

> A minimal, working manifest for every content kind — what it changes, how to prove it in game, and the one trap that bites first.

Source: https://docs.rsmm.me/guides/first-mod-by-kind/

Fifteen content kinds ship with the SDK, and every one of them starts the same
way: a folder under `mods/`, a `manifest.toml`, `rsmm apply`. What changes per
kind is the handful of fields in the `[[content]]` block — and the way you
prove the change actually landed.

This page is one starting mod per kind. Each snippet is a **complete**
`manifest.toml`: copy it into `mods/<id>/manifest.toml`, adjust the ids, apply.

:::note[Before the first one]
Read [Your first mod](/getting-started/first-mod/) for the scaffold, and
[Content kinds & confidence](/reference/sdk-api/kinds/) for which kinds are
proven in-game. A kind rated below `confirmed` needs `experimental = true` in
`[mod]` — the snippets below already carry it where it is required.
:::

## The loop, every time

```sh
./rsmm new MyMod          # scaffold mods/MyMod/
./rsmm lint MyMod         # manifest, asset paths, confidence gate
./rsmm restore --all      # back to vanilla first — restore wipes the loader
./rsmm apply              # install this mod's files
./rsmm install-loader     # re-plant the loader (apply does not)
./rsmm run                # launch through Steam
```

`restore --all` before every `apply` is not superstition: it is how you avoid
testing a mod on top of the last one's leftovers, and it is the uninstall path
you should expect to work at the end.

---

## `item` — a new magical object

**What the player sees.** A brand-new item in the compendium that drops, is
offered by chests, and works.

**Or build it on a page.** The **Items** tab of `rsmm editor`, or the
[web editor](/guides/web-editor/), writes this block from a picked base item.

```toml
[mod]
id          = "SwiftAttacks"
name        = "Swift Attacks"
version     = "0.1.0"
author      = "you"
description = "A faster cousin of the Ace card."

[[content]]
kind  = "item"
id    = "Swift_Attacks"      # SAME BYTE LENGTH as base (13) — see the trap
base  = "Damage_Attack"
name  = "Swift Attacks"
description = "Attack speed, and nothing else."
value_patches = [["Attack Speed Value", 0.15, 0.30]]
```

**Prove it.** Start a run, open the compendium — the item is listed. Then take
it from a chest and watch the value you patched.

**Trap.** The clone pipeline is length-preserving: `id` must match `base` in
byte length. Browse bases with `./rsmm items list`, and a base's editable
value labels with `./rsmm items show <base>` — a label marked `shadowed`
accepts the edit and changes nothing in game.

**Change the shipped item instead.** `mode = "replace"` takes the same fields
but edits the base itself rather than adding a copy beside it: no new id, the
base keeps its rarity, and `name`/`description` rewrite the text the item
already shows. The shipped file is backed up and comes back when the mod is
turned off. The editor's **Replace this item** / **Make a copy** switch picks
between the two.

```toml
[[content]]
kind          = "item"
id            = "Damage_Attack"
mode          = "replace"
base          = "Damage_Attack"
value_patches = [["Attack Speed Value", 0.15, 0.30]]
```

**Also does the opposite.** `mode = "ban"` with `items = [...]` removes vanilla
items from the catalog instead — the multiplayer-correct way to disable one.

---

## `talent` — retune a talent

**What the player sees.** The same talent card, different numbers.

**Or build it on a page.** The **Talents** tab of `rsmm editor`, or the
[web editor](/guides/web-editor/), lists every value a hero has and writes this
block (and `skill` blocks for renamed cards).

```toml
[mod]
id          = "JulietBuff"
name        = "Juliet Talent Buff"
version     = "0.1.0"
author      = "you"
description = "Juliet's dash shield lasts longer."

[[content]]
kind = "talent"
id   = "dash_shield_duration"
hero = "Juliet"
file = "Hero_Juliet.entity"
value_patches = [
  { label = "Skill Dash Shield Duration", old = 6.0, new = 9.0 },
]
```

**Prove it.** Take the talent in a run and read the card: the number moves.

**Trap.** A label can exist in several of a hero's entity files, and some values
are *shadowed* by an override node — the writer handles both, but you have to
name the label exactly, and `old` must match the shipped number or the apply
stops. Find labels, their files and their numbers with
`./rsmm talents Juliet --grep shield`, and see the
[talent tutorial](/guides/talent-tutorial/) for the card-text placeholders.

---

## `ability` — change a shipped hero's abilities in place

**What the player sees.** The same hero, an ability that behaves differently:
a number changed (a hit's stagger, a cooldown, a damage multiplier) or a link
rewired. No second hero is added, so the change applies to every run with that
hero, and `rsmm restore` puts the originals back.

**Or build it on a page.** The **Abilities** tab of `rsmm editor`, or the
[web editor](/guides/web-editor/): set a number, pick "Change the original
hero", and *Save to mod* writes this block. Choose "Make a separate custom
hero" there when you want a copy (`kind = "hero"`) instead, or an ability copied
with `clone`.

```toml
[mod]
id           = "BeowulfFireballNerf"
name         = "Beowulf Fireball Nerf"
version      = "0.1.0"
author       = "you"
description  = "Beowulf's Fireball staggers less."
experimental = true

[[content]]
kind = "ability"
id   = "BeowulfAbilities"
hero = "Beowulf"

[[content.abilities]]
set    = "Stagger Power Selector.entries[0][1]"
value  = 25
entity = "Hero_Beowulf_Ultimate_2_Fireball"
```

**Prove it.** Use the ability in a run and look at the effect: here the fireball
hits stagger enemies less than the 50 it ships with.

**Trap.** A hit's numbers often live in another file of the hero (the fireball's
stagger is in its own projectile file, hence `entity`), and a selector's number
is addressed as `Part.entries[i][j]`, not `Part.value`. The editor's search
lists matches in every file of a hero. `clone` steps are refused here: copying
an ability adds parts that only a custom hero builds. The kind is experimental
until the steps are proven in game.

---

## `entity` — edit any shipped entity in place

**What the player sees.** One shipped object behaving differently: a boss
spawner, a camp, a UI. It takes the same `set` / `link` / `add_link` /
`remove_link` steps as `ability`, aimed at one entity file that is not a hero's.
`rsmm restore` puts the original back.

```toml
[mod]
id           = "NoOvertimeTint"
name         = "No Overtime Tint"
version      = "0.1.0"
author       = "you"
description  = "Removes the red screen tint before and during overtime."

[[content]]
kind   = "entity"
id     = "boss_spawner_no_tint"
entity = "Objects/Map_Boss_Spawner/Map_Boss_Spawner_Graph_Model"

[[content.steps]]
remove_link = "State FX PreOvertime.while_active[1]"
```

**Prove it.** Let a chapter run into overtime: the screen stays its normal
colour while the banner, minimap ping and music still arrive.

**Trap.** `entity` is the path under `EntitySettings` (`.entity.ot` optional).
Part names and link indices are the ones `rsmm entity-graph` prints for that
file, and removing a link shifts the later indices of the SAME list, so remove
from the end first or list one step per field. `clone` steps are refused.

---

## `mesh` — put your model in the game

**What the player sees.** A shipped prop, weapon or body wearing your geometry.

```toml
[mod]
id          = "ShrineBlock"
name        = "Runestone Block"
version     = "0.1.0"
author      = "you"
description = "Replaces a ruin block with a runestone."

[[content]]
kind   = "mesh"
id     = "shrine_over_ruin_block"
target = "Scenery\\DarkHills\\Wall_Ruins_Block_Small_A.fbx"
model  = "art/shrine.glb"
```

**Prove it.** Walk a chapter that places the target mesh. Your shape is there,
lit and textured, with no other change.

**Trap.** The override is **global**: every tile that places that mesh now shows
yours. And replacing a *character* needs the right `transform.skin` —
`"gltf"` when you rigged to the game's bone names, `"rigid"` when you did not.
The default (`"transfer"`) assumes your mesh occupies the same space as the one
it replaces, and shreds a differently-shaped body on the first animation frame.

---

## `animation` — replace a clip with your own motion

**What the player sees.** A shipped animation, such as Piper's dash, playing your motion.

```toml
[mod]
id           = "PiperSpin"
name         = "Piper Spin Dash"
version      = "0.1.0"
author       = "you"
description  = "Piper spins through her dash."

[[content]]
kind   = "animation"
id     = "piper_dash"
target = "Characters\\Heroes\\Piper\\Animations\\Piper_Dash_Default.fbx"
source = "anims/piper_dash.glb"
```

**Prove it.** Dash in a run: the move plays your keys.

**Authoring in Blender or Maya.** `rsmm export-character Piper` writes one
`.glb` with the real armature (the game's bone names, hierarchy and bind pose),
the skinned body with its full materials (colour, normal and
metal/roughness/AO maps), the weapon or prop on the bone that carries it, and
every clip that fits that rig. `--skin Combat` exports a skin's look instead:
its materials, its body and its weapon (`--list-skins` names them). A piece
on a skeleton of its own, like the Combat cloak, comes in as a second armature
at its own origin: the entity does not say where it hangs, so place it by hand.
It imports as a posable, animated character.

For anything that is not a hero, use `rsmm export-model`. It exports any of the
game's 3,001 models: scenery, props, enemies, NPCs and mechanisms like chests.
Each comes with its full materials, and a rigged one also gets its skeleton and
every clip in its folder that fits it. `rsmm export-model --list Ogres` shows
what there is, and `rsmm export-model OgreHuman_GEO` writes one model.
`rsmm export-model --all -o export/` writes every model into a tree laid out
like the game's folders. That run is long, and `--no-textures` makes it much
faster.

Two settings matter:

1. **Set the scene frame rate to 60 *before* importing.** Clips mix a 30 fps
   grid with 60 fps keys where something snaps (Piper's weapon flips in half a
   frame). At 24 or 30 fps Blender drops those keys. At 60, all 45 of Piper's
   clips came back within 0.3 degrees after an import and export.
2. Export glTF with animations, keeping the action names.

Then `rsmm import-character edited.glb --mod my-piper` (add `--skin Combat` if
you exported a skin) writes the mod for you. It cooks every action, compares
its sampled poses with the shipped clip of the same name, and keeps only the
ones that moved more than `--threshold` degrees (default 1; an untouched round
trip stays under 0.5). The body is kept when its vertices no longer match the
shipped body. Each kept clip becomes a block like the one above, the body a
`kind = "mesh"` block with `transform = { skin = "gltf", submeshes = "map" }`
(weights bind by bone name, each submesh keeps its own material), and the
`.glb` is copied into the mod. It never overwrites an existing mod without
`--force`.

**Trap.** Bones are matched by **name**, and the target clip is the template:
it decides which bones exist. A bone your file does not animate is held at the
target's first pose (`strict = true` makes that an error). A bone the target
lacks is refused. Like `mesh`, the override is global: everything that plays
that clip plays yours.

---

## `poi` — a structure in a chapter

**What the player sees.** A shrine / cauldron / camp appearing on a map that
never had one.

A POI is a folder, and needs no `[[content]]` block at all. The mod's
`manifest.toml` is just the `[mod]` table; everything else lives beside the
model:

```
mods/MyShrine/
  manifest.toml
  pois/runestone_shrine/
      poi.toml
      model.glb
      albedo.png  normal.png  mra.png  icon.png
```

This is the shrine that was proven in game end to end: tile, mesh, minimap
marker and interaction.

```toml
# pois/runestone_shrine/poi.toml
base     = "Dark_Hills/6x6_Crystal_01"   # the tile it is generated as
chapters = ["Dark_Hills"]
kinds    = ["Crystal"]                   # which generator slots it may fill
copies   = 1

replaces      = "Objects_Common\\DreamCrystal_Medium.entity.ot"
entity_base   = "DarkHills\\SceneryObjects_DarkHills\\Wall_Ruins_Block_Small_A.entity.ot"
material_base = "Scenery\\DarkHills\\M_Walls_Ruins.mat.ot"
transform     = { fit = "rig", scale = 2.0 }
interactive   = true

[slots]
albedo = "Scenery\\DarkHills\\T_Walls_Ruins_ALB.tga"
mra    = "Scenery\\DarkHills\\T_Walls_Ruins_MRA.tga"
normal = "Scenery\\DarkHills\\T_Walls_Ruins_NRM.tga"

[marker]
icon          = "icon.png"
reveal_radius = 20000.0
```

**Prove it.** Run the chapter and look at the minimap: the icon draws, the prop
is interactable, and a mod can confirm its own placements from Lua
(`R.poi.placed`).

**Trap.** `kinds` must be slots that tiles of the base's size actually fill
— a 40×40 base can never fill a 6×6 `Fountain` slot, and the emit says so.
`weight` is a **tier**, not a spawn rate — raising it to make a POI
commoner is backwards. Use `copies`, which buys pool entries one for one.
Browse bases with `./rsmm poi list`.

---

## `enemy` — change what a camp spawns

**What the player sees.** Every Dark Hills camp full of treants, or a brand-new
creature among the usual ones.

```toml
[mod]
id           = "Treantfall"
name         = "Treantfall"
version      = "0.1.0"
author       = "you"
description  = "Dark Hills is a forest, and it has opinions."

[[content]]
kind   = "enemy"
id     = "treant_everywhere"
mode   = "override"          # rewrite a retail population in place
pools  = ["Dark_Hills"]
entity = "Enemies\\Treant\\Standard_Root_Treant.entity.ot"
```

**Prove it.** Load the chapter and fight the first camp: every creature in it
is a treant. List a biome's creatures with `./rsmm enemies pool Dark_Hills`.

**Trap.** `power` (old name `weight`) is a creature's **cost** against the
camp's power budget, not its spawn odds. A `mode = "clone"` enemy set to 20 was
priced out of every gnoll camp and never appeared. Leave it unset to keep the
base's cost. Imported creatures can also bring projectiles and attack
zones the destination chapter never loads; see
[Custom enemies](/guides/custom-enemies/).

---

## `reward` — ban or retune what spawns at reward points

**What the player sees.** No more locked chests in Avalon, or fewer of them.

```toml
[mod]
id           = "NoLockedChests"
name         = "No Locked Chests"
version      = "0.1.0"
author       = "you"
description  = "Chests spawn unlocked."

[[content]]
kind = "reward"
id   = "avalon_rewards"
base = "Camp_Rewards_Avalon_Update5"
ban  = ["Chest_Locked"]
```

**Prove it.** Play the chapter and count what the reward points produce. Pick a
number the game cannot reach on its own — `counts = { 2 = [3, 3] }` gave three
astrolabs where Dark Hills normally has at most one.

**Trap.** This bans reward *objects*, never talent or item *cards* — that lever
is the item catalog (`kind = "item"`, `mode = "ban"`). Each `ban` entry must
match something, deliberately: a typo fails the emit instead of silently doing
nothing. Use the `_Update5` def: the plain `Camp_Rewards_<Biome>` ones are never
loaded, and the SDK refuses them.

---

## `shop` — change the Sandman's stock and prices

**What the player sees.** Different items in the in-run vendor, at your prices.

```toml
[mod]
id           = "CheapSandman"
name         = "Cheap Sandman"
version      = "0.1.0"
author       = "you"
description  = "Everything is half off."

[[content]]
kind        = "shop"
id          = "sandman"
price_scale = 0.5            # every Sandman item, half price
```

**Prove it.** Find the Sandman in a run and open the shop.

**Trap.** There is one Sandman, so a mod declares at most one `shop`. The seven
generators (`minor`, `medium`, `major`, the `*_duplicate` and `*_object`
variants) each decide count, quality and flag pool separately — changing one
does not move the others. A slot's `count` can go *down* but never above what
it ships with: the shop screen has a fixed number of widgets per slot.

---

## `tilegen` — a chapter's map-generation recipe

**What the player sees.** More camps, more wells, a differently-shaped map.

```toml
[mod]
id           = "BusyHills"
name         = "Busy Dark Hills"
version      = "0.1.0"
author       = "you"
description  = "Fewer, hand-placed-feeling camps."

[[content]]
kind    = "tilegen"
id      = "camps"
chapter = "DarkHills"
[content.kinds.Camp]
count = 2                 # camps placed by the kind pass
[content.fill]
"40x40" = []              # leftover big slots stay empty instead of
"64x64" = []              # becoming camps
```

**Where tiles come from.** Generation runs in two passes, and tiles can pull
in more tiles:

1. **Kind pass.** Each kind places up to its `count`.
2. **Fill pass.** Every footprint group then fills each slot still empty with a
   tile carrying the group's flags. Dark Hills fills 40x40/64x64 with `Camp`,
   which is why an unedited map shows 8-9 camps against a Camp count of 5.
   `fill = { "<WxH>" = [] }` turns it off for that group.
3. **Tile constraints.** A placed tile can require others nearby. `Start` places
   one `Story` tile, and the Wood House story tile then places 3 Treant camps.
   The recipe doesn't control these.

Flag `quotas` are **caps** (at most N), so raising one never adds tiles.

**Prove it.** Start a run in that chapter and count what generated.
`R.poi.on_generated` + `R.poi.placed` hand you every placed tile by name, so the
count can come from the spawner itself instead of the minimap. Count camps by
source: Treant camps next to the Wood House come from its constraint, not the
recipe.

**Trap.** Edits are keyed by **name** and re-applied to the shipped recipe every
time, so a name the recipe no longer has fails the emit rather than landing on
whatever now sits at that index. The **Map** tab of `./rsmm editor` writes these
blocks for you from a 3D view of the chapter.

---

## `game_mode` — reorder the chapters of a run

**What the player sees.** A run that starts in Avalon.

```toml
[mod]
id           = "AvalonFirst"
name         = "Avalon First"
version      = "0.1.0"
author       = "you"
description  = "Chapter order: 2, 0, 1, 3."

[[content]]
kind     = "game_mode"
id       = "AvalonFirst"
base     = "All_Chapters"
chapters = [2, 0, 1, 3]
```

**Prove it.** Start a new run and read the chapter you land in.

**Trap.** This rewrites the game's one run order in place — there is no
second mode to pick from a menu, so the `id` is only a label, and two mods
that both set `chapters` (or a `map` mod with `chapter = N`) collide on the
same file. A FIXED order is data-safe; per-run randomisation is not (it needs
engine RNG and multiplayer determinism). Proven in game: skipping chapters
and running them out of order. Each chapter may appear once; a repeat is
refused, because the game skips it.

---

## `map` — make a chapter play a cloned map

**What the player sees.** A chapter that plays a mapdef of your own. Today it
looks like the base map: the clone reuses the base's terrain and still draws
its tiles from the base's pool.

```toml
[mod]
id           = "TwilightHills"
name         = "Twilight Hills"
version      = "0.1.0"
author       = "you"
description  = "Chapter 1 plays a Dark Hills clone."
experimental = true

[[content]]
kind    = "map"
id      = "Twilight_Hills"
base    = "Dark_Hills"   # Dark_Hills, Storm_Island, Avalon or Baba_Yaga
chapter = 0              # 0 Dark Hills, 1 Storm Island, 2 Avalon, 3 Baba Yaga
```

**Prove it.** `R.maps.chapters()` lists each chapter's map: the one you
repointed says `resref` and resolves to a mapdef that is not the vanilla one.

**Trap.** `chapter` overrides `All_Chapters` as a whole file, so it conflicts
with a `game_mode` edit in another mod (last writer wins). Tile generation
follows the base's tile-generation level back to the ORIGINAL mapdef, so pool
edits on the clone do nothing yet, and `tribe` has shown no visible effect.
To change what an existing chapter generates, `tilegen` and `poi` are the
proven tools.

---

## `skill` — relabel a talent

**What the player sees.** A talent with your name and description on the
level-up card and in the Skill Menu.

```toml
[mod]
id           = "DiveRename"
name         = "Dive, Renamed"
version      = "0.1.0"
author       = "you"
description  = "Attack Dive becomes Meteor."

[[content]]
kind        = "skill"
id          = "meteor"
hero        = "Aladdin"
source      = "Attack Dive"
name        = "Meteor"
description = "Come down harder."
```

**Prove it.** Open the hero's Skill Menu — the new text is there.

**Trap.** Relabel renames an EXISTING talent — a hero's talent count is fixed.
`mode = "clone"` (add a row) and `mode = "repoint"` (rename the herodef row) are
refused: the first crashed the game, and the second changes nothing visible,
because the name shown comes from the hero entity's controller key.

---

## `modifier` — a custom run mutator

**What the player sees.** A new toggle on the challenge screen — in theory.

```toml
[mod]
id           = "DoubleXp"
name         = "Double XP"
version      = "0.1.0"
author       = "you"
description  = "A relabelled MoreExperience."
experimental = true

[[content]]
kind        = "modifier"
id          = "DoubleXp"
base        = "MoreExperience"
name        = "Double XP"
description = "Twice the experience, twice the regret."
```

**Prove it.** Open the challenge screen and look for the row.

**Trap.** The def cooks and loads; a NET-NEW modifier *appearing in the UI* is
the unproven part — the slot count looks pre-sized to the vanilla set. A
modifier's effect is hardcoded C++ keyed by an entity-value id, so a clone
reuses an existing behaviour; new behaviour is layered in Lua via `R.modifier`.

---

## `melody` — retune one of the Piper's melodies

**What the player sees.** A lost melody that grants a different effect.

```toml
[mod]
id           = "HealierHeal"
name         = "Healier Heal"
version      = "0.1.0"
author       = "you"
description  = "Fully Heal reveals the map instead."
experimental = true

[[content]]
kind   = "melody"
id     = "fully_heal"
base   = "Fully_Heal"
effect = "Reveal_Map"        # must be another retail melody's stem
```

**Prove it.** Play the Piper, collect that melody, use it.

**Trap.** There are exactly twelve melodies and twelve icons, indexed by a dense
enum — so there is no thirteenth. This kind edits the twelve that exist and
refuses to pretend otherwise.

---

## `boss` — make a boss arena fight another boss

**What the player sees.** The Dark Hills ghoul den, with the Storm Island
giant crab waiting at the bottom.

```toml
[mod]
id           = "CrabDen"
name         = "Crab Den"
version      = "0.1.0"
author       = "you"
description  = "The ghoul den fights the giant crab."

[[content]]
kind    = "boss"
id      = "crab_den"
base    = "Boss_Marsh_Ghoul"
becomes = "Boss_Crab"
```

**Prove it.** Enter the arena `base` belongs to and see who is waiting. (Proven
with `base = "Boss_White_Lady"`: her shrine raised its arena around the crab and
paid its reward when the crab died.)
`base` must be one of the bosses whose arena picks them by flag alone:
`Boss_Crab`, `Boss_Marsh_Ghoul`, `Boss_Wolf`, `Boss_White_Lady`. `becomes` can
be any boss definition.

**Trap.** Quest bosses, the Jinn and the three-part witch fight are refused
as `base`: something besides the definition names their entity, so swapping
it would split the fight from whatever holds that reference. The swap is
global — every run fights the new boss there.

---

## `hero` — add a hero to the roster

**What the player sees.** A new portrait on the hero-select screen. With only
a `base` it is an exact copy of that hero; the fields under "A hero of its own"
give it its own name, body, textures, portrait and gameplay entity.

```toml
[mod]
id           = "MoreHeroes"
name         = "More Heroes"
version      = "0.1.0"
author       = "you"
description  = "A second Piper."

[[content]]
kind = "hero"
id   = "Zz_Piper_Clone"
base = "Piper"
```

**Prove it.** Open the hero-select screen: one more portrait than before. From
Lua, `#R.defs.instances("oCDtHeroDefinition")` goes from 12 to 13.

**Trap.** The roster is every hero the game has **loaded**, and heroes load only
through the LiveOps versiondef's hero list, which `apply` appends to. Dropping a
herodef file in without that loads nothing. The new hero takes the next index,
which no save has unlocked, so test with the `unlock-heroes` mod. Paid DLC
hero (Merlin) is a `base` only when the block says `dlc_owner = true`: the
clone plays for anyone who installs the mod, so share it only with players
who own the DLC.

### A hero of its own

Everything past `base` turns the copy into a hero of its own. The fields below
are **not yet proven in game**. Only the plain copy above is.

```toml
[[content]]
kind        = "hero"
id          = "Nyx"                       # letters and digits: it names Hero_Nyx
base        = "Piper"                     # whose moves she has
name        = "Nyx"
description = "Piper's moves, her own look."
model       = "art/nyx.glb"               # body, rigged to Piper's skeleton
albedo      = "art/nyx_albedo.png"        # also: mra, normal
portrait    = "art/nyx_portrait.png"      # select screen + in-run

# A weapon of her own. The key is the base's graphic object; `rsmm
# export-character Piper` lists it as an attachment.
[content.weapons."Weapon In Left Hand Mesh"]
model  = "art/nyx_flute.glb"
albedo = "art/nyx_flute.png"

# Her own moves: a clip of Nyx's alone, the base keeps its own.
[content.animations.Piper_Dash_Default]
source = "art/nyx_moves.glb"
clip   = "Piper_Dash_Default"             # the action's name in the .glb

# Outfits fill the skin slots after Default, in order.
[[content.outfits]]
name   = "Frost"
albedo = "art/nyx_frost.png"

[[content.outfits]]
name   = "Mercenary"
model  = "art/nyx_mercenary.glb"      # a body of its own
albedo = "art/nyx_mercenary.png"

# Her numbers. `rsmm export-character Piper --list-values` lists them.
[content.values]
"Ultimate Power 2 Cooldown Max" = 30
"Trait Ability Pets Per Spawn Default Amount" = 3
"Hero_Piper_Projectile/Lifetime Duration" = 0.8   # one entity only

# What her abilities use: a VFX, a sound, a mesh, anything her entities name.
[content.references]
"Settings\\Heroes\\Hero_Piper_FX\\Piper_Note_Day_01.vfx.ot" = "Settings\\Heroes\\Hero_Juliet_FX\\Juliet_Basic_Bullet_Trail_01.vfx.ot"

# How her abilities are wired: copy, set and rewire parts, by the names
# `rsmm entity-graph Piper` shows. Applied in order.
[[content.abilities]]
clone = "Ability Secondary"          # a group, or a list of parts
as    = "Echo"                       # new group; each part gets " Echo"

[[content.abilities]]
set   = "Primary Ability Shots Delay.value"
value = 0.2                          # on a linked number, replaces the link

[[content.abilities]]
entity = "Ice_Clone"                 # another file of the family
set    = "Explosion Attack Traverser.obj_2[3]"
value  = 4.0                         # the n-th number inside a part's settings

[[content.abilities]]
link  = "Primary Ability Shoot Timer.on_end"
to    = "State Secondary Ability Echo"
```

- **`name` / `description`** are added to the base's text bank as
  `Hero_<id>_Name` / `Hero_<id>_Desc` in every language (English text for all
  of them), and the new herodef points at them.
- **`model`** is the body. Start from `rsmm export-character Piper`, edit the
  mesh in Blender on Piper's skeleton, and export. Bones are matched by name,
  and a weapon left in the file is ignored (it is a separate object in game).
  Every skin slot shows this body.
- **`albedo` / `mra` / `normal`** replace the maps of the body material. A map
  you leave out keeps the base's.
- **`portrait`** replaces the select-screen and in-run portraits. It is the
  riskiest field: a UI texture under a new name once hung level load (a POI
  minimap icon), so try it separately.
- **`weapons`** gives a weapon its own mesh (`model`, a static mesh) and/or
  maps (`albedo`, `mra`, `normal`). Only this hero carries it; the base keeps
  its own. The mesh is used exactly as authored, in the weapon's own space:
  export it ON ITS OWN with its object transform cleared, not while it is
  parented to the hand bone of an `export-character` file (the cooker bakes
  object transforms, so a weapon exported in the hand ends up offset).
- **`animations`** cooks each clip under a new name (`Nyx_Piper_Dash_Default`)
  and points only this hero's entities at it. The `animation` kind replaces a
  clip for everyone who plays it; this does not. Keys are the base's clip
  names, as `rsmm export-character` prints them. A `.glb` path alone means the
  action carries the clip's own name.
- **`outfits`** are more skins, each with its own `name` on the skin page.
  An outfit is the Default look wearing its own body maps, and with `model` it
  gets a body of its own too, rigged like `model` (to the base's skeleton).
  Outfits take the skin slots after Default in order, and the slots after them
  show Default. They may show as locked: the base's skin unlocks do not carry
  over to a new hero.
- **`values`** sets the hero's numbers: cooldowns, durations, radii, damage
  multipliers, pet counts, projectile lifetimes.
  `rsmm export-character <Base> --list-values` lists what can be set and in
  which entity. A bare label sets it everywhere; `<Entity>/<Label>` sets it in
  one entity only. A misspelt label fails the build.
- **`references`** swaps anything the hero's own entities name: another VFX, a
  sound event, a mesh, a clip. Each new resource's preloads are borrowed from a
  shipped cache that already loads it. A resource no shipped cache lists is
  refused, because an unlisted preload crashes the game at load.
- **`skills`** gives the hero talent and ability cards of her own:
  `[content.skills."Dash Trap"]` (a talent, as its `Skill Controller` names
  it) or `[content.skills."Ability Power"]` (an ability slot), each with
  `name` and/or `description`. The base hero keeps his cards. The number of
  talents is fixed, so this relabels a slot; change what the talent does with
  `abilities` (its parts are the `Skill <talent>` group). Keep the card's
  `{N}` placeholders and `#…@` keywords: the numbers come from the card's own
  String Format.
- **`placeholder`** (a PNG, a flat pink by convention) paints every piece of
  art the hero still borrows from its base: each character material (body,
  gear, companion, every skin), every ability and talent icon, the HUD
  images, and the book's portraits, skin icons and codex pictures. Whatever
  is still pink in game is what is left to make. `albedo`, `weapons` and
  `portrait` win over it. Story pages the hero does not write itself read as
  pages still to write.
- **`effects`** gives the hero particle effects of its own. Every effect in
  the base's own FX folder (Beowulf has 99) is copied under the hero's name
  with its own materials and textures, recoloured to a tint at each colour's
  own brightness, so shapes and transparency stay. The recolour reaches the
  colour textures (never masks or surface data), the materials' colours and
  the effect's own colour ramps, which are what make fire orange:
  `[content.effects."*"]` `tint = "#7ad0ff"` for all of them, or
  `[content.effects.Beowulf_Shockwave_Front_01]` for one. With `placeholder`,
  effects given no tint turn pink. Effects shared with every hero
  (`Common_FX`) are never touched.
- **`hide`** lists meshes the hero does not have, by name (`"Wyrm_GEO"`,
  Beowulf's dragon) or full path. Each is swapped, in this hero's entities
  only, for an invisible copy: the same mesh on the same skeleton, shrunk to
  about a thousandth. Everything attached to its bones keeps working, so the
  dragon's fire still comes, just from nowhere visible. Its sounds stay.
- **`memoirs`** is the book's story pages, in order: `[[content.memoirs]]`
  tables with `title` and `text` (Beowulf has 7). A page left out keeps the
  base hero's story, or shows a placeholder when `placeholder` is set. The
  narration audio stays the base's.
- **`abilities`** edits how her abilities are wired. An ability is a graph of
  parts (states, timers, tests, spawners, values) inside the hero's entity;
  `rsmm entity-graph Piper --group "Ability Secondary"` lists one ability's
  parts and links, and `--show "<part>"` shows a part's fields by name. Each
  step is one of:
  - `clone = "<group>"` + `as = "<new group>"` (or `clone = ["part", ...]`):
    copy the parts under new names (`suffix`, default `" " + as`). Links among
    the copies point at the copies; everything they own is copied too.
    `from = "Juliet"` copies from another hero.
  - `set = "Part.field"` + `value`: a number, a bool, or `[x, y, z]`.
    `"Part.field[n]"` sets the n-th number (or `[x, y, z]`) inside an object
    field, as `--show` prints them; with a text `value` it replaces the n-th
    string instead, e.g. `set = "My Spawner.template[1]"` with
    `value = "Heroes\\Hero_Beowulf\\Hero_Beowulf_Shockwave.entity.ot"` makes
    a spawner spawn something else.
  - `link = "Part.field"` + `to = "Other Part"` (`""` for nothing); a list
    element is `"Part.list[0]"`, and `"Part.obj[n]"` is the n-th reference
    inside an object field (`--tokens` lists them, empty ones included).

    **Turning a spawn.** A spawner's own yaw fields (`position[8]`,
    `transform[5]`) are ignored for a hero's ability spawn: four shockwaves
    turned that way all went the way the hero faced. The game turns a spawn
    the way Piper fans her notes: the spawner reads a 3D node, whose Y angle
    (radians) comes from a value. Copy a spawner together with its node
    (`clone = ["Attack Shoot Projectile Spawner 02", "Attack Shoot 3d Node 02"]`)
    and point the node's angle at a value of your own
    (`link = "Attack Shoot 3d Node 02 Copy.obj_4[5]"`).
  - `add_link = "Part.list"` + `to`, and `remove_link = "Part.list[i]"`.
  Add `entity = "FX"` to a step to edit another entity of the family.
  The **Abilities** tab of `rsmm editor` builds these steps for you.
  It opens on **Numbers**: every number the chosen ability uses, by name
  (type a value, press Enter; ↺ resets it). The **Diagram** tab draws the
  ability as a graph of parts for re-pointing links and copying groups. Every
  change is re-checked straight away; press *Copy manifest code* and paste it
  into the manifest.
  Every edit is checked before anything is written, and the build fails
  rather than install an ability that cannot work: a link into an entity the
  hero does not carry (copying Juliet's secondary drags links into
  `Hero_Romeo_Juliet_Common`, which a hero built on Piper does not have), a
  part left owning nothing, a number re-pointed at a value of another type.
  The check proves the wiring is sound, not that the ability plays the way
  you meant: that is still a playtest.
- **`[[content.attacks]]`**: an attack of the hero's own that replaces an
  ability slot, declared instead of wired step by step:

  ```toml
  [[content.attacks]]
  id        = "Crescent"             # its entity is Hero_<hero>_Crescent
  slot      = "special"
  model     = "art/crescent.glb"     # static mesh, glTF +Y = direction of flight
  albedo    = "art/crescent_alb.png" # mra / normal optional
  speed     = 16
  lifetime  = 0.9                    # seconds
  beats     = [[0, 180], [90, -90]]  # each beat's angles, 0 = where the hero faces
  delay     = 0.4                    # seconds between beats
  animation = "art/cast.glb"         # replaces the slot's clip (`clip` = its name)
  ```

  The projectile is a new entity of the hero's own on the engine's generic
  hero projectile (physics, hits, piercing, damage and despawn come from
  it), with the mod's mesh and maps, the hero's own trail and impact effects
  (tinted by `effects`) and the base's projectile sounds. Each angle fires
  from a copy of the base's projectile spawner and 3D node, turned by the
  node's angle (see *Turning a spawn* above). Beat 0 fires when the slot is
  used and each later beat on a timer inside the slot's state, so the
  slot's animation must last until the last beat. Damage is the generic
  projectile's for now. Supported bases so far: Piper (`slot = "special"`).
- **`own_entity = true`** is implied by every field above except `name`,
  `description` and `portrait`. The hero gets
  its own gameplay entity: every `Hero_<Base>*` entity (the hero, FX, pets,
  projectiles, skins) is cloned as `Hero_<id>*` with its paths and scopes
  renamed, and a new alias in `ApplicationSettings.ot` binds the skins to it.
  The whole family has to move together, because a pet or a projectile reads
  its owner's values by the owner's template name. With its own entity, the
  hero's abilities and values are its own to change later.

**Prove it.** A portrait named after your hero, your body and texture when you
pick it, and the base's abilities (Piper's rats and notes) working in a run.
How the pieces connect is written up in `docs/_re/kinds/heroes.md` under "How a
hero is assembled from data".

---

## Where to go next

- [Content kinds & confidence](/reference/sdk-api/kinds/) — the generated rating
  table, and the only place a rating is written down for readers.
- [Authoring mods](/guides/modding/) — the full manifest surface, patches,
  merges, load order.
- [Conventions & best practices](/reference/conventions/) — naming, pre-flight
  checklist, surviving game updates.
- [Example mods](/guides/examples/) — complete mods that ship in the repo.

---

# Hero unlock gates

> The five lock types on a hero definition, which ones a mod may open, and how to get the decompile that shows you.

Source: https://docs.rsmm.me/guides/merlin-unlock/

Every locked hero on the picker screen is locked by one of five different
mechanisms. They are **not** interchangeable, and the distinction decides
whether a mod may touch them at all.

:::caution[This page used to say something else]
An earlier version of this guide described a `MerlinUnlock` mod that hooked
`IsUnlocked` unconditionally and short-circuited it to `true` for a chosen
herodef. That recipe is retracted. It did not distinguish a progression gate
from the ownership gate, so what it actually documented was a DLC bypass. The
script and mod it referenced (`scripts/mine_merlin_unlock.py`,
`mods/MerlinUnlock/`) never existed in this repo.
:::

## The five gates

A hero definition carries children derived from
`oIGameUnlockConditionSettings`. `IsUnlocked` is **vftable slot 14** on every
`oIGameUnlockConditionData` subclass — the base leaves 10/11/14 as stubs and
each subclass overrides them. `oCDtHeroPickerEntityCpnt` calls it when the
player hovers a portrait.

| Settings class | Symbol | Reads | Mod may open? |
|---|---|---|---|
| `HeroProgressionUnlockConditionSettings` | `HeroProgressionUnlock_IsUnlocked` | `required(settings+0xb0) <= reached(data+0x40)` | yes |
| `HeroRankGameLockConditionSettings` | `HeroRankLock_IsUnlocked` | profile rank vs. required rank | yes |
| `HeroStoryUnlockConditionSettings` | `HeroStoryUnlock_IsUnlocked` | story counter vs. threshold | yes |
| `ChallengeUnlockConditionSettings` | `ChallengeUnlock_IsUnlocked` | referenced challenge complete | yes |
| `AdditionalContentGameUnlockConditionSettings` | *(deliberately unnamed)* | Steam DLC entitlement | **no** |

The first four are grind gates. They read counters the player earns and that
live in `_Save/Profile_*.ob`. Opening them locally changes only which portraits
your own client offers.

The fifth is not a gate on progress, it is a gate on purchase. It resolves
through the content manager's vftable slot 1:

```text
oIAdditionalContentManager::vftable     @ 0x140f3e288   slot[1] = stub, always reject
oCNullAdditionalContentManager::vftable @ 0x140f3e1e0   same stub
oCLocalAdditionalContentManager::vftable@ 0x140f3e578   FUN_140647440 — GetFileAttributesW
oCSteamAdditionalContentManager::vftable@ 0x140f8db00   FUN_140a2c600 — ISteamApps::BIsDLCEnabled
```

On a Steam build `FUN_140a2c600` reads the u32 pack key at `node+0x3c` and asks
`ISteamApps::BIsDLCEnabled` whether the account owns it. That symbol is left
unnamed in `data/symbols.json` on purpose, so nothing in the SDK can resolve it
by semantic name.

Heroes sold as content packs — Merlin (Merlin HeroPack), the Romeo & Juliet
HeroPack roster — sit behind that fifth gate. Buy the pack and every mod here
works on them normally; there is no supported path around it.

## Opening the progression gates

`R.hero.unlock_progression()` hooks the four grind gates by symbol name and
returns how many armed. It resolves each through `I.resolve`, so a symbol that
is unverified for the current build fails closed rather than hooking a stale
address. Ownership is untouched.

```lua
local R = require "rsmm"
R.on("ready", function() R.hero.unlock_progression() end)
```

Shipped as `mods/hero-unlock/`. Runtime-only — the profile save is never
written, so disabling the mod restores the stock picker with no cleanup.

## Getting the decompile these addresses come from

```bash
python3 scripts/ghidra_export.py \
    --ghidra  /path/to/ghidra_11.3_PUBLIC \
    --exe     "$GAME/Ravenswatch.exe" \
    --project ghidra_project \
    --out     data/decompiled.jsonl
```

* First pass imports the PE and runs full auto-analysis; later passes reuse
  `ghidra_project/Ravenswatch.gpr`, so only the export repeats.
* Output is JSON-Lines, one function per line:
  `{"addr":"0x140abc...","name":"...","sig":"...","size":N,"code":"<C source>"}`.
* Wall time on the 22 MB PE: **30–90 min** (`_JAVA_OPTIONS=-Xmx8G` is set by
  the driver).

To find the gate implementations yourself:

```bash
jq -r 'select(.name | test("Unlock")) | "\(.addr)  \(.name)"' data/decompiled.jsonl
```

Or skip Ghidra entirely — `python scripts/disasm.py --resolve HeroRankLock_IsUnlocked`
disassembles the live exe with symbol annotation.

## Why not patch the cooked herodef instead?

* The `.gen` payload sections are aligned and length-prefixed; rewriting them
  risks invalidating offsets recorded by `UsedRscList.ot` and `asset_map`.
* A binary swap persists, but reverting needs the original file. The Lua hook
  is runtime-only.

Merlin's encoded herodef, for reference:

```text
DarkTalesResources/_Cooking/Nqhdzdidrzv/Aqurqv/Hquldz.nqurtqh.ri.NiAqurNqhdzdidrz.yqz
            ^---------------- "Definitions/Heroes/Merlin.herodef.ot.DtHeroDefinition.gen"
```

The encoding is the substitution cipher in `src/rsmm/engine/cipher.py`;
`./rsmm decode <file>` dumps the cooked section table.

## Save-file format

`_Save/Profile_1.ob` is the canonical store for unlock state — `strings` shows
`HeroRankGameLockConditionData`, `HeroProgressionUnlockConditionData`,
`HeroStoryUnlockConditionData`, `AdditionalContentGameUnlockConditionData`.

Do **not** edit it. Steam Cloud will fight you and `oCSaveSerializer`
checksums the file. Runtime hooks are the durable answer. If you want to
experiment, copy the profile to `/tmp` first.

---

# Mod Authoring Guide

> Scaffold, build, test, and ship a mod — the single authoring guide.

Source: https://docs.rsmm.me/guides/modding/

This is the **single** authoring guide — scaffolding a mod through shipping a
finished `.zip`. For CLI command details, see the [CLI Reference](/reference/cli/);
for the SDK design rationale, [SDK_V3.md](/guides/sdk/).

:::tip[New to modding?]
This page is the complete reference, and it gets technical fast. If you haven't
made a mod before, start with [Make your first mod](/getting-started/first-mod/),
which walks you through one from start to finish, then come back here when you
want to know what else a mod can do.
:::

```mermaid
flowchart LR
    N["rsmm new"] --> E["edit manifest.toml<br/>+ drop assets"]
    E --> A["rsmm apply"]
    SDK["Python SDK<br/>(with sdk.Mod)"] -.->|"emits"| E
    A --> T["rsmm run<br/>test in game"]
    T -->|"iterate"| E
    T --> P["rsmm pack → dist/&lt;id&gt;.zip"]
    P --> U["upload via Registry"]
```

> **Write the manifest.** Every mod ships the same thing: a declarative
> `manifest.toml` (`[[content]]` / `[[patch]]`) plus assets, and writing that
> file by hand is the normal way to make a mod. `rsmm new` scaffolds it, the
> editor schema autocompletes it, and `rsmm lint` checks it. The Python SDK
> (`with sdk.Mod(...)`) is an optional *generator* for the same file, useful
> when a mod has many similar entries to produce. Your `build.py` is a tool you
> run; it is **not** shipped inside the mod. See
> [Authoring with the Python SDK](#authoring-with-the-python-sdk) below.

> **A mod is data, not code.** The shipped artifact is `manifest.toml` + assets
> — never an arbitrary python script dropped in the mod folder. Reversing a byte
> layout with a throwaway script is fine for *discovery*, but fold the capability
> into `rsmm.sdk` and express the mod declaratively before shipping. `rsmm lint`
> (and CI) rejects any `*.py` in a mod except the sanctioned `on_disable.py`
> lifecycle hook. (The SDK `build.py` lives in the mod source but is a generator,
> not loaded at runtime; `init.lua` is the one sanctioned in-mod runtime script.)

---

## Quick start

```sh
# Scaffold a mod
./rsmm new MyMod

# Verify it's healthy
./rsmm doctor

# Install into the game
./rsmm apply

# Launch the game
./rsmm run

# Iterate with auto-reapply
./rsmm watch              # runs in background; reapplies on every change

# Roll back when done
./rsmm restore --all

# Package for sharing
./rsmm pack MyMod         # writes dist/MyMod.zip
```

---

## Content lives in folders, not in the manifest

`manifest.toml` describes the **mod** — id, author, licence, multiplayer scope.
It should not grow a table for every item, enemy or structure in it. Content
goes in the file tree instead, one directory per thing:

```
mods/my-mod/
    manifest.toml               what the mod is
    items/ember_charm/
        item.toml               what the item is
    enemies/frost_wolf/
        enemy.toml
    pois/runestone_shrine/
        poi.toml
        model.glb               your own mesh
        albedo.png              your own maps, matched to
        mra.png                 texture slots by filename
        normal.png
```

Each folder is one content def. Its id defaults to the folder name, and the
`<kind>.toml` inside holds the same fields a `[[content]]` block would. `rsmm
new <id> --kind <kind>` scaffolds this layout.

Directory names are plural, kinds singular: `items/` → `item`, `enemies/` →
`enemy`, `bosses/`, `heroes/`, `talents/`, `skills/`, `modifiers/`, `rewards/`,
`melodies/`, `maps/`, `pois/`. `game_mode` is deliberately not on the list — a
mod has at most one, so it stays in the manifest.

You can still write `[[content]]` by hand, and a declared block **wins** over a
folder with the same id, so dropping to the explicit form for one def does not
mean moving the rest.

### POIs get presets and art-by-filename

`poi` goes furthest with the convention, because a structure otherwise needs
five engine paths. A `poi.toml` usually only has to say which chapters it
appears in:

```toml
#:schema https://docs.rsmm.me/poi.schema.json
chapters = ["Dark_Hills", "Avalon", "Storm_Island"]
```

The `#:schema` line gives Taplo / Even Better TOML completion and flags a
misspelled key before `apply` does.

Everything else — which tile it stands in, which object it takes the place of,
which prop and material it inherits structure from, its kind and spawn weight —
comes from a preset. Drop `model.glb` plus `albedo.png` / `mra.png` /
`normal.png` beside it and those become the structure's own art; omit them and
you get a clone of a shipped structure. See `rsmm poi` to browse, and
`mods/runestone-shrine` for a worked example.


## Two override strategies

Independent of *how* you produce the manifest (hand-written TOML or the
[Python SDK](#authoring-with-the-python-sdk)), a mod changes the game in one of
two ways:

### 1. Drop cooked files (raw)

Mirror decoded paths under `assets/`. Full control, byte-for-byte. One mod owns each file.

### 2. Compose `[[patch]]` blocks (recommended)

Write declarative blocks in `manifest.toml` for numeric values (`stat`), texture
swaps (`texture`), and plaintext `.ot` fields (`ot`). The applier composes every mod's patches into a single
cooked file per target. Two mods touching *different* fields of the same file
both take effect; conflicts on the *same* field resolve by `load_order` (lower =
applies first; later wins on overlap).

```toml
[[patch]]
kind  = "stat"
name  = "Bleed_Duration_Value"
value = 10

[[patch]]
kind = "stat"
name = "Easy"
min  = 5
max  = 10

[[patch]]
kind     = "ot"
selector = "Merlin DMG Zone"
field    = "m_eComputerType"
value    = 0
```

The same blocks from the optional Python SDK — `python3 mods/MyMod/build.py`
writes the manifest above:

```python
# mods/MyMod/build.py
from rsmm import sdk

with sdk.Mod("MyMod", author="me", load_order=50) as m:
    m.stat("Bleed_Duration_Value", value=10)
    m.stat("Easy", min=5, max=10)
    m.ot("Merlin DMG Zone", "m_eComputerType", 0)
```

#### Editing a plaintext `.ot` (`kind = "ot"`)

A few `oCTextSaver` files ship **uncooked** beside the executable —
`DarkTalesResources/ApplicationSettings.ot` is the one worth touching. It holds
the friendly-fire factors, the forced-seed option, and the entity-value modifier
descriptors (see below). It is plain text: no cipher, no cooking.

A mod *could* ship a whole edited copy under `assets/_root/`, and before this
patch kind that was the only way. Don't: that redistributes a game file, and it
reverts every unrelated change the next game patch makes to it. Declare the
field instead — `apply` reads the install's own bytes, rewrites just that field,
and installs the result through the same `_root/` channel:

```toml
[[patch]]
kind     = "ot"
selector = "Merlin DMG Zone"     # matches s|m_sLabel in a block
field    = "m_eComputerType"     # must already exist in that block
value    = 0
# file           = "DarkTalesResources/ApplicationSettings.ot"   (the default)
# selector_field = "m_sLabel"                                    (the default)
```

Rules, all enforced at merge time with an error rather than a silent no-op:

* the selector must match **exactly one** block;
* the field must **already exist** in that block — a patch edits a value, it
  never invents a field the engine would ignore;
* a nested block's fields are not its parent's (`m_oDefaultValue`'s `u16Type` is
  reached by selecting the nested block, not the descriptor around it);
* the value's type comes from the **file's** prefix (`i|` int, `u|` unsigned,
  `f|` float, `b|` bool, `s|` string) — writing a string into `i|` is refused;
* if any edit in a file fails, the whole file is refused. Half-applied edits are
  a configuration nobody wrote.

The base is the install's **pristine** copy (`<file>.rsmm.bak` when an earlier
apply made one), so re-running `apply` is idempotent and two texture-style
chains cannot compound.

##### Entity values: `m_eComputerType`

Each `oSModifierValueDesc` block in `ApplicationSettings.ot` describes one
entity value — a label, a default, `m_uMaxStackSize`, `m_eStackMode`, and
`m_eComputerType`. The last one picks which `oCEntityValueModifier*Computer`
folds **concurrent modifiers of that value** together. It is not a damage type.

The engine ships seven; three independent orderings in the binary agree on
`Add(0) Sub(1) Mult(2) Reduce(3) Oldest(4) Max(5) Min(6)`, and `ct=0` = Add
(contributions sum) anchors it. The shipped file uses `0` forty times, `3` six
times, `6` once — and every `3` is a persistent zone or trail: `Merlin DMG Zone`,
`Dullahan_Trail_DOT`, `Mordred_Trail_DOT`, `Fire_Trap_DOT`, `Poison_Trap_DOT`,
`Piper Pets Within Special`. Players report these do not stack when they overlap,
which is what a non-additive combiner would do.

:::caution[Inferred, not proven]
The enum's *names* cannot be recovered from the binary: the strings `Reduce`,
`Oldest`, `Multiply` and `Substract` have zero code xrefs (the same pointer-table
interning that defeats event-name scans). The mapping above is inference from
declaration order. Setting one of the six to `0` and checking whether two
overlapping instances start stacking is the experiment that settles it.
:::

---

## Mod layout

```
mods/MyMod/
    manifest.toml              # Required: id, name, version, author
    assets/                    # Mirrors decoded paths from data/asset_map.csv
        <decoded-path>/<file>
        _root/                 # Optional: files outside _Cooking/, at the
            DarkTalesResources/#   install root. Prefer a `kind = "ot"` patch
                ApplicationSettings.ot   # for plaintext .ot files (below).
    init.lua                   # Optional: Lua script run by the loader DLL
    build.py                   # Optional: Python SDK build script
    on_disable.py              # Optional: cleanup hook when mod is disabled
```

### manifest.toml

```toml
#:schema https://docs.rsmm.me/manifest.schema.json

[mod]
id          = "MyMod"
name        = "My Mod"
version     = "1.0.0"
author      = "you"
description = "what it does"
enabled     = true
```

**Every key must be one something reads.** A misspelled key used to install a
mod that did nothing, so now:

- `rsmm lint` fails on an unknown key in `[[content]]` or `[[patch]]` and names
  the closest valid one (`unknown key 'valeu' (did you mean 'value'?)`). An
  unknown `[mod]` key is a warning.
- It also fails a patch that would change nothing: a stat name that does not
  exist, a field that value does not have (`Easy` has `min`/`max`, not
  `value`), a non-number, or a texture path the game does not ship.
- `rsmm apply` and the Python SDK refuse an unknown content field outright.

The `#:schema` line (which `rsmm new` writes for you) lets
[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
or any Taplo-based editor autocomplete keys and underline the same mistakes as
you type. The schema is generated from the same list lint uses, so the two
never disagree.

### on_disable.py (optional)

Place next to `manifest.toml`. Fires from `./rsmm apply` when the mod flips `enabled = true → false`. Subprocess with 30s timeout; receives `RSMM_GAME_DIR`, `RSMM_COOKING`, `RSMM_MOD_DIR` env vars.

The hook runs as the player, outside the game, with no sandbox, so it never runs unasked: `rsmm apply` lists the pending hooks and waits for a yes (or `--yes`), and uninstalling from the desktop app asks whether to run it before removing the mod.

Use for cleanup the loader DLL can't do at apply time — clearing settings keys, deleting profile caches, etc.

See `mods/ExampleSeedPin/on_disable.py` for a canonical example.

### ConsoleRuntime / dev_mode

The bundled `mods/ConsoleRuntime/` mod ships with a `dev_mode` flag in its `manifest.toml`. Off by default. When `dev_mode = true`, ConsoleRuntime registers `/eval`, which executes arbitrary Lua inside the game process.

Toggle: edit `mods/ConsoleRuntime/manifest.toml`, set `dev_mode = true`, then `./rsmm apply` (or relaunch the game). Never ship a release with it on.

---

## Authoring with the Python SDK

**Optional.** The manifest is the main way to write a mod; the Python SDK
*generates* one. Reach for it when a mod has many similar entries — fifty stat
tweaks, a table of item variants — that are easier to produce in a loop than to
type out. You describe the mod in Python and `rsmm.sdk` writes the
`mods/<id>/` tree atomically. It applies the same checks as `rsmm lint`: an
unknown field is refused, with the nearest valid name.

Every content kind is reachable with one call, `m.content(kind, id=..., **fields)`,
whose fields are exactly the manifest's. Five kinds also have a named shortcut
(`m.item`, `m.enemy`, `m.boss`, `m.map`, `m.hero`); the rest use `m.content`.
Design rationale: [SDK_V3.md](/guides/sdk/).

### First mod

A mod is a `with sdk.Mod(...) as m:` block — calls accumulate in memory and the
tree is written when the block exits.

```python
# mods/FrostPack/build.py
from rsmm import sdk

with sdk.Mod("FrostPack", version="1.0.0", author="you", name="Frost Pack") as m:
    m.i18n("EN", {"FrostPack_hello": "A chill wind blows."})
```

```bash
python mods/FrostPack/build.py   # writes mods/FrostPack/manifest.toml + assets
rsmm list                        # see it registered
rsmm apply                       # install into the game
```

### Typed content + handles

`m.content(kind, id=..., **fields)` registers any kind; `m.item / m.enemy /
m.boss / m.map / m.hero` are shortcuts for five of them. Each returns a
`ContentRef` (like Forge's `RegistryObject`). Pass a handle anywhere another
content id is expected — it resolves to the raw id automatically. Find valid
bases with `rsmm schema [kind] [--grep T]`.

```python
with sdk.Mod("FrostPack", version="1.0.0", author="you",
             experimental=True) as m:           # required for non-confirmed kinds
    blade = m.item("FrostBlade", base="Orb_Grants_Strength", name="Frost Blade")
    m.enemy("FrostGhoul", base="Sling_Ghoul", add_flags=["Elite"])
    m.boss("CrabDen", base="Boss_Marsh_Ghoul", becomes="Boss_Crab")
    # every other kind: the same fields as its [[content]] block
    m.content("reward", id="MoreChests", base="Camp_Rewards_Dark_Hills_Update5",
              counts={"2": [3, 3]})
```

> Kinds below `confirmed` need `experimental=True`. Which ones those are is
> generated from the code: [Content kinds & confidence](/reference/sdk-api/kinds/).

### Tags, assets, config

```python
m.tag("daggers", [blade, "VanillaKnife"])     # append-across-mods set; R.tags() in Lua
m.texture("3D/.../T_Melusine_ALB.png", "art/albedo.png")    # PNG/DDS/TGA, auto-cooked
m.skinpack("Crimson Pack", key=0x900001)                    # new selectable slot (experimental)
m.config({"fields": {"frost_damage": {"type": "float", "default": 1.5}}})
m.i18n("FR", {"FrostBlade_desc": "Gèle à l'impact."})
print(m.summary())                            # dict of everything staged, no disk write
```

#### Config with icons (`multiselect`)

A config field is normally `bool`/`int`/`float`/`string`/`enum`. A
`multiselect` holds a **list** of ids and, when it names an allowlisted option
provider, the desktop draws it as a searchable list of the game's own art:

```toml
# mods/<id>/config_schema.toml
[fields.banned]
type   = "multiselect"
source = "item-catalog"   # allowlisted provider; NOT a path or a command
label  = "Banned items"
default = []
```

The CLI resolves `source` into options — `{id, label, group, icon,
description}` — and sends them with the schema, so the panel renders labels,
grouping, search and art in one round trip. Read the value back with the normal
config API (`ConfigStore(mod_dir).get("banned")`); the `banned-items` mod's
`[[content]]` ban block takes its item list from exactly that.

#### A saved config reaches the game on the next launch, never sooner

Nothing about config is hot-reloaded. The loader hands a mod its values once,
when it loads the mod, and a config that feeds `[[content]]` (an item ban, say)
only becomes real when `rsmm apply` rewrites the cooked asset that carries it —
which the desktop runs as part of Play. So an edit made while Ravenswatch is
running changes nothing in that session: quit the game completely, then launch
again. The desktop config panel says so after every save, and marks the
asset-rebuilding case (any provider-backed field) explicitly, because that
launch does real work before the game starts.

Providers are an **allowlist**: a mod supplies a name, never a path, a URL or a
command. The desktop webview can spawn the CLI, so anything a mod could inject
there would run on the player's machine — the same reason overlay shape is data
and never markup. The providers today are `item-catalog` (every magical object
the game can offer), `enemy-roster` (every creature a camp can roll) and
`shop-items` (every item the Sandman's offers can hold, with its price).

:::caution[An option icon must be an inline data URL]
`data:image/png;base64,…` only, under 64 KB. A path or a remote URL is dropped
rather than passed through, so a mod can never make the client fetch on its
behalf. The CLI decodes the game's own cooked textures to PNG
(`rsmm.engine.icon_decode`, pure stdlib — the shipped CLI has no runtime
dependencies) and caches them under `<game>/rsmm/cache/items/`.
:::

A provider-backed field does **not** reject ids it cannot currently see. The
valid set lives in the game install, which may be missing or newly patched, and
dropping an unrecognised id would silently delete the player's selection the
first time the CLI ran somewhere the catalog could not be read.

#### Editors for lists of game items (`item-grid`)

An `item-grid` sorts a provider's options into **sections you declare**, with an
optional number per item. The whole editor — sections, labels, which items fit
where, counts, and even its look — is your mod's declaration. The desktop draws
every `item-grid` with one generic component; it does not know what yours is for.

```toml
# mods/<id>/config_schema.toml
[fields.loadout]
type   = "item-grid"
label  = "Loadout"
source = "shop-items"                       # allowlisted provider, as above
title  = "Pick what is on offer"            # optional, your own copy
layout = "columns"                          # section groups side by side; default "stack"
quote  = "Every dream has its price."       # optional
number = { attr = "price", label = "Price", min = 0, max = 99999, editable = "priceEditable" }

[[fields.loadout.sections]]
id      = "minor"                           # letters, digits, _ or -
label   = "Offers"
group   = "Minor dreams"                    # consecutive sections sharing a group share a heading
accepts = { role = "offer" }                # option attributes that must ALL match
count   = { label = "Offers per visit", min = 1, max = 4, default = 4 }

[fields.loadout.theme]                      # optional: dress it in the game's own art
panel    = "Ui/SandMan/UI_SandManBg.png"
portrait = "Ui/NPC/NPC_Sandman_Portrait.png"
header   = { texture = "Ui/SandMan/UI_SandMan_categoriesBG.png", ink = "dark" }
```

- **Options** come from `source` and may carry `attrs`. `accepts` filters on
  them; a provider marks where an option sits by default with `attrs.defaultIn`
  (a list of section ids); `number.attr` names the attribute holding the
  default number, and `number.editable` the boolean that says it may change.
- **`empty`** on a section is your text for when it holds no items — a section
  the provider starts empty (like a shop's random-object slot) explains itself
  instead of looking broken.
- **The stored value** keeps only what differs from those defaults:
  `{ sections = { minor = { items = [...], count = 2 } }, numbers = { <id> = 10 } }`.
  An untouched editor stores nothing, so "Reset to defaults" really is the
  unmodded state. A content kind reads it — `kind = "shop"` takes
  `config = "<field>"`, see [Edit the Sandman shop](#edit-the-sandman-shop-kindshop).
- **Layout**: `stack` puts section groups one under another; `columns` puts
  them side by side, each in its own `panel` frame with an optional
  `separator` between, and moves the portrait and quote beside them on a wide
  screen. A vendor-style grid with a few groups reads far better as columns.
- **Theme** slots: `title`, `panel` (9-sliced frame), `header`, `separator`,
  `details`, `quote`, `portrait`, `remove`, `removeHover`, `number`,
  `numberIcon`. Each names a **game** texture as its decoded path
  (`rsmm assets search` finds them), either as a plain string or as
  `{ texture = "…", ink = "dark" }`. `ink` (`light` by default) is the text
  colour that reads on that texture — the app cannot tell a parchment scroll
  from a slate panel, so you say which it is. The CLI accepts only `Ui/…png` paths the game's own asset map resolves,
  decodes them from the player's install when the editor opens, and caches them
  under `<game>/rsmm/cache/ui/`. Nothing is shipped with the mod, and a schema
  cannot name any other file. Leave the theme out and the grid uses the app's
  own style.

### Test offline (no game)

`rsmm.sdk.testkit` asserts over staged state without applying:

```python
from rsmm import sdk
from rsmm.sdk.testkit import expect, assert_no_conflicts

def build():
    m = sdk.builder.ModBuilder("FrostPack", version="1.0.0", author="you")
    blade = m.item("FrostBlade", base="Orb_Grants_Strength", name="Frost Blade")
    m.tag("daggers", [blade]); m.i18n("EN", {"FrostBlade_desc": "Freezes."})
    return m

def test_frostpack():
    (expect(build())
        .has_item("FrostBlade").has_tag("daggers", "FrostBlade")
        .i18n_complete().clean())          # every locale key present, no warnings

def test_no_clashes():
    assert_no_conflicts(build())           # safe alongside itself
```

### SDK quick reference

| Goal | Call / command |
|------|----------------|
| New content (handle), any kind | `m.content(kind, id=…, **fields)` |
| Shortcut for five kinds | `m.item/enemy/boss/map/hero(id, base=…)` |
| Find base ids | `rsmm schema [kind] [--grep T]` |
| Group content | `m.tag(id, [refs…])` |
| Override asset | `m.texture/model/asset(decoded, src)` |
| New skin slot | `m.skinpack(name, key=…)` |
| Config / strings | `m.config({...})` / `m.i18n(loc, {...})` |
| Preview staged state | `m.summary()` |
| Offline assertions | `from rsmm.sdk.testkit import expect, assert_no_conflicts` |
| Generated API docs | `rsmm docs-gen` → [`docs/api/`](/) |

---

## Recipes

### Replace a cooked file (raw)

```sh
# Find the decoded path:
rg -i "hero.*portrait" data/asset_map.csv

# Copy your file in:
cp /path/to/donor.dxt \
   mods/MyMod/assets/Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt

# Apply
./rsmm apply
```

### Texture swap (donor reference)

Point one shipped texture at another shipped texture, with no image file of
your own. There is no SDK method for this; declare it in the manifest:

```toml
[[patch]]
kind   = "texture"
target = "Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt"
donor  = "Ui/BookMenu/Heroes/UI_HeroPortrait_SunWukong_Active.png.Texture.dxt"
```

Both are decoded paths — find them with `./rsmm assets search Heroes Portrait png`.
`rsmm apply` copies the donor's pristine bytes to the target. To use your own
image instead, call `m.texture(path, "art/my.png")`.

### Custom 3D mesh (`.glb`)

```python
mod.model("3D/Characters/Heroes/Juliet/Juliet_GEO.fbx", "assets/my_mesh.glb")
mod.model(path, src, rotate_deg=(90, 0, 0), scale=0.8)  # orientation / size
mod.model(path, src, skin="gltf")                       # use YOUR OWN weights
mod.model(path, src, skin="rigid")                      # bind to ONE bone
mod.model(path, src, fit="none")                        # keep your own size
mod.model(path, src, submeshes="map")                   # keep the material split
```

The cooker replaces the mesh inside the shipped asset and keeps **that asset's
existing skeleton**. A custom skeleton is never written, so the bones your mesh
moves on are always the game's — but which of them each vertex rides is yours
to control.

#### Weights: `skin="gltf"` for a character, `transfer` for a prop

The default, `skin="transfer"`, copies weights *positionally*: each of your
vertices takes the weights of the game vertices nearest to it. That is right
for a prop, and for a body only if you authored it in the original's bind pose
— otherwise an arm vertex nearest a leg bone is weighted to the leg and the
model tears itself apart the moment it animates. `rsmm apply` warns when your
mesh does not overlap the original's bind pose.

**`skin="gltf"` is the way to replace a character.** Rig your mesh to the
game's skeleton in Blender, using the original's bone names, and export with
the armature. The cooker then reads `JOINTS_0`/`WEIGHTS_0` out of your `.glb`
and binds each vertex to the bone you named, so nothing is guessed and the pose
you modelled in stops mattering. It implies `fit="rig"` — no scale, no
recentre — because a mesh rigged to the game's skeleton is already in place.

Two helpers go with it. `bones={"MyBone": "DEF.Spine"}` renames joints on the
way in, for a rig that came from elsewhere; a name the target's skeleton does
not have is reported, and a vertex left with no usable bone is an error rather
than a silent pin to bone 0. `drop_bones=["DEF.PHY.Grab"]` deletes the geometry
a bone drives, for a donor carrying something that has to become a separate
object — a chain, a slung weapon.

Note that an `rsmm uncook` mesh carries **no** glTF skin (its weights ride in
`extras.rsmm.cooked_b64`, which Blender discards on re-export), so `skin="gltf"`
needs a mesh you actually rigged, not a round-tripped one.

`skin="rigid"` opts out of weights entirely and binds the whole mesh to a
single bone: it follows the character but never bends. Right for a prop or a
static shape, wrong for a body.

#### Submeshes carry materials

A character is several submeshes because the entity hands a different material
to each one. By default they are all merged into the first, which leaves the
rest as empty stubs — so everything draws with the first material and your
second texture never appears. `submeshes="map"` lays yours onto the original's
one for one instead. Pairing is by order, so order your objects in Blender to
match the original's.

Two limits worth knowing before you model: meshes above 65,535 vertices are
refused, because a heavier one crashes the game at load (decimate toward that
ceiling, not far below it — it is far higher than the vanilla count and looks
near-identical to a 250k film source); and a custom **skeleton** or custom
**animations** cannot be shipped at all, because nothing writes those formats
yet. Animation clips also key **translation** on every bone, not just rotation
— measured across a shipped hero clip, 113 tracks of 113 — so a posed skeleton
always has the original's proportions, and a taller or shorter body follows the
original's limb lengths no matter how it is bound. Reskinning what already
animates is the supported path.

### Numeric balance / modifier / camp difficulty

Three families of numeric values are editable by name: global values
(`*.globalvalue.ot`, e.g. `Bleed_Duration_Value`), game-modifier definitions,
and enemy-camp difficulty bands (`Easy`, …). The name is the asset's file name
without extensions — `./rsmm assets search globalvalue Bleed` lists them.

```python
with sdk.Mod("LongerStatusEffects") as m:
    m.stat("Bleed_Duration_Value", value=10)
    m.stat("Ignite_Duration_Value", value=11)
    m.stat("Easy", min=5, max=10)      # multi-field: one keyword per field
```

or directly in `manifest.toml`:

```toml
[[patch]]
kind  = "stat"
name  = "Bleed_Duration_Value"
value = 10
```

`rsmm apply` merges every enabled mod's `stat` patches into one file per value:
two mods changing different fields both take effect, and two mods changing the
same field log a conflict (the later mod by `load_order` wins). An unknown name
is reported and skipped.

### Randomise or replace a monster population (`kind="enemy"`, `mode="override"`)

Rewrites **retail** enemy definitions in place so a biome's slots instantiate
different creatures. Camps, tiers, tribes and difficulty are untouched — only
the prefab each slot spawns changes.

```toml
[[content]]
kind        = "enemy"
mode        = "override"
id          = "random_roster"
cross_biome = true     # draw from every creature in the game, and repoint each
                       # biome's EntityPooling asset so they are streamed there
mix         = "shuffle"  # each biome gets as many distinct creatures as it has
seed        = 1337       # pool slots, each used once ("random" draws with
                         # replacement and leaves ~a third of the slots unused)
```

`power` (optional) sets one power **cost** for every overridden enemy. It is
not spawn odds: a camp spends a power budget, so raising it makes each camp
field fewer, pricier enemies, and a cost above the budget means the enemy is
never picked. Vanilla camp enemies cost 0.1-20. `weight` is its old,
misleading name and still works with a warning.

**`cross_biome` is the load-bearing flag.** Without it a swap must stay inside
the biome's own entity pool, so the randomiser can only permute the cast that
chapter already had — Storm Island still shows crabs and gnolls, and it looks
identical to vanilla. With it, each chapter draws from all 50 camp-spawnable
creatures and gets 8-11 foreign ones. A biome hosts exactly as many distinct
creatures as it has pool slots (10-15): an `oCGameStream` ref can be repointed,
but the vector cannot grow.

Or pin a whole biome to one monster:

```toml
[[content]]
kind   = "enemy"
mode   = "override"
id     = "treant_world"
pools  = ["Dark_Hills"]
entity = "Enemies\\Treant\\Standard_Clawed_Treant.entity.ot"
```

Or write the cast yourself, chapter by chapter, instead of letting the seed
deal it:

```toml
[[content]]
kind          = "enemy"
mode          = "override"
id            = "my_roster"
cross_biome   = true
repoint_pools = false     # required to pull a creature across chapters
mix           = "random"  # how the cast is spread over the chapter's defs
seed          = 1337

[content.casts]
Dark_Hills   = ["Elite_Wolf_Alpha", "Standard_Reef_Crab", "Standard_Storm_Jinn"]
Storm_Island = ["Standard_Clawed_Treant"]   # one monster = the whole chapter
```

A chapter listed in `casts` draws **only** from the monsters written there; a
chapter left out keeps its dealt (or vanilla) cast, so pinning one chapter does
not reshuffle the others. Monsters may be named by definition id
(`Elite_Wolf_Alpha`), prefab stem, or full entity ref. `mix` still decides how
the cast spreads over that chapter's ~15 definitions, which is why a
one-monster list turns the whole chapter into that monster.

The same cast can come from the mod's **config panel** instead of the
manifest: declare one `multiselect` field per chapter, named after the pool,
with `source = "enemy-roster"` in `config_schema.toml`, and the desktop app
draws a grouped monster picker. A chapter the player picks for overrides the
manifest's cast for that chapter; an empty pick leaves it on the roll. See
`mods/random-monsters` for the worked example. Two same-`source` multiselect
fields are treated as buckets over one option set, so the panel draws each
pick as a chip with a remove (×) and a "move to another list" arrow — moving a
monster from one chapter to another is one click, not a hunt through two
50-row scrollers.

The picker's options and the re-emit both work on a plain install: the enemy
definitions, pool assets and resource caches are read from the uncooked mirror
when an authoring checkout has one, and otherwise straight out of
`<install>/DarkTalesResources/_Cooking` through the bundled `asset_map.json`
(preferring the pristine `.rsmm.bak` when a previous apply left one). Both
stores hold the same bytes, and a test asserts an emit from either is
byte-identical.

Casting a creature from another chapter needs `cross_biome = true`, and
`repoint_pools = false` is the combination proven in-game. With pools rewritten
(`repoint_pools = true`) two extra rules are enforced, both of which crash a
chapter transition otherwise: a cast may not be longer than the chapter's pool
slots, and no creature may be cast in two chapters at once.

`rsmm enemies pools` lists the biome pools; `rsmm enemies pool <biome>` lists
the prefabs valid as `entity` there. Scope defaults to every open-world pool;
narrow it with `pools`, extend it with `enemies`, and drop individuals with
`exclude`.

Two rules the builder enforces rather than documents, because both fail
silently in-game:

- **A creature is only ever assigned to a biome that streams it.** Candidates
  come from the biome's own cast, and under `cross_biome` the pool is rewritten
  first so the cast is streamed. Only def-owned pool slots are repointed —
  never the projectiles, attack zones and VFX trails a real attack needs.
- **The resource cache travels with the swap.** Each rewritten definition gets
  the sorted union of its own `*.UsedRscCache.ot` and that of the definition
  owning the new prefab. Without it the new meshes are unlisted, resolve to
  null at level build, and the engine's teardown loop destroys the null — an
  access violation nowhere near the edit.

Bosses, summons and quest enemies are never in scope: no pool streams them, so
they are placed by the script owning their encounter rather than rolled by a
camp selector. To make a boss arena fight a different boss, use the `boss`
kind, which knows which arenas pick their boss by flag alone.

:::caution[Unproven: imported creatures' support entities]
A creature's projectiles and attack zones live in *its home* biome's pool. When
`cross_biome` imports it elsewhere those entries are not repointed in, though
the merged `UsedRscCache` does carry them. Whether pool membership is
separately required for them is untested — if an imported creature misfires,
this is the first thing to suspect.
:::

**The roll happens once, at `rsmm apply`**, and is baked into the emitted
assets — not re-rolled per run. That is what keeps co-op consistent: peers
have to agree on the seed, not on a runtime RNG. A peer without the mod sees
vanilla monsters.

### Disable items (`kind="item"`, `mode="ban"`)

Drop vanilla magical objects from the catalog so they can never be offered or
drop — the "ban the crutch items" challenge-run lever.

```toml
[[content]]
kind  = "item"
mode  = "ban"
id    = "no_crutches"
items = ["Avoid_Death_Once_Per_Chapter", "Armor_Per_Object"]
```

Or skip the ids entirely and **pick the items from a list of the game's own
icons**: the `banned-items` mod declares a `multiselect` config field (see
[Config with icons](#config-with-icons-multiselect)), so opening its config in
the desktop app shows every item with its art, display name and effect text, and
the ban list is whatever you ticked. `rsmm items catalog` is the same list in a
terminal, and `rsmm items ban --add <id>` edits it without a UI. When a mod
declares the picker, the picker's selection wins over the manifest's `items`
list.

`items` are bare vanilla item ids — the filenames under
`EntitySettings/Objects/Magical_Objects/<Rarity>/`. `rsmm apply` rebuilds the
LiveOps `versiondef` magical-object vector without them, so the engine never
loads them into the pool and no draw can reach them. The vanilla manifest is
backed up once and rebuilt from that pristine copy on every apply, so disabling
the mod restores the full catalog.

Bans from several mods are **unioned**, so two mods each banning a different
item yield both bans.

:::caution[This works in multiplayer only if every peer runs the mod]
The offer draw is seeded and *host-authoritative deterministic*, so a per-peer
runtime filter — a loader hook, a Lua callback — would make peers disagree
about the roll and desync the run. That is why the ban is data-level: every
peer builds an identical pool from identical assets, so the deterministic draw
stays identical everywhere.

Mismatched installs do **not** crash — a grant networks by GUID and the pool
lookup guards a miss, so a peer without the item simply doesn't receive it —
but players will see different offers. Whether a host-only install is enough
(i.e. whether offers are drawn host-side and broadcast, or replayed per peer
from a shared seed) is **untested**; don't rely on it.
:::

Two side effects worth knowing:

- A banned item **disappears from the compendium** too. The catalog entry is
  what the compendium enumerates; there is no separate "hide from drops only"
  flag.
- The entity file itself stays installed and its resource-cache line is left
  alone. That is deliberate: a surplus cache line only wastes a preload, while
  a missing one crashes the load.

An id that no vanilla item has is refused at emit time when the asset corpus is
available, and reported as a `[warn]` against the install's own manifest at
apply time. Banning a name nothing matches is otherwise a perfectly well-formed
no-op that only surfaces as "the banned item still dropped" a playtest later.

### Edit the Sandman shop (`kind="shop"`)

The Sandman is the game's vendor. A `shop` def changes what it costs and what it
offers, by overriding the retail files in place. There is one Sandman, so a mod
declares at most one.

```toml
[mod]
id           = "cheap-sandman"
multiplayer_scope = "deterministic-shared"   # every peer needs the same shop

[[content]]
kind        = "shop"
id          = "sandman"
price_scale = 0.5              # every item not listed below costs half

[content.prices]               # dream shards; prefix Power_Up_Sandman_ is optional
Minor_Heal                        = 10
Major_Upgrade_Talent_To_Legendary = 150

[content.offers.minor]
count = 2                      # vanilla rolls 4

[content.offers.major_object]
weights = { legendary = 1, cursed = 0 }   # unlisted qualities keep their vanilla weight
```

What the shop is made of:

| Generator | Vanilla count | Pool | Quality weights |
|---|---|---|---|
| `minor` | 4 | `Sandman; Minor` (heal, reroll, shield, strength) | powerup |
| `medium` | 1 | `Sandman; Medium` | powerup |
| `medium_duplicate` | 1 | `Sandman; MediumDuplicate` | powerup |
| `medium_object` | 1 | none — a random magical object | common 0.5, rare 0.5 |
| `major` | 1 | `Sandman; Major` | powerup |
| `major_duplicate` | 1 | `Sandman; MajorDuplicate` | powerup |
| `major_object` | 1 | none — a random magical object | epic 0.5, legendary 0.25, cursed 0.25 |

Vanilla prices: Minor items 50–75, Medium 100–200, Major 250.

Each generator accepts `count`, `weights` (qualities `common`, `rare`, `epic`,
`legendary`, `cursed`, `powerup`) and `pool` (the include-flag filter; `""`
means no filter). Things to know:

- **A generator never offers the same item twice**, so a `count` above the
  number of items in its pool adds nothing. The `minor` pool holds exactly 4
  items, which is why the vanilla Minor row never changes.
- **Every Sandman item is quality `powerup`.** Moving a Sandman pool's weight
  onto another quality finds nothing to offer.
- **The `*_duplicate` and `*_object` generators are a pair.** The duplicate
  offer is a powerup, and the object offer is the magical object it copies.
  `major_object`'s weights decide which quality of object that is.
- **Prices are also multiplied at runtime** by the hero's "Reduce all dream
  shard prices" and "Reduce Sandman dream shard prices" values and the run's
  "Dream Shard Costs Modifier" (the `HigherPrices` game modifier), then rounded.

Unknown items, generators, qualities or fields raise at emit time rather than
producing a file that silently changes nothing.

**Choosing exactly which items a slot offers.** `slots` names the items per
generator, and is how an item from another family (a Grimoire chapter, a
Wishing Well gift) gets into the shop:

```toml
[content.slots.minor]
items = ["Power_Up_Sandman_Minor_Heal", "Power_Up_Grimoire_Armor_High"]
count = 2                      # up to what the slot ships with; minor needs at least 2
```

The shop screen shows two of each tier's three offers (the offer, the copy
offer and the random magical object), so all three are slots you can fill.
`medium_object` and `major_object` ship with no item list — they sell a random
magical object of the listed rarities — and giving one `items` makes it sell
those instead (its weights switch to `powerup`, the only quality they have).

A slot whose list differs from the game's gets its own pool tag
(`RSMM_Shop_minor`), and each chosen item gets that tag appended to its flags.
Nothing is removed from any item, so other vendors that read the same items are
unaffected.

:::danger[The Minor slot must offer at least two items]
When the shop opens, the game picks two *different* Minor offers with no guard
against a shorter list, so a Minor roll of one item crashes the game (an integer
divide by zero). The `shop` kind refuses a Minor `count` below 2 and a Minor
pool with fewer than two items, from `slots`, `offers` or a config grid alike.
Give the editor's Minor section `count = { min = 2, … }` so it never offers the
value in the first place.
::: Only powerups that carry flags of their own qualify (45 of them),
and a `*_duplicate` slot only takes the powerups that copy an object.

**Editing it from a config screen instead.** Point the shop at an
[`item-grid`](#editors-for-lists-of-game-items-item-grid) field backed by the
`shop-items` provider, with one section per slot id, and the player edits
slots, counts and prices in the desktop app; the grid's stored value replaces
`slots` and `prices`:

```toml
[[content]]
kind   = "shop"
id     = "sandman"
config = "shop"                # the item-grid field in config_schema.toml
```

:::caution[Not yet proven in-game]
The field meanings come from the shop's generator, quality-roll and price code
in the game executable, and every edit round-trips byte-for-byte, but no edited
shop has been opened in-game yet. Setting a `pool` to flags outside the
`Sandman` family, or a `count` above what the shop screen has room for, is
untested. Multiplayer behaviour follows the item ban above: run it on every
peer.
:::

### Magical-object & talent values (`value_patches`)

Edit the numbers inside a magical object or a hero talent ("Skill"). Discover
the editable labels + defaults first, then declare the edits in `manifest.toml`:

```sh
./rsmm items show Damage_Power      # item value fields (+ [shadowed] markers)
./rsmm talents Juliet               # hero talent values (+ [shadowed/no-op])
```

```toml
# Item: clone a vanilla magical object with patched values
[[content]]
kind = "item"
id   = "MyStrongerPower"
base = "Damage_Power"
value_patches = [
    ["Power Crit Chance Value", 0.4, 0.1],
    # A shadowed value (see below) needs clear_override to take effect:
    { label = "Damage Value", old = 0.2, new = 0.5, clear_override = true },
]

# Talent: patch a hero's cooked entity in place (plain override, no clone)
[[content]]
kind = "talent"
hero = "Juliet"
id   = "JulietBuff"
value_patches = [["Primary Ability Rose Explosion Damage Value", 8.0, 24.0]]
```

**Shadowed values.** Some value nodes don't use their inline number — the game
reads the value from a selector/curve (e.g. card-count scaling), so editing the
inline float is a silent no-op. `rsmm items show` / `rsmm talents` tag these
`[shadowed]`, and `apply` **errors** if you patch one without
`clear_override = true`. Clearing the override makes the inline number
authoritative but unbinds the selector — e.g. per-card-stack scaling becomes a
flat value. That trade-off is intentional; pick the flat number you want.

### Which stat an item's effect gives (`stats`)

Each effect of a magical object (its always-on effect and its super effect)
changes one stat. `stats` points an effect at a different one, by the effect's
name. `rsmm items show <base>` lists the effects, the stat each one gives, and
whether it is the super effect:

```toml
[[content]]
kind = "item"
id   = "Damage_Per_Vitalitz"
base = "Damage_Per_Vitality"
name = "Ogre Crit"
stats = { "Super Effect Modifier" = "Crit damage" }
value_patches = [["Super Effect Crit Chance Value", 0.2, 0.3]]
super_description = "#Crit Damage@ &+{0}%~"
```

- **Stat names** are the engine's own (`Attack power`, `Crit chance`,
  `Crit damage`, `Armour`, `Vitality`, `Move Speed Ratio`, …); the full list is
  `data/stat_keys.json`. A few stats have no name yet; give those by key
  (`"0x58e0a5c"`), as `rsmm items show` prints them.
- **The amount keeps its old unit.** 0.2 crit chance becomes 0.2 of the new
  stat, so change the number with `value_patches` too.
- **`super_description`** gives the copy super-effect text of its own (the base's
  text still names the old stat). Items without a super effect (cursed,
  legendary, power-ups) refuse it.
- **Some stats need more than the stat.** Plain numbers (attack power, armour,
  crit, cooldowns, move speed) work anywhere. Flags like `Lightning explode` or
  the instant-kill thresholds only do something with the components the item
  that ships them carries.

A **talent** takes the same `stats` table, next to its `file` (effect names
repeat across a hero's files):

```toml
[[content]]
kind  = "talent"
id    = "aladdin_wish_armour"
hero  = "Aladdin"
file  = "Hero_Aladdin.entity"
stats = { "Ability Trait Wish 3 Shield Gain Modifier" = "Armour" }
```

The **Items** and **Talents** tabs of `rsmm editor` and the
[web editor](/guides/web-editor/) show the same thing as a stat picker per
effect.

### Lua-scripted mod

The loader DLL (`dist/winhttp.dll`) runs `init.lua` once per launch in a sandboxed `lua_State` per mod.

```sh
./rsmm install-loader     # Copy the DLL into the game install
```

Add to Steam launch options: `WINEDLLOVERRIDES="winhttp=n,b" %command%`.

Lua API exposed to mods:

```lua
-- Runtime
rsmm.log(msg)
rsmm.mod_dir()                       -- this mod's directory
rsmm.game_dir()                      -- absolute install dir
rsmm.is_in_main_menu()               -- bool
rsmm.list_mods()                     -- {id, name, version, author, enabled}[]
rsmm.encoded_path(decoded)           -- decoded -> encoded path
rsmm.decoded_path(encoded)           -- encoded -> decoded path
rsmm.register_asset_override(decoded, src_abs_path)
rsmm.commit()                        -- apply registered overrides
rsmm.on_event(name, fn)              -- "ready" | "exit"

-- Game function access (53k functions resolvable by name)
rsmm.resolve(name)                   -- "FUN_xxx" -> runtime VA
rsmm.call(target, "sig", ...)        -- invoke by signature
rsmm.module_base()                   -- Ravenswatch.exe image base
rsmm.read_u8/u16/u32/u64/f32/f64(va) -- raw memory read
rsmm.read_cstr(va, max)              -- read NUL-terminated string
rsmm.write_u8/u16/u32/u64/f32/f64(va, v)
```

See `mods/ExampleLuaMod/init.lua` and `mods/ExampleSeedPin/init.lua` for working examples. Full game-function API + caveats: [docs/_re/CALLING_GAME_FUNCTIONS.md](/reverse-engineering/calling-game-functions/).

### Events

`R.on` is the whole surface. Both engine buses are armed by default, so a mod
sees every event the game fires without the user touching launch options.

```lua
local h = R.on("gameplay:GIVE_MAGICAL_OBJECT", function(ev) ... end)
R.on_match("^gameplay:ABILITY_", function(ev, name) ... end)  -- whole family
R.once("run:start", function() ... end)                        -- fire once
R.off(h)                                                       -- unsubscribe
R.emit("mymod:something", { n = 1 })                           -- tell other mods
```

Four sources land on the same bus:

| Source | Names | Notes |
|---|---|---|
| Lifecycle | `setup`, `ready`, `tick`, `exit` | loader thread |
| Analytics firehose | `run_start`, `enemy_killed`, `unlock_hero`, … | after the action, no live handles |
| Gameplay bus | `gameplay:<NAME>` | at the action, live handles, game's MAIN thread |
| Loader-derived | `hero:captured`, `hero:changed`, `hero:lost`, `menu:enter`, `menu:leave`, `run:start`, `run:end` | loader thread |

`ev.source` says which (`"analytics"`, `"gameplay"`, `"loader"`, `"mod"`) — and
it is stamped by the loader, so it can be trusted. **Only `"gameplay"` handlers
run on the game's main thread**; anything else must route engine-mutating work
through `R.schedule.next_main` (see [the thread model](/reverse-engineering/event-systems/)).

**150 gameplay events are catalogued** — mined out of the shipped exe by
`tools/mine_event_names.py` and browsable without launching anything:

```sh
./rsmm symbols events            # all of them, grouped by family
./rsmm symbols events boss       # BOSS_ACTIVATED, BOSS_DEFEATED, …
```

A taste of what's on the bus: `BOSS_DEFEATED`, `OPEN_CHEST`, `HERO_REVIVE`,
`START_NIGHTMARE`, `WISHING_WELL_FILLED`, `USE_HEAL_FOUNTAIN`,
`UPGRADE_RANDOM_SKILL`, `DUPLICATE_RANDOM_EPIC_OBJECT`, `CHOOSE_MELODY`,
`MAP_GENERATION_DONE`, `TELEPORT_SUBMAP_ENTER`, `ENEMY_KILLED`.

The same catalog is available inside the game, plus a live one of everything
that has actually fired:

```lua
R.events.known("gameplay")    -- the 150 static names, before anything fires
R.events.category("BOSS_DEFEATED")   --> "boss"

R.events.list("^gameplay:")   -- sorted names seen THIS session
R.events.count("enemy_killed")
R.events.dump()               -- log every event with its count + payload keys
```

The catalog is a browsing aid, not a whitelist: the loader reads the plaintext
name off the event object, so a name a future patch adds fires too.

### Event payloads

Most events have **no payload** — and that is the engine's design, not a gap
in ours. There are only ~24 `oCGameNamedEvent` subclasses that carry data;
every other name is dispatched as the bare base class, so all it can tell you
is *that it happened*, plus the `dispatcher` / `entity` handles saying to whom.

For the ~24 that do carry data, the layouts are recovered from the binary by
`tools/mine_event_payloads.py` (RTTI → vftable → the code that stores it) and
the loader decodes them by matching the event's **own vftable**, so the match
is exact:

```lua
R.on("gameplay:NETWORK_DAMAGE", function(ev)
    R.log(ev.value)          -- 12.5      (f32, hand-confirmed)
    R.log(ev.source_id)      -- "0x2a1f…" (the attacker's NET id; handles are
    R.log(ev.dispatcher)     --            hex strings, because a Lua number
end)                         --            would lose the low bits)
```

Read the field names honestly: **offsets and widths are recovered, meaning is
not.** A field only gets a semantic name (`value`, `source_id`,
`mo_guid_lo`) where hand-RE confirmed it; everything else is mechanical —
`u50` is "u32 at +0x50", `f6c` is "float at +0x6c". They are real fields at
real offsets, but what they *mean* is for you to pin down.

Two things help with that. `ev.class` tells you which struct you are looking
at, and the `RSMM_EVENT_PROBE` loader flag adds a raw window (`ev.w38 …
ev.w70`) to every gameplay event — so a field gets pinned from Lua in one
session instead of a C++ rebuild per guess.

Decoding is gated on the build fingerprint: vftable addresses are
build-specific, so after a game update the loader falls back to the plain
envelope until the schemas are re-mined
(`python tools/mine_event_payloads.py --verify`).

### Damage attribution (`R.damage`)

"Who is carrying the run?" is a question about damage per PLAYER, and no single
event answers it. `R.damage` merges the three places the engine produces a
damage number with an attacker attached, and hands you a live ranking:

```lua
R.damage.enable{ window = 10 }          -- opt-in: it installs engine hooks

R.damage.on(function(hit)
    -- hit.label / hit.slot / hit.is_local / hit.amount / hit.source
    -- hit.kind == "dealt" (they hurt something) or "taken" (they got hurt)
end)

for _, row in ipairs(R.damage.board()) do   -- already sorted, row.rank set
    R.log(row.rank, row.label, row.dealt, row.share, row.dps, row.by_type.ultimate)
end

R.damage.leader()          -- the row on top right now
R.damage.engine_totals()   -- the game's OWN totals for the local player
R.damage.reset()           -- e.g. per run or per chapter
```

#### Enemies only, or everything the game counts?

Fences, jars, vegetation and mission props are damageable entities, so damage
dealt to them reaches the same bookkeeping hook a boss does — and the engine's
own end-screen total counts it. A player who clears a room of furniture can
therefore out-rank one who fought. Opt out per meter:

```lua
R.damage.enable{ ignore_scenery = true }   -- rank enemy damage only
R.damage.ignore_scenery(true)              -- or toggle it mid-run
R.damage.scenery_total()                   -- what the filter dropped
R.damage.is_enemy(entity)                  -- true / false / nil = unknown
```

The test walks the victim's **component map** — an `oCEntity` keeps its
components in an F14 table (slots at `entity+0x5f0`, stride `0x10` =
`{u32 class id, component*}`, bucket mask at `+0x600`) keyed by the engine's
32-bit class id. A gameplay enemy carries
`oCDtEntityCpntEnemyController` = `0x1561073c`; destructible props carry only
Hittable + HitPoint. Class ids are mined by `tools/mine_class_ids.py` into
`data/class_ids.json`, and a class id is a hash of the class NAME, so it
survives a game patch that moves every address.

It is a page-guarded READ — never an engine call — so a stale offset gives a
wrong answer, never a crash, and an entity that cannot be read is `nil`
(**unknown**), which still counts: a failed read must never delete a player's
real damage. Filtered damage is not lost either — it stays on the row as
`row.scenery` / `row.scenery_hits`.

:::caution
Do **not** look for components in the pointer array at `entity+0x190` /
`+0x198`. That array belongs to an `oCEntitySpawnerGo` (it is what
`Entity_GetComponentByTester` takes), not to an `oCEntity`. Reading it off an
entity returns nothing for most victims and an unrelated vector for the rest —
which is exactly how the first version of this filter classified every enemy in
a live run as "unknown" and did nothing at all.
:::

The SDK default is **off**, because counting props is what agrees with the
game's own total; filtering is a deliberate divergence a mod asks for. The
bundled `damage-meter` mod turns it **on** — a prop takes a flat 1.0 per hit, so
counting props distorts hit counts and DPS far more than damage.

| Source | Sees | Identity |
|---|---|---|
| `HeroStats_OnDamageDealt` (hooked) | **every hero's** damage applied on this machine, allies included | hero controller |
| `Entity_ResolveAttackHits` (hooked) | attacks resolved locally — used for damage **taken**, and as a fallback | attacker entity |
| `gameplay:NETWORK_DAMAGE` | damage the target's owner **replicates** to you | attacker net id |

The first source is what makes an ALLY's damage countable. It is the engine's
own per-hero bookkeeping, and it runs for every hero — the game just declines
to *total* anything for a hero that is not the local player (its `+0x1d88`
gate), which is why the end-of-run screen only ever shows your own numbers.
Hooking it read-only gives every hero's damage, split by ability type
(`row.by_type.attack / power / special / defense / trait / ultimate / dash`).

The three views are unified per player: a row found by controller, by entity
and by net id is the same row, so nobody appears twice and `share` stays
honest. A replicated echo of a hit already counted locally is dropped, while
repeated identical hits from one source (a multi-hit flurry) are kept.

A player keeps ONE row across a chapter change, where the engine rebuilds every
hero controller: the row is re-adopted by hero id (exact — each player's hero is
distinct) or, failing that, by the engine's is-local byte. Both joins are gated
on a **chapter epoch**, bumped by `GAME_END_NEXT_CHAPTER` /
`MAP_GENERATION_DONE`: inside one chapter, a hero controller the meter has never
seen is a **different player**, never a rebuilt one. Without that gate the
third and fourth players to deal damage are adopted as "the same person again"
and a four-player board collapses to two rows — a merge deletes a player, while
the duplicate it prevents is visible and keeps everyone's damage. A declined
merge is logged (`refused to merge …`), as is every row boarded, with the
`local_byte` and `hero_id` the joins were about to use.

Every hook is observation-only: it replays the original with the exact
arguments it received and returns the engine's own result, so no damage value,
target list or event changes.

:::caution[A peer can only count what its machine sees]
The replication event is built solely on the machine that OWNS the target, and
only for a remote attacker — so nothing double-counts, but the **host**, which
owns the enemies, is the peer with the most complete board. Your own damage is
always correct on any peer. This is a property of the netcode; no mod can widen
it.
:::

The `damage-meter` mod is the ready-made consumer: it reports to the loader log
and publishes an overlay once a second (see below), which feeds both
`rsmm overlay damage-meter --watch` and the desktop app's overlay window.

### Player names (`R.player`)

```lua
R.player.name()              --> "Ovilli"  (nil when Steam is unavailable)
R.player.name_of(steamid64)  --> a known account's name, or nil
```

The **local** player's real display name, read from `steam_api64.dll`'s flat
API by the loader — no game structures, so it survives game patches. `R.damage`
uses it to label your own row instead of "You".

**Remote** players are not named yet, and the reason is worth knowing before
you try: the game resolves an ally's name from the party member's user-data
JSON (`steam.personaName`, `gamertag`, `Nickname`, `pseudo` — `FUN_140929940`)
and stores it in the party-slot UI model, but nothing observed so far links a
party slot to the hero entity a damage row is keyed by. Pinning that link needs
a live co-op session. Until then, label unknown players by join order and let
the player rename them (the damage-meter mod exposes `player_1..4` for exactly
that).

### Overlays (`R.overlay`)

The game gives a mod nowhere to draw a HUD, so a mod can publish one to the
desktop client instead. Two halves:

**Declare the shape** in `manifest.toml`. The client renders exactly this:

```toml
[overlay]
title     = "Damage"
icon      = "swords"                       # from a fixed icon set
sort      = { key = "dealt", dir = "desc" }
highlight = "is_local"                     # bool row key -> accented row
empty     = "Waiting for a run."

[[overlay.columns]]
key = "label"
label = "Player"
type = "text"                              # text | number | percent | bar

[[overlay.columns]]
key = "dealt"
label = "Damage"
type = "number"
format = "compact"                         # 48.2k
suffix = ""
```

**Publish the rows** at runtime, at whatever cadence suits the mod:

```lua
R.overlay.publish{
    rows = { { label = "You", dealt = 4821, share = 0.57, is_local = true } },
    meta = { total = 8410 },               -- shown in the footer
}
R.overlay.clear()                          -- e.g. at a run boundary
```

Rows are flat records of string/number/boolean — anything else is dropped. An
unchanged payload is skipped, so publishing every tick costs nothing.

Then: the desktop app puts an **Overlay** button on the mod itself (library card,
list row, mod page) for every mod that declares one, and `rsmm overlay <mod>`
renders the same board in a terminal.

:::note[Shape is data, never code]
A mod declares columns; it cannot hand markup or script to the client. That
webview can spawn the CLI, so mod-supplied code in it would be arbitrary code
execution on the player's machine — and every overlay would look like whatever
its author felt like that day. `rsmm lint` rejects a malformed declaration.
:::

### Hot-reload (Lua iteration < 5 seconds)

Run `./rsmm watch` in a side terminal while the game runs. On any save under `mods/`:

1. Lints the mods you changed. A lint error holds the apply back and is printed, so a typo
   never reaches the game (`--no-lint` skips this).
2. Re-applies cooked overrides and syncs each enabled mod's `manifest.toml`, `init.lua` and
   other top-level Lua/data files into the game-dir `mods/<id>/`.
3. The loader polls those files every ~1 second, tears down the changed mod's `lua_State`, and re-runs `init.lua`.

Tweak a number, hit save, see the result in-game without restarting.

Watch the live log:

```sh
./rsmm log -f --grep "lua\|reload"
```

Expected output on a Lua-only edit:

```
[lua] ExampleSeedPin reload (init.lua changed)
[lua] ExampleSeedPin init OK
[SeedPin] forced seed = 12345 (enable=1) after 1 ticks
```

---

## Reading the loader log

The loader writes to `<game>/mods/_log.txt`. Read it from the repo:

```sh
./rsmm log              # Full dump
./rsmm log -n 80        # Last 80 lines
./rsmm log -f           # Follow live (Ctrl-C to stop)
./rsmm log --grep lua   # Filter (case-insensitive)
./rsmm log --clear      # Clear before a fresh launch
```

Lua errors print as `[lua] <mod-id> ...`; `rsmm.log("msg")` calls land in the same file.

---

## Loader features a mod needs

Some loader features are off until switched on, because they hook the engine
more deeply. The one mods need most is **hero capture**: without it `R.entity`,
`R.stat`, `R.combat`, `R.xp`, `R.camera` and the talent grants never find your
hero, and a mod that uses them silently does nothing. Declare what your mod needs
and `rsmm apply` switches it on while the mod is enabled (and off again when no
enabled mod needs it, leaving flags the player set alone):

```toml
[mod]
id           = "camera-control"
loader_flags = ["RSMM_ENABLE_HERO_CAPTURE"]
```

Only the flags the app's **Loader features** panel lets a player switch on are
accepted; `rsmm lint` names them. In Lua, `R.entity.capture_enabled()` tells "the
player turned it off" apart from "the hero is not found yet" (loading, menus).

---

## Don't ship vanilla bytes

`rsmm pack <id>` hashes every file against the original cooked asset. If any file is byte-identical to the original, pack **refuses** — shipping unmodified game bytes is redistribution of copyrighted game content, not a mod.

```
$ ./rsmm pack MyMod
refusing to pack MyMod: contains files byte-identical to original game assets ...
  assets/Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt  (matches original cooked asset)
```

Fix: replace the listed files with your own modified bytes. `--allow-vanilla` bypasses the check for personal backup zips only.

The `data/uncooked/` mirror is git-ignored for the same reason — it exists for local reference only (see [Uncooked Assets](/guides/uncooked-assets/)).

---

## Online play: client-only and gameplay mods

For online play, RSMM sorts every running mod into one of two groups:

- **Client-only** mods change what *you* see or read, never the game the party plays:
  a damage meter or other overlay, a camera change, a texture or sound swap, new UI text.
- **Gameplay** mods change the game: new or edited content (`[[content]]`), data
  patches (`[[patch]]`), overrides of game data, or Lua that does more than read
  (`R.give`, `R.stat.modify`, `R.hp.set`, `R.talent.grant`, `R.emit`, …).

An install that runs only client-only mods counts as **vanilla** online. Run
`rsmm modpack` to see which group each of your mods is in, and why.

RSMM decides the group from what the mod contains, not from its
`multiplayer_scope`, so a wrong declaration cannot move a mod into the
client-only group. Lint warns when a mod declares `cosmetic` or `local-only` (or
nothing) but changes the game. Declare `deterministic-shared` or
`host-authoritative` for those.

For Lua, the client-only calls are the whole of `R.log`, `R.on`/`R.off`/`R.once`,
`R.overlay`, `R.config`, `R.kv`, `R.schedule`, `R.exp`, `R.health`, `R.i18n`,
`R.damage` and `R.camera`, plus these reads: `R.entity.hero`/`ready`/`hp`/`hp_frac`/`max_hp`,
`R.stat.get`/`cached`/`keys`/`names`, `R.hp.get`/`frac`/`max` and
`R.events.known`/`count`/`category`. Anything else, including `R[...]` lookups or
passing `R` to another function, counts as gameplay.

## Load order

When two mods override the same encoded path, the applier keeps the **later mod by alphabetical id** and warns. Explicit load-order control will come with the in-game UI. If order matters now, encode it: `10_Patch`, `20_Skins`, ...

---

## Content kinds & confidence

Every content kind carries an honesty rating — **how much we trust the bytes
it emits**. The single source of truth is
`src/rsmm/sdk/content.py::KIND_CONFIDENCE`, which `rsmm lint` and the SDK
enforce. The per-kind table is **generated** from it:
[Content kinds & confidence](/reference/sdk-api/kinds/). This page links there
rather than restating a rating, because a hand-kept copy drifts the first time
a kind is proven in game. (`tests/test_kind_docs_lockstep.py` fails if a prose
table here pairs a `kind="…"` with a rating.)

**Finer than a kind.** Some kinds have modes proven to different degrees. The
kind's rating is the weakest mode it ships, so read these alongside it:

- `kind="enemy"`, `mode="override"`: proven in-game 2026-08-28. A
  fixed-entity override turned every Dark Hills camp into treants, and
  `cross_biome` placed chapter-2/3 creatures in an earlier chapter. What's still
  unknown is an imported creature's projectiles and attack zones (see the
  caution above).
- `kind="enemy"`, `mode="clone"`: proven in-game 2026-09-24. A Gnolls-tribe
  clone with a Mud Crab body spawned in Storm Island gnoll camps. The def
  self-registers onto its tribe's roster at load, so `UsedRscList` registration
  is the whole contract. The trap: `power` (formerly `weight`) is the clone's
  **cost** against the camp's power budget. At 20, the first attempt was priced
  out of every gnoll camp and never appeared. Leave it unset to keep the base's
  cost.
- `kind="item"`, `mode="ban"`: the exact inverse of the proven catalog write. It
  drops entries from the same LiveOps MO vector. It hasn't been confirmed
  in-game yet.
- `kind="mesh"` is proven, but an override is **global**: every tile that uses
  that mesh changes too. A character replacement also needs the right
  `transform.skin`, or the model is shredded on the first animation frame.

**Capabilities that are not content kinds:**

| Capability | Rating | Reality |
|---|---|---|
| **Replace a cooked file** (raw / texture / model / stat / text / url patch) | ✅ confirmed | Install-time file replacement. Bread and butter. |
| **PNG → cooked texture** | ✅ confirmed | `engine/cooked_schemas/texture.py` cooks PNG/DDS/TGA into the `oCTexture` container at apply-time. |
| **Reskin an existing hero** (texture/model override) | ✅ confirmed | See `JulietReskin`. |
| **New selectable skin slot** | ⚠️ experimental | Needs the loader skin detour; the DLC-entitlement filter rejects new keys by default (`RSMM_SKIN_FORCE_SHOW=1` to test). Replacing an existing slot is ✅ confirmed. |
| **Engine event hooks** (`R.on("OnDamage", …)`) | ⚠️ experimental | The event bus + payload envelope ship in the loader, and emitter addresses are mapped — but the runtime path is **not yet verified end-to-end on CI** (loader is Windows-only). Treat as unproven until the loader smoke test (below) is green. |
| **Call any of 53k game functions from Lua** (`R.engine.call`) | ✅ confirmed | Covers seed pinning, stat reads, save inspection, forced option overrides. Interception (hooks) is the experimental part above. |

**Opting into unverified kinds.** Registering any non-`confirmed` kind requires
`sdk.Mod(..., experimental=True)` (and the manifest records `experimental = true`);
otherwise the SDK raises and `rsmm lint` fails. This is deliberate — a ⚠️/❓
kind is a known guess, not a finished feature.

```python
with sdk.Mod("MyMapMod", experimental=True) as m:   # required for any non-confirmed kind
    m.map("Twilight_Hills", base="Dark_Hills")
```

See [docs/INTERNALS.md](/architecture/internals/) for the engine notes that ground all of the above, and [docs/ROADMAP.md](/project/roadmap/) for open work.

---

## Cooked-file inspector

```sh
./rsmm decode <path-to-cooked-file>       # Structural dump
./rsmm decode <path> --raw                # Include hex payloads
```

Parses the class table + section structure. Won't fully decode per-class property bodies (schemas live in `Ravenswatch.exe`) but prints enough to identify what you'd be modifying.

---

# SDK v3

> Design spec for the v3 mod-authoring SDK.

Source: https://docs.rsmm.me/guides/sdk/

:::note
**This is a design/rationale doc, not a how-to.** To *write a mod*, go to
[MODDING.md](/guides/modding/) and its
[Python SDK section](/guides/modding/#authoring-with-the-python-sdk). This file
explains *why* the SDK is shaped the way it is.

Status: design + scaffold landed (2026-05-19). Schema-mining + TLS-injection
are scaffolded but their RE / native work is open. See "Open work" at the
bottom for what is still empirical.
:::

## Goals

1. **Add new content** — items, enemies, bosses, maps, heroes — declared from a
   mod, materialized as cooked-asset writes by RSMM.
2. **Edit existing content** — every kind above, plus numeric values, texture
   swaps and plaintext `.ot` fields. Reuse the existing `[[patch]]` merge pipeline.
3. **Open extensibility** — third parties contribute new content kinds, CLI
   subcommands, or runtime services as Python entry-point plugins. Core stays
   stable; ecosystem grows out of tree.
4. **Crash-safe** — apply transaction is atomic; a boot canary detects a crashy
   mod and bisects on next launch; per-mod Lua errors never escape `pcall`.
5. **Programmer freedom** — `R.call` (53k fns), `R.hook` (after TLS injection
   lands), `R.read/write` memory primitives, event bus, scheduler.
6. **Survives game updates** — pattern-resolver already byte-pattern not VA;
   manifests declare `target_game_build`; mods address fns by name; schemas
   are versioned and auto-migrated.
7. **Localization, config, inter-mod APIs** — first-class. Wired through the
   SDK runtime, not bolted on per mod.
8. **Distribution** — open spec (`repo.json`), SHA256 + optional Ed25519
   signature. No central host required.

## Module map

```
src/rsmm/sdk/
  __init__.py         # public Python surface: `from rsmm import sdk; sdk.Mod(...)`
  api.py              # @sdk_export + version pin (rsmm.sdk.api.v1)
  health.py           # apply-canary + crash-history bisect
  transaction.py      # stage -> swap install pipeline
  config.py           # schema-driven per-mod config, generates UI rows
  i18n.py             # lang/<locale>.toml merge into text banks
  content.py          # R.content.register(kind, def) facade
  plugins.py          # entry-point discovery, version-gated load
  repo.py             # repo.json schema + sign/verify (Ed25519)
  versioning.py       # game-build hash check + schema migrations
  kinds/              # one module per content kind
    items.py          # magical objects
    enemies.py
    bosses.py
    maps.py
    heroes.py
    _schema_mining.py # Ghidra-driven class-cohort schema extractor
```

Lua side (loader DLL):

```
src/loader/lib/
  rsmm.lua            # R = require "rsmm" — the core surface (R.on/R.emit,
                      #   R.entity/R.combat/R.stat/R.xp, R.give, R.item,
                      #   R.talent, R.options, R.hook, R.kv, R.debug,
                      #   R.serialize, R.defs, R.rtti) and it merges the
                      #   submodules below onto R
  engine_gen.lua      # GENERATED: semantic name -> {pattern, offset, sig}
src/loader/lua/
  rsmm/health.lua     # R.health (crash count, last_error, checkpoint)
  rsmm/config.lua     # R.config.get/set/on_change
  rsmm/i18n.lua       # R.i18n.t
  rsmm/api.lua        # R.api.expose/require
  rsmm/schedule.lua   # R.schedule.{next_frame, after, next_main, after_main}
  rsmm/exp.lua        # R.exp — record a playtest verdict (read with `rsmm exp`)
  rsmm/poi.lua        # R.poi.on_generated — observe map generation (probe)
  rsmm/spawn.lua      # R.spawn.{probe, at, near, copy} — instantiate an entity (experimental)
```

Both trees are merged into `<game>/rsmm/lib/` by `rsmm install-loader`, which
is why `require "rsmm"` and `require "rsmm.schedule"` both resolve in-game.

`rsmm.lua` is rebuilt by `rsmm build` from the Python side so the Lua API
declarations stay in lockstep with the Python registrations.

How an authored mod becomes installed bytes (declarative all the way down —
no per-mod scripts):

```mermaid
flowchart TD
    M["sdk.Mod(...)<br/>item / enemy / texture / model / tag"] --> R["content.register<br/>+ staged assets"]
    R --> K["kinds/*<br/>clone vanilla base"]
    K --> C["engine cook<br/>(magic_item_cook, geometry_cook, …)"]
    C --> T["transaction<br/>stage → atomic swap"]
    T --> A["rsmm apply<br/>back up + install cooked files"]
    A --> G["Game reads<br/>_Cooking/&lt;encoded&gt;"]
    L["Lua mods"] -.->|"R.on / R.call (loader DLL)"| G
```

## Manifest v2

```toml
[mod]
id = "MyMod"
name = "My Mod"
version = "1.2.3"             # semver
author = "Me"
description = "..."
enabled = true

sdk_version = ">=3.0,<4"      # required SDK API
target_game_build = "1.2.3"   # what game version it was built for
load_order = 100              # tiebreak ordering
priority   = 0

[dependencies]
otheritempack = ">=1.0"

[provides]
api = "myapi"                 # what `R.api.require("myapi")` resolves to

[[patch]]                     # existing field-merge support
...

[[content]]                   # NEW: declarative content registration
kind   = "item"               # one of: item, enemy, boss, map, hero
id     = "FrostBlade"
source = "content/frost_blade.toml"
```

## Apply transaction

`rsmm apply` becomes two-phase:

1. **Stage**: every write goes to `<cooking>/.rsmm_stage/<encoded>`. Backups
   created next to originals as before. Nothing in `_Cooking/` proper is
   touched yet.
2. **Commit**: atomic rename of staged files into place (POSIX `os.rename`,
   `MoveFileExW` w/ `MOVEFILE_REPLACE_EXISTING` on Windows). On the first
   error mid-commit, every successful rename is rolled back from `.rsmm.bak`.

State writes are also staged. `.rsmm_state.json` is written to
`.rsmm_state.json.tmp` then renamed.

Power-loss safety: `rsmm apply` is restartable — staged-but-uncommitted
files are detected at startup and either committed (if a `COMMIT` marker
exists) or discarded.

## Boot canary

The loader opens a canary in `<game>/mods/_health.json` before any mod code
runs, and stamps a `step` as boot advances:

```
boot -> per_mod:A -> post_init:A -> per_mod:B -> ... -> ready -> boot_ok
```

```json
{
  "version": 1,
  "canary": { "open": true, "step": "per_mod:A", "session": "a3f1" },
  "mods": { "A": { "crashes": 1, "last_error": "...", "disabled": false } }
}
```

The canary is closed (`open: false`) once the tick pump has run for ~2 s past
`ready` — i.e. the game demonstrably survived load. If the NEXT launch finds
it still open, the previous run died at the recorded step, so a crash inside
`per_mod:X` is attributed to mod X and counted.

Three **consecutive** failed boots and the mod is skipped at load
(`disabled: true` with a reason) — you can't reach an in-game UI to turn off
a mod that bricks startup. Any launch that boots successfully resets the
counters. To re-enable, clear the flag in `mods/_health.json`.

## `R.health` API

```lua
R.health.crash_count("modid")   -- consecutive failed boots (default: this mod)
R.health.last_error("modid")    -- string|nil
R.health.disable("modid", "reason")
R.health.checkpoint("step")     -- stamp your own sub-step into the canary
```

## Config

`mods/<id>/config_schema.toml`:

```toml
[fields.damage_mult]
type    = "float"
min     = 0.1
max     = 10.0
default = 1.0
label   = "Damage multiplier"

[fields.enable_effect]
type    = "bool"
default = true
```

`mods/<id>/config.toml` is written by the user through the desktop app's
config panel, or from a shell with
`rsmm json config set <id> '{"damage_mult": 2.5}'` (replaces the stored
values; `rsmm json config get <id>` reads them). SDK API:

```lua
local cfg = R.config              -- bound to the calling mod
local mult = cfg.get("damage_mult")
cfg.on_change("damage_mult", function(new, old) ... end)
```

Validation errors at write-time → rejected with explicit message.

## i18n

`mods/<id>/lang/<locale>.toml` (a `.json` object of the same key/value pairs
works too):

```toml
[strings]
title  = "Frost Blade"
desc   = "An icy weapon."
```

Locales: `EN, JA, KO, RU, ES, DE, PL, FR, IT, PT-BR, ZH-S, ZH-T` (game's
existing 12 user locales + the `RAW` QA pseudo-locale).

At apply time, RSMM merges strings into per-locale text-bank overrides,
keys namespaced as `RSMM_<modid>_<key>`.

Lua API:

```lua
R.i18n.t("title")               -- "Frost Blade"
R.i18n.t("hello", {name="X"})   -- substitution: "Hello, X"
```

Missing locale → fall back to `EN`. Missing key in `EN` → return the key
literally and log warning.

## Inter-mod API

```lua
-- producer
R.api.expose({
  spawn_item = function(id, pos) ... end,
  version    = "1.0.0",
})

-- consumer
local items = R.api.require("itempack", ">=1.0")
items.spawn_item("FrostBlade", player.pos)
```

`expose` is implicitly namespaced to the calling mod's `id` (override with
`api_name`). `require` checks the producer's `version` against the semver
spec and returns a read-only proxy that `pcall`s every call, so a producer
failure surfaces as an error in the consumer instead of taking it down.

**Calls cross a state boundary.** Every mod runs in its own `lua_State`, so
the proxy marshals through the loader rather than handing over a Lua table
directly. Arguments and return values must therefore be **data** — `nil`,
boolean, number, string, or tables of those. Passing a function (a callback)
is rejected with an error; use an event (`R.on`) for producer → consumer
signalling.

```lua
R.api.has("itempack")       -- bool
R.api.version("itempack")   -- "1.0.0" | nil
R.api.list()                -- { itempack = { mod_id = ..., version = ... } }
```

### Signalling: `R.emit`

`R.api` is the *call* direction. For the other direction — "something
happened, whoever cares should react" — emit an event; every mod's state
receives it.

```lua
-- producer
R.emit("itempack:crafted", { id = "FrostBlade", tier = 3 })

-- any consumer
R.on("itempack:crafted", function(ev)
  R.log(ev.from, "crafted", ev.id)     -- ev.from = the producer's mod id
end)
```

Payloads must be data (they are marshalled between states). The loader
stamps `event`, `source = "mod"` and `from = <mod id>` onto every payload,
**overwriting** whatever you set — that is what stops a mod from
impersonating the gameplay bus, whose `source` field is how `R.schedule`'s
main-thread pump and `R.stat`'s re-assert know they are running on the
game's own thread. For the same reason the loader's own names are refused:
the `gameplay:` / `ui:` / `rsmm:` prefixes and the lifecycle events
(`setup`, `ready`, `tick`, `exit`). Prefix yours with your mod id.

## Plugin registry

Third-party Python packages can register SDK extensions via PEP-621
entry points:

```toml
# their pyproject.toml
[project.entry-points."rsmm.plugins"]
my_pack = "my_pack.entry:register"
```

`register(api)` is called with an `rsmm.sdk.api.v1` namespace and may:

* declare new `R.content` kinds (via `api.content.register_kind(...)`),
* add CLI subcommands (`api.cli.register(name, fn)`),
* expose Lua-side modules (file copied to the loader's `lua/` dir).

Discovery: `importlib.metadata.entry_points(group="rsmm.plugins")`.
Each plugin declares `requires_api = ">=1.x,<2"`; unsatisfied plugins
are skipped with a warning.

## Content kinds

`R.content.register(kind, def)` (Lua) and `rsmm.sdk.content.register(...)`
(Python) both funnel into one Python pipeline. Per kind:

* `items` — magical-object registry entry + entity cooked file + text-bank
  keys + icon texture override.
* `enemies` — entity clone of a vanilla base enemy + AI controller + stat
  globals + spawn-table entry.
* `bosses` — same as enemies + boss-fight controller + arena patch.
* `maps` — biome entry into level list + tile/spawn-weight patch.
* `heroes` — entity + portraits + power tree + i18n keys + character-select
  slot patch.

Each kind module owns:

1. Its template `.gen` byte slice (extracted from a vanilla cooked file at
   build time, cached under `data/templates/<kind>/`).
2. A field-by-field patcher (id, name, stats, icon path, …) that emits a
   modified `.gen`.
3. The reverse-translation back into a decoded `mods/_merged/assets/...`
   tree consumed by `apply_mods.py`.

## Schema mining

`src/rsmm/sdk/kinds/_schema_mining.py` drives a Ghidra-headless pipeline:

1. For each class involved (e.g. `oCEntityCpntMagicalObjectSettings`),
   bucket every vanilla cooked file by body size and call `class_diff` to
   identify field offsets.
2. Cross-reference with strings from `docs/_re/out/strings.json` to label
   text-bank-key offsets.
3. Emit `data/schemas/<class>.json` consumed by `_schema_mining.encode()`.

This is an empirical RE task; it lands kind by kind. v3 ships with items
first, then enemies; bosses/maps/heroes are template-clone-only until
their schemas are mined.

## Distribution (`repo.json`)

A mod-repo index file any host can publish:

```json
{
  "schema": "rsmm.repo.v1",
  "name": "Ovilli's mods",
  "updated_at": "2026-05-19T00:00:00Z",
  "mods": [
    {
      "id": "FrostBlade",
      "version": "1.2.3",
      "sdk_version": ">=3.0,<4",
      "target_game_build": "1.2.3",
      "url": "https://example.com/FrostBlade-1.2.3.zip",
      "sha256": "...",
      "size": 12345,
      "sig": "...",          // optional Ed25519, base64
      "pubkey_id": "ovilli"  // matches a key in user's ~/.rsmm/keys/
    }
  ]
}
```

CLI:

```sh
rsmm repo add https://example.com/repo.json
rsmm install FrostBlade            # resolves to one of the registered repos
rsmm pack MyMod --sign keys/me     # writes dist/MyMod-1.2.3.zip + .sig
rsmm verify dist/FrostBlade.zip    # SHA256 + sig vs ~/.rsmm/keys/
```

Trust model:

* Unsigned: install proceeds with `WARN unsigned mod`.
* Signed by an unknown key: install proceeds with `WARN unknown signer
  (pubkey_id=...). Trust? [y/N]`.
* Signed by a known + trusted key: silent install.

No revocation list in v3 (out of scope). Users can hand-delete keys from
`~/.rsmm/keys/`.

## TLS-callback DLL injection (dropped)

The original plan was to install MinHook from a `PIMAGE_TLS_CALLBACK` inside
`winhttp.dll`, which runs before the EXE's `_DllMainCRTStartup`, so patches
would land ahead of an anti-tamper integrity sweep.

It was never needed. [The protector
teardown](/reverse-engineering/protector/) established that the AT is a
one-shot unpacker with no runtime integrity monitor, so hooks installed from
the ordinary loader thread are never re-checked. The scaffold sat behind
`RSMM_TLS_HOOK=1` for a year doing nothing but calling `MH_Initialize`
early, and its "queue pending hooks" half was an empty stub — so it was
removed. `R.hook` works from the normal `DllMain` path.

## Versioning + game updates

* Loader writes the running EXE's SHA256 to
  `<cooking>/.rsmm_game_build.json` after a successful boot. Next apply
  compares — mismatch → warn + soft-disable mods that use raw VAs.
* `rsmm doctor` flags mods whose `target_game_build` differs from the
  current `.rsmm_game_build.json`.
* Each SDK-managed content def carries `schema_version`. On schema bump,
  migrations under `src/rsmm/sdk/kinds/<kind>/migrations/<from>_to_<to>.py`
  run at build time.

## Open work

* Schema mining for non-item kinds. Items first, then enemies, then the
  rest.
* TLS-callback hook reliability under Proton + Wine.
* `rsmm safe-mode --bisect` driver.
* In-game config panel (loader-side ImGui).
* Web GUI updates to surface health + config + i18n.

## Migration

* `manifest.toml` v1 still parses; v2 fields are all optional with sane
  defaults. No mod break.
* `apply_mods.py` keeps the same CLI surface; the staging dir is invisible
  to users.
* `R.hook` exposes "not supported" today and silently upgrades when
  TLS injection lands.

---

# Talent modding, step by step

> A beginner's guide to changing a hero's talents, from their numbers to their names and descriptions.

Source: https://docs.rsmm.me/guides/talent-tutorial/

import { Steps, Tabs, TabItem, Aside, LinkCard, CardGrid } from '@astrojs/starlight/components';

This guide takes you from nothing to a working talent mod. You do not need to
know how to program. You will copy some commands, fill in one text file, and
check the result in the game.

We use one example all the way through: **Ice Shield**, a Defense talent of
The Snow Queen. By the end of the guide it will:

- be called **Glacier Shield**,
- give a stronger shield,
- last 9 seconds instead of 6.

The same steps work for any talent of any hero. Only the names change.

## What you can and cannot change

| You want to… | Possible? | Step |
|---|---|---|
| Change a number that is the same at every rarity (a duration, a count, a cooldown) | Yes | [Step 5](#step-5-change-a-number-that-is-the-same-at-every-rarity) |
| Change a number that is different for each rarity | Yes | [Step 6](#step-6-change-a-number-that-depends-on-rarity) |
| Rename a talent or rewrite its description | Yes | [Step 7](#step-7-change-the-name-and-the-description) |
| Give a talent a new icon | Yes | [Step 7](#step-7-change-the-name-and-the-description) |
| Make a talent do something completely different | Only for experienced modders | [Going further](#going-further) |
| Add a brand-new talent next to the existing ones | **No.** Every hero has a fixed set of talent slots, and adding one breaks the hero. | — |

## Words used on this page

| Word | Meaning |
|---|---|
| **Talent** | A card you pick when you level up. The game's files call talents **skills**, so you will see both words. |
| **Rarity** | Common, Rare, Epic or Legendary. Many talent numbers are different for each rarity. |
| **Mod** | A folder that holds one text file, `manifest.toml`, which describes your changes. |
| **Terminal** | The window where you type commands. On Windows it is **Command Prompt** or **PowerShell**. On Linux it is called **Terminal**. |
| **Apply** | The moment RSMM copies your changes into the game. |
| **RSMM** | Ravenswatch Mod Manager, the tool this site documents. |

## Step 1: Set up once

You need three things installed:

- **Ravenswatch** (from Steam)
- **Python** 3.11 or newer ([python.org](https://www.python.org/downloads/)). On Windows, tick **"Add python.exe to PATH"** in the installer.
- **Git** ([git-scm.com](https://git-scm.com/downloads))

<Aside type="caution" title="The desktop app alone is not enough">
Talent mods need the full RSMM downloaded from GitHub. The tools that read talent
files are part of RSMM's source code and are not included in the desktop app.
</Aside>

Open a terminal and paste these lines one at a time:

<Tabs syncKey="os">
  <TabItem label="Windows">
    ```cmd
    git clone https://github.com/Ovilli/RavenswatchModManager.git
    cd RavenswatchModManager
    python -m venv venv
    venv\Scripts\activate
    pip install -e .
    pip install texture2ddecoder Pillow
    rsmm doctor
    ```
  </TabItem>
  <TabItem label="Linux">
    ```sh
    git clone https://github.com/Ovilli/RavenswatchModManager.git
    cd RavenswatchModManager
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -e .
    pip install texture2ddecoder Pillow
    rsmm doctor
    ```
  </TabItem>
</Tabs>

The second `pip install` line adds the two packages the next step needs to read
the game's files.

`rsmm doctor` checks your setup and tells you if something is missing, for
example if it cannot find the game. A warning about the loader is fine for now:
you only need it in Step 10.

<Aside type="tip" title="Every time you open a new terminal">
Go into the `RavenswatchModManager` folder and run the activate line again:
`venv\Scripts\activate` on Windows, `source .venv/bin/activate` on Linux. If a
command says `rsmm` or `python` is not found, this is almost always the reason.
</Aside>

Next, make a readable copy of the game's hero files. RSMM reads talents from
this copy, which it keeps in `data/uncooked/`. Run both lines:

```sh
python scripts/extract_uncooked.py --filter "EntitySettings\Heroes"
python scripts/extract_uncooked.py --filter "Definitions\Heroes"
```

Type the backslash `\` exactly as shown, on Linux too. If the script says it
cannot find `_Cooking`, it could not find your game. Add
`--game-dir "C:\path\to\Ravenswatch"` to the end of both lines, using the
folder that contains `Ravenswatch.exe`.

<Aside type="note">
Run these two lines again after every game update, so your copy matches the game.
</Aside>

To check that it worked, run:

```sh
rsmm talents
```

You should see a list of heroes, each with a count of values. If you see that
list, setup is finished.

## Step 2: Find your talent's names

A talent has an English name on its card, and different names inside the game
files. For example, Scarlet's **Short Wick** is called `Secondary Quick Bombs`
inside the files. You need the file names.

Open the **[Talent name lookup](/reference/talent-names/)** page, find your hero,
and find your talent in the table. Write down three things:

| What | Ice Shield example | Used for |
|---|---|---|
| **Hero spelling** (at the top of the hero's section) | `Snow_Queen` | Telling RSMM which hero |
| **Search word** | `Defense Shield` | Finding the talent's numbers |
| **Rename with** | `Skill_Defense_Shield` | Changing the name or description |

## Step 3: Look inside the talent

This step uses a small helper script that shows everything about one talent:
its text and all its numbers.

Create a new file called `talent_info.py` **directly in the `RavenswatchModManager`
folder**, next to `README.md`. Open it in any text editor (Notepad works), paste
the code below and save.

<Aside type="caution">
Do not put this file inside your mod's folder. Mods must not contain Python
files, and RSMM's checks reject a mod that does.
</Aside>

```python title="talent_info.py"
# talent_info.py - print everything you need to mod one talent.
#
#   python talent_info.py <Hero> "<Search word>" <Rename with>
#
# All three values come from the Talent name lookup page.
import sys
from pathlib import Path

from rsmm.engine import talent_values as TV
from rsmm.engine.text_patches import _pristine, lang_path_for, parse_text_file
from rsmm.sdk.kinds.skills import _install_bank

if len(sys.argv) != 4:
    sys.exit('Usage: python talent_info.py <Hero> "<Search word>" <Rename with>')
hero, word, key = sys.argv[1], sys.argv[2].lower(), sys.argv[3]

folder = Path("data/uncooked/EntitySettings/Heroes") / f"Hero_{hero}"
if not folder.is_dir():
    sys.exit(f"No folder {folder}\nCheck the hero spelling, or extract the game files first.")

# 1. The text on the card, exactly as the game stores it.
bank = _install_bank(hero)
if bank is None:
    print("(Could not find the game install, so the card text is not shown.)")
else:
    keys = parse_text_file(_pristine(bank[0])).entries
    english = parse_text_file(_pristine(lang_path_for(bank[0], "EN"))).entries
    text = dict(zip(keys, english))
    for suffix in ("_Name", "_Title", "_Desc"):
        if key + suffix in text:
            print(f"{suffix[1:].upper():<6} {text[key + suffix]}")

# 2. Every number that belongs to the talent.
for f in sorted(folder.glob("*.entity.ot.EntitySettingsResource.gen")):
    data = f.read_bytes()
    lines = []
    plain = TV.list_talent_values(data)
    for v in plain:
        if word in v.label.lower():
            lock = "   <- LOCKED (read 'shadowed' in the tutorial)" if v.is_overridden else ""
            lines.append(f"  ONE NUMBER  {v.label} = {v.value:g}{lock}")
    labels = {v.label for v in plain}
    selectors = {t for _, t in TV._iter_lstrings(data)
                 if word in t.lower() and t.endswith("Selector") and not t.startswith("[")}
    for name in sorted(selectors - labels):
        try:
            unions = TV.list_union_values(data, name)
        except ValueError:
            continue
        nums = [f"index {i} = {v:g}" for i, (_, v, kind) in enumerate(unions) if kind in (0, 1)]
        if nums:
            lines.append(f"  PER RARITY  {name}:  " + ", ".join(nums))
    if lines:
        print(f'\nfile = "{f.name.split(".entity.")[0]}.entity"')
        print("\n".join(lines))
```

Now run it with the three things you wrote down. Put the search word in quotes,
because it contains a space:

```sh
python talent_info.py Snow_Queen "Defense Shield" Skill_Defense_Shield
```

For Ice Shield it prints:

```text
NAME   Ice Shield
DESC   • #DEFENSE@ grants a &{0}~ SHIELD to {1} and all Heroes passed for #{2}@ seconds

file = "Hero_Snow_Queen.entity"
  ONE NUMBER  Skill Defense Shield Duration = 6
  PER RARITY  Skill Defense Shield Value Selector:  index 1 = 2.8, index 3 = 2.4, index 5 = 2, index 7 = 1.6
```

Here is what each line means:

| Line | Meaning |
|---|---|
| `NAME` | The talent's name. |
| `DESC` | The description, exactly as the game stores it. The `{0}`, `{1}` and `{2}` are gaps. The game fills them in with numbers when it draws the card. |
| `file = "..."` | The hero file that holds these numbers. You will copy this whole line into your mod. |
| `ONE NUMBER` | A number that is the same at every rarity. Here the shield lasts **6** seconds. It is the `{2}` in `for #{2}@ seconds`, so when you change it the card shows the new number by itself. |
| `PER RARITY` | A list with one number per rarity. Here it is the shield's strength. The card may show it in a different form, for example as a percentage, but this is the number behind it. |

The `index` tells you which rarity a number belongs to:

| index | Rarity |
|---|---|
| 1 | Legendary |
| 3 | Epic |
| 5 | Rare |
| 7 | Common |

In the game's files the biggest number almost always sits at index 1, like the
2.8 here. If you are unsure, test it in the game ([Step 10](#step-10-optional-get-the-talent-at-the-start-of-every-run)).

**If the helper prints no numbers**, try a shorter search word. For example, use
`Shield` instead of `Defense Shield`. A shorter word also shows numbers from
other talents, so read the names carefully.

**If a line ends in `<- LOCKED`**, that number is controlled by a per-rarity list
somewhere else, and changing it does nothing. Change the `PER RARITY` numbers
instead. The [Troubleshooting](#troubleshooting) section explains this.

## Step 4: Create your mod

Inside the `RavenswatchModManager` folder there is a folder called `mods`.
Create a new folder inside it called `glacier-shield`. Inside that, create a
file called `manifest.toml`:

```text
RavenswatchModManager/
└── mods/
    └── glacier-shield/
        └── manifest.toml
```

Paste this into `manifest.toml`:

```toml title="mods/glacier-shield/manifest.toml"
[mod]
id          = "glacier-shield"
name        = "Glacier Shield"
version     = "0.1.0"
author      = "YourName"
description = "The Snow Queen's Ice Shield becomes Glacier Shield: stronger, and it lasts longer."
license     = "MIT"
sdk_version = ">=3.0,<4"
enabled     = true
experimental = true
tags        = ["talents", "snow-queen"]
multiplayer_scope = "deterministic-shared"
```

What the lines mean:

| Line | Meaning |
|---|---|
| `id` | Your mod's name inside RSMM. It must match the folder name. Use lowercase letters and dashes only. |
| `name`, `description` | What people see in the mod list. |
| `author` | Your name. |
| `enabled = true` | RSMM installs this mod when you apply. |
| `experimental = true` | Needed because Step 7 renames a talent. See the note below. |
| `multiplayer_scope = "deterministic-shared"` | The mod changes the game, so everyone in a party needs it. See [Online play](/guides/modding/#online-play-client-only-and-gameplay-mods). |

<Aside type="note" title="Why experimental?">
Renaming uses the `skill` content type. As a whole, RSMM rates that type
experimental, because some of its other modes are unproven. The renaming mode
used in this guide has been tested in the game. If your mod only changes
numbers, you can leave `experimental = true` out.
</Aside>

A few rules for this kind of file (it is called TOML):

- Text goes in `"double quotes"`. Numbers do not.
- Put each setting on its own line.
- A `#` starts a comment. Everything after it on that line is ignored.

## Step 5: Change a number that is the same at every rarity

We make the shield last 9 seconds instead of 6. Add this to the end of
`manifest.toml`:

```toml
[[content]]
kind = "talent"
id   = "ice_shield_duration"
hero = "Snow_Queen"
file = "Hero_Snow_Queen.entity"
value_patches = [
  { label = "Skill Defense Shield Duration", old = 6.0, new = 9.0 },
]
```

Line by line:

| Line | What to write |
|---|---|
| `[[content]]` | Starts one change. A mod can have as many as you like. |
| `kind = "talent"` | This change edits talent numbers. |
| `id` | A name you make up for this change. Use only letters, numbers and underscores `_`, with no spaces and no dashes. Every change in the mod needs its own `id`. |
| `hero` | The **Hero spelling** from Step 2. For `kind = "talent"`, use the first spelling. |
| `file` | Copy the `file = ...` line from the helper's output. |
| `label` | The name after `ONE NUMBER`, copied exactly, including capital letters. |
| `old` | The number the helper printed. This is a safety check: if the game file holds a different number, RSMM stops and tells you instead of changing the wrong thing. |
| `new` | Your new number. |

To change several numbers at once, add more lines between the square brackets.
Separate them with commas:

```toml
value_patches = [
  { label = "First Label",  old = 6.0, new = 9.0 },
  { label = "Second Label", old = 3.0, new = 4.0 },
]
```

## Step 6: Change a number that depends on rarity

Now we make the shield stronger at every rarity. Add another block:

```toml
[[content]]
kind = "talent"
id   = "ice_shield_strength"
hero = "Snow_Queen"
file = "Hero_Snow_Queen.entity"
union_patches = [
  { label = "Skill Defense Shield Value Selector", index = 7, old = 1.6, new = 2.0 },  # Common
  { label = "Skill Defense Shield Value Selector", index = 5, old = 2.0, new = 2.6 },  # Rare
  { label = "Skill Defense Shield Value Selector", index = 3, old = 2.4, new = 3.2 },  # Epic
  { label = "Skill Defense Shield Value Selector", index = 1, old = 2.8, new = 4.0 },  # Legendary
]
```

This works like Step 5, with two differences:

- The list is called `union_patches` instead of `value_patches`.
- Each line has an `index`, which picks the rarity. Copy it from the helper's
  `PER RARITY` line.

Only include the rarities you want to change. One line on its own is fine.

<Aside type="tip">
Steps 5 and 6 edit the same hero file, so you could put `value_patches` and
`union_patches` in one block. Separate blocks are easier to read, and RSMM
combines them correctly.
</Aside>

## Step 7: Change the name and the description

Add one more block:

```toml
[[content]]
kind   = "skill"
id     = "ice_shield_text"
hero   = "Snow_Queen"
mode   = "relabel"
source = "Skill_Defense_Shield"
name        = "Glacier Shield"
description = "• #DEFENSE@ grants a &{0}~ SHIELD to {1} and all Heroes passed for #{2}@ seconds"
```

| Line | What to write |
|---|---|
| `kind = "skill"` | This change edits talent text. |
| `hero` | The **second** hero spelling from the lookup page. It differs only for Sun Wukong (`Sun_Wukong` here, `SunWukong` for `kind = "talent"`). |
| `mode = "relabel"` | Change the text of an existing talent. Always use this mode. |
| `source` | The **Rename with** value from Step 2. Do not use the English name. |
| `name` | The new name. Leave this line out to keep the original name. |
| `description` | The new description. Leave this line out to keep the original. |

### How to write a description

Start from the `DESC` line the helper printed, and change the words around the
codes.

**Keep the number gaps** (`{0}`, `{1}`, `{2}`, …). The game fills in each gap with
a number from the talent. You can move a gap or leave one out, but you cannot
add a new one. If the original description stops at `{2}`, a `{3}` shows up
empty.

The codes the game uses for formatting:

| Code | Result | Example |
|---|---|---|
| `#…@` | Highlighted text, used for ability names and fixed numbers | `#DEFENSE@`, `#{2}@` |
| `&…~` | A number that grows with rarity (shown in green) | `&{0}~` |
| `$…*` | A downside | `${0}%*` |
| `• ` | A bullet point at the start of a line | `• #POWER@ deals more damage` |
| `\n` | A new line | `"• First line\n• Second line"` |

<Aside type="caution" title="Good to know">
- Your text replaces the talent's text in **every language**. A player with the
  game in German sees your English text.
- **Juliet's talent names cannot be changed**, because they are stored
  differently. Her descriptions can be. The lookup page marks the few other
  talents with the same limit as "description only".
</Aside>

### A new icon (optional)

Put a PNG image in your mod folder, for example
`mods/glacier-shield/art/glacier-shield.png`. Then add this line to the same
`kind = "skill"` block:

```toml
icon = "art/glacier-shield.png"
```

Use a square image. The game's own talent icons are 128 × 128 pixels.

## Step 8: Check the mod

Run:

```sh
rsmm lint glacier-shield
```

For this guide's mod, you should see:

```text
  [WARN] glacier-shield: content kind 'skill' is 'guess' — shipping under experimental opt-in (may not work in-game).
  [OK]   glacier-shield  (raw=0 patches=0 content=3 scope=deterministic-shared)
```

That warning is expected. It is the "experimental" note from Step 4. A line that
says `[FAIL]` is a real problem: read it, fix the file and run `lint` again.

## Step 9: Put it into the game

**Close Ravenswatch first.** Then run:

```sh
rsmm restore --all
rsmm apply
```

`restore --all` puts all the game's original files back, and `apply` then
installs every enabled mod fresh. Always run both. If you only run `apply`,
parts of an older version of your mod can stay behind.

While `apply` runs, look for your mod in the output:

| You see | Meaning |
|---|---|
| `[content] glacier-shield: emitted 15 file(s)` | It worked. (The count is 1 hero file + 1 hero file + 13 language files.) |
| `[content] glacier-shield: emit failed: ...` | Your mod was **not** installed. The text after `failed:` says why. See [Troubleshooting](#troubleshooting). |

`apply` keeps going after a failed mod so that other mods still install. **Scroll
up and check.** Missing an error here is the most common reason a mod "does
nothing".

Now start the game and play The Snow Queen. When a level-up offers Ice Shield,
the card should say **Glacier Shield** and show the new numbers.

## Step 10 (optional): Get the talent at the start of every run

Waiting for the game to offer your talent can take many runs. A small test file
can give you the talent automatically at the start of each run.

This uses the **RSMM loader**, a file RSMM adds to the game so mods can run Lua
scripts. Set it up once (and again after every `restore --all`, which removes it):

<Tabs syncKey="os">
  <TabItem label="Windows">
    ```cmd
    rsmm install-loader
    rsmm doctor
    ```
  </TabItem>
  <TabItem label="Linux">
    Close Steam first, then:
    ```sh
    rsmm install-loader
    rsmm run --set-launch-options --no-launch
    rsmm doctor
    ```
    The second command sets Ravenswatch's Steam launch options. Without them, the game on Linux never loads the loader.
  </TabItem>
</Tabs>

The first time, `install-loader` downloads the ready-made loader for you, so you
do not need to build anything. Close the game before you run it.

Then create a file called `init.lua` in your mod folder, next to `manifest.toml`:

```lua title="mods/glacier-shield/init.lua"
-- TESTING ONLY. Gives you the talent at the start of every run.
-- Delete this file before you share or publish the mod.
local R = require "rsmm"

local TALENT = "Defense Shield"   -- the "Search word" from the lookup page
local RARITY = 0                  -- 0 Common, 1 Rare, 2 Epic, 3 Legendary

local done = false
R.on("run:start", function() done = false end)
R.schedule.every(3, function()
    if done or not R.entity.ready() then return end
    if #R.talent.controllers() == 0 then return end
    done = true
    R.talent.dump()
    R.talent.grant(TALENT, RARITY)
end)
```

Start a run with the right hero. After a few seconds you have the talent. To
test a different rarity, change `RARITY`, close the game, and run
`rsmm restore --all`, `rsmm apply` and `rsmm install-loader` again.

To see what happened, run:

```sh
rsmm log --grep talent
```

| You see | Meaning |
|---|---|
| `[rsmm.talent] granted ...` | It worked. |
| `grant refused: no talent matches ...` | The name in `TALENT` did not match. The lines above it list the name of every talent the hero has. Copy a part of the right name into `TALENT`. |
| `grant refused: all ten talent slots are full` | Start a new run. |

<Aside type="danger" title="Remove init.lua before sharing">
For anyone else, this file is a cheat that hands out a free talent. Delete it
before you pack or publish the mod.
</Aside>

## Step 11: Share your mod

<Steps>
1. Delete `init.lua` if you made one.
2. Run `rsmm lint glacier-shield` and fix any `[FAIL]`.
3. Run `rsmm pack glacier-shield`. This creates `dist/glacier-shield.zip`.
4. Upload the zip in the desktop app's **Registry** tab, or run
   `rsmm publish glacier-shield` (the first time, run `rsmm publish login`).
</Steps>

## Undo everything

To remove every mod and return the game to normal, close the game and run:

```sh
rsmm restore --all
```

To turn off only this mod, run:

```sh
rsmm disable glacier-shield
rsmm restore --all
rsmm apply
```

## The finished mod

Here is the complete `manifest.toml` from this guide:

```toml title="mods/glacier-shield/manifest.toml"
[mod]
id          = "glacier-shield"
name        = "Glacier Shield"
version     = "0.1.0"
author      = "YourName"
description = "The Snow Queen's Ice Shield becomes Glacier Shield: stronger, and it lasts longer."
license     = "MIT"
sdk_version = ">=3.0,<4"
enabled     = true
experimental = true
tags        = ["talents", "snow-queen"]
multiplayer_scope = "deterministic-shared"

# Lasts 9 seconds instead of 6.
[[content]]
kind = "talent"
id   = "ice_shield_duration"
hero = "Snow_Queen"
file = "Hero_Snow_Queen.entity"
value_patches = [
  { label = "Skill Defense Shield Duration", old = 6.0, new = 9.0 },
]

# A stronger shield at every rarity.
[[content]]
kind = "talent"
id   = "ice_shield_strength"
hero = "Snow_Queen"
file = "Hero_Snow_Queen.entity"
union_patches = [
  { label = "Skill Defense Shield Value Selector", index = 7, old = 1.6, new = 2.0 },  # Common
  { label = "Skill Defense Shield Value Selector", index = 5, old = 2.0, new = 2.6 },  # Rare
  { label = "Skill Defense Shield Value Selector", index = 3, old = 2.4, new = 3.2 },  # Epic
  { label = "Skill Defense Shield Value Selector", index = 1, old = 2.8, new = 4.0 },  # Legendary
]

# The new name. The description keeps the original's number gaps.
[[content]]
kind   = "skill"
id     = "ice_shield_text"
hero   = "Snow_Queen"
mode   = "relabel"
source = "Skill_Defense_Shield"
name        = "Glacier Shield"
description = "• #DEFENSE@ grants a &{0}~ SHIELD to {1} and all Heroes passed for #{2}@ seconds"
```

## Troubleshooting

Find the message you got in the left column. The messages below are exactly what
RSMM prints, with this guide's example values.

| Message | What it means | How to fix it |
|---|---|---|
| `current value 6.0 != expected 5.0` | The `old` number does not match the game file. | Copy the number from the helper's output. After a game update, run the helper again, because the number may have changed. |
| `value label 'Skill Defense Shield Duratoin' not found in Snow_Queen's entity files` | The `label` has a typo. | Copy it exactly from the helper, including capital letters. |
| `no vanilla hero dir for 'SnowQueen' under EntitySettings/Heroes (is data/uncooked present?)` | The hero spelling is wrong, or you skipped the extraction in Step 1. | Use the spelling from the lookup page, and run the Step 1 extraction. |
| `id 'ice-shield' must match ^[A-Za-z0-9_]+$` | A block's `id` contains a dash or a space. | Use only letters, numbers and `_`. |
| `skip block missing kind/id` | A `[[content]]` block has no `id` line. | Add one. |
| ``union_patches need `file` to select exactly one entity file (matched 30: ...)`` | The block has no `file` line. | Add the `file = ...` line from the helper. |
| `'Skill Special Marked Value' is shadowed: its value is sourced from a selector/reference ...` | The helper marked this number `LOCKED`. The game ignores it and reads a per-rarity list instead, so changing it would do nothing. | Change the `PER RARITY` numbers with `union_patches` instead. |
| `no text key for 'Ice Shield' — tried Skill_Ice_Shield_Name` | `source` holds the English name. | Use the **Rename with** value from the lookup page. |
| `text key 'Skill_Power_More_Range_Name' not in bank` | This talent's name cannot be changed (all of Juliet's, and a few others). | Remove the `name` line and keep only `description`. |
| `content kind 'skill' is 'guess' ... Set [mod] experimental = true` | The mod renames a talent but has no `experimental = true`. | Add it to the `[mod]` section. |
| `no install text bank for 'Snow_Queen' reachable` | RSMM cannot find your game. | Run `rsmm doctor` and follow what it says. |

**The game shows no change, and there was no error:**

1. Did you close the game before `rsmm apply`?
2. Scroll up in the `apply` output. Does it say `emitted` for your mod, or `failed`?
3. Is `enabled = true` in your manifest? `rsmm list` shows every mod and whether it is on.
4. Did you change a `LOCKED` number? The game ignores those.
5. Did you change the rarity you are actually playing? Check the index table in Step 3.

## Going further

This guide covers the changes that are safe for beginners. Ready to change what a
talent **does**, not just its numbers? The advanced guide shows how to swap the
attack a talent plays, add "if you own this talent" rules, give a talent an extra
stat bonus, and build new effects out of pieces the game already has.

<CardGrid>
  <LinkCard title="Advanced talent modding" href="/guides/talent-tutorial-advanced/" description="Rewire and clone the parts a talent is made of." />
  <LinkCard title="Talent name lookup" href="/reference/talent-names/" description="Every hero's talents with the names a mod needs." />
  <LinkCard title="Custom skills (talents)" href="/guides/custom-skills/" description="The skill type in more depth, including binding behaviour from Lua." />
  <LinkCard title="Authoring mods" href="/guides/modding/" description="The full guide to every kind of mod." />
  <LinkCard title="Troubleshooting" href="/getting-started/troubleshooting/" description="Problems that are not specific to talents." />
</CardGrid>

---

# Advanced talent modding

> Change what a talent does, not just its numbers. Swap attacks, add conditions, add stat bonuses and build new effects.

Source: https://docs.rsmm.me/guides/talent-tutorial-advanced/

import { Steps, Tabs, TabItem, Aside, Badge, LinkCard, CardGrid } from '@astrojs/starlight/components';

The [beginner tutorial](/guides/talent-tutorial/) changes a talent's numbers and
text. This page goes further and changes **what a talent does**. By the end you
will know how to:

- make a talent play a different attack,
- add an "if the player has this talent, do that" rule,
- make a talent switch on a different effect,
- give a talent an extra bonus, such as a shorter cooldown, with a new number on its card,
- build a new "every N attacks" effect out of pieces the game already has.

You still do not write code. Everything is `manifest.toml`, like before. What
changes is that you now need to understand how a talent is put together inside
the game's files, and this page teaches that first.

<Aside type="caution" title="Finish the beginner tutorial first">
This page assumes you already have the setup from
[Step 1](/guides/talent-tutorial/#step-1-set-up-once), the
`talent_info.py` helper from
[Step 3](/guides/talent-tutorial/#step-3-look-inside-the-talent), and the
testing file from
[Step 10](/guides/talent-tutorial/#step-10-optional-get-the-talent-at-the-start-of-every-run).
You will use all three.
</Aside>

## How much has been tested

Some of these techniques are proven in the game. Others build correct files but
have not been played yet. Each recipe carries one of these labels:

| Label | Meaning |
|---|---|
| <Badge text="Tested in game" variant="success" /> | Someone played it, and it did what the recipe says. |
| <Badge text="Partly tested" variant="caution" /> | Part of it was seen working in the game, and part was not checked yet. |
| <Badge text="Not yet tested" variant="danger" /> | RSMM builds it correctly, but nobody has played it yet. |

Every example on this page builds without errors against the current game
files. "Builds" is not the same as "works", which is why the labels exist.

## Before you start: four rules

1. **Change one thing, then test it.** A wrong link does not show an error. The
   talent just stops working, or does something odd. If you change five things
   at once, you cannot tell which one broke it.
2. **Put all changes to one hero file in one mod.** If two separate mods both
   change `Hero_SunWukong.entity`, only one of them ends up in the game. Inside
   one mod, as many `[[content]]` blocks as you like combine correctly.
3. **Never touch your only copy of the game.** `rsmm restore --all` undoes
   everything RSMM did, so run it whenever something looks wrong.
4. **Test with the talent actually owned.** A talent's effect only runs while you
   have the talent. Use the testing file from the beginner tutorial.

## How a talent works inside

A hero file, like `Hero_SunWukong.entity`, is a big collection of small named
**parts**. Each part does one job, and parts point at each other. A talent is not
one part. It is a small chain of them.

Here is Sun Wukong's **Stick Twirl**, the talent that turns an attack right after
a dash into a spinning attack. This is the real chain from the game's files:

```mermaid
flowchart TD
    A["Skill Controller Dash Attack<br/><i>the talent itself</i>"] -->|switches on| B["Skill Dash Attack<br/><i>State</i>"]
    C["Basic Attack Is Skill Dash Attack Condition<br/><i>Tester</i>"] -->|checks| B
    D["Basic Attack Clip Selector Step 1<br/><i>Selector</i>"] -->|asks| C
    D -->|if yes| E["Skill Dash Attack Clip<br/><i>Anim Clip: the spin</i>"]
    D -->|if no| F["Basic Attack Clip 1<br/><i>Anim Clip: the normal first hit</i>"]
    A -->|card text| G["Skill String Desc Dash Attack<br/><i>String Format</i>"]
    H["Skill Dash Attack Damage Multiplier Value Selector<br/><i>Value Selector</i>"] -->|reads the rarity of| A
```

Read it like this:

1. When you pick Stick Twirl, its **Skill Controller** switches on a **State**
   called `Skill Dash Attack`.
2. When you attack, the **Selector** for the first hit asks a **Tester**: "is
   `Skill Dash Attack` switched on, and did the player just dash?"
3. If yes, it plays the spin (**Anim Clip** `Skill Dash Attack Clip`). If no, it
   plays the normal first hit.
4. The **Value Selector** looks up which rarity the controller has, to choose the
   damage.
5. The **String Format** fills in the numbers on the card.

**The big idea:** owning a talent switches on its State, and the rest of the hero
checks that State. To change what a talent does, you change **what points at
what**. That is called a **rewire**.

### The parts you will meet

| Type | What it does |
|---|---|
| **Skill Controller** | The talent itself. Holds its rarity and switches on its State. |
| **State** | Something that is on or off. A talent's State is on while you own the talent. States can have children that run while they are on, such as a Modifier. |
| **Tester** | A yes/no question, for example "is this State on?" |
| **Selector** | Picks one of several options, based on Testers. |
| **Value** | One number. |
| **Value Selector** | One number per rarity. These are the `PER RARITY` lines from `talent_info.py`. |
| **Anim Clip** | One animation, together with the hits, effects and sounds that happen during it. |
| **Modifier** | Changes a stat, such as a cooldown, while its State is on. |
| **Counter** | Counts events and does something when it reaches a number. |
| **Named Event Sender** | Sends a named signal, such as `HORDE_ATTACKS_COUNTER_INC`, that Counters can listen to. |
| **String Format** | Fills the `{0}`, `{1}`, … gaps on a talent card with numbers. |

### Names, labels and hidden links

Every part has a **name**, like `Basic Attack Clip 4`. When one part points at
another, the file stores two things:

- a **hidden ID** of the target, which the game actually follows, and
- a **label**, which is only a note for humans, like
  `[Anim Clip] Hero_SunWukong\Ability Basic\Basic Attack Clip 4`.

A rewire changes the hidden ID and leaves the label alone. After a rewire, the
label can therefore say one thing while the game does another. The inspector
tool below always shows you where a link really goes.

## The inspector: see how parts connect

This helper shows every part of a hero, what each part points at, and what
points at it. Create `talent_graph.py` in the `RavenswatchModManager` folder,
next to `talent_info.py`, and paste this:

```python title="talent_graph.py"
# talent_graph.py - see how the parts of a hero's talents connect.
#
#   python talent_graph.py <Hero> find "<word>"        list parts whose name contains the word
#   python talent_graph.py <Hero> show "<Part name>"   one part: what it uses, and what uses it
#
# Options, added at the end:
#   --mod <mod-id>    look at your mod's changed file instead of the original
#   --file <name>     look in another file of the hero, e.g. --file Hero_Snow_Queen_Ice_Clone
import re
import struct
import sys
from pathlib import Path

from rsmm.engine import cooked
from rsmm.engine import entity_append as EA

args = sys.argv[1:]
options = {}
for flag in ("--mod", "--file"):
    if flag in args:
        at = args.index(flag)
        options[flag] = args[at + 1] if at + 1 < len(args) else ""
        del args[at:at + 2]
if len(args) != 3 or args[1] not in ("find", "show"):
    sys.exit('Usage: python talent_graph.py <Hero> find|show "<text>" [--mod <id>] [--file <name>]')
hero, mode, text = args
stem = options.get("--file") or f"Hero_{hero}"
root = Path("mods") / options["--mod"] / "assets" if "--mod" in options else Path("data/uncooked")
path = (root / "EntitySettings" / "Heroes" / f"Hero_{hero}"
        / f"{stem}.entity.ot.EntitySettingsResource.gen")
if not path.is_file():
    sys.exit(f"No file {path}\nCheck the spelling. For --mod, run rsmm apply first.")

BEGIN, END = cooked.MARK_BEGIN, cooked.MARK_END
cf = cooked.parse(path.read_bytes())
classes = [c.name for c in cf.classes]
picker = classes.index("oCEntityCpntPicker")


def kind_of(class_name):
    words = re.sub(r"^oC(Dt)?(EntityCpnt|EntityComponent)?|Settings$", "", class_name)
    return re.sub(r"(?<=[a-z])(?=[A-Z])", " ", words)


# Every named part: name -> (kind, identity, section index)
parts = {}
for i, sec in enumerate(cf.sections[1:-1], start=1):
    p = sec.payload
    end = p.find(END)
    if end < 0 or end + 24 > len(p):
        continue
    at = end + 20
    n = struct.unpack_from("<I", p, at)[0]
    if not 0 < n < 256:
        continue
    try:
        name = p[at + 4:at + 4 + n].decode("ascii")
    except UnicodeDecodeError:
        continue
    cls = struct.unpack_from("<I", p, 0)[0]
    parts[name] = (kind_of(classes[cls]) if cls < len(classes) else "?", p[at - 16:at], i)


# Testers and collectors keep their conditions in unnamed sub-parts.
count, _ = EA._directory(cf)
owned = set(range(count)) - set(EA.component_vector(cf.sections[-1].payload)[1])


def payloads(index, standalone=False, depth=0):
    """A part's own bytes plus those of every unnamed sub-part it owns."""
    p = cf.sections[index].payload
    yield p
    if depth < 8:
        for off in EA._carrier_refs(p, classes, owned, standalone):
            sub = struct.unpack_from("<I", p, off)[0]
            yield from payloads(1 + sub, True, depth + 1)


def references(index):
    """(identity, label) of every reference a part makes."""
    out = []
    for payload in payloads(index):
        out += refs_in(payload)
    return out


def refs_in(payload):
    out, i = [], payload.find(BEGIN + struct.pack("<I", picker))
    while i != -1:
        if i + 28 <= len(payload):
            n = struct.unpack_from("<I", payload, i + 24)[0]
            if 0 < n < 512:
                label = payload[i + 28:i + 28 + n].decode("utf-8", "replace")
                if label.startswith("["):
                    out.append((payload[i + 8:i + 24], label))
        i = payload.find(BEGIN + struct.pack("<I", picker), i + 1)
    return out


if mode == "find":
    hits = sorted((k, name) for name, (k, _g, _i) in parts.items() if text.lower() in name.lower())
    for kind, name in hits:
        print(f"  {kind:<28} {name}")
    print(f"\n{len(hits)} part(s) in {stem}")
    sys.exit()

if text not in parts:
    sys.exit(f'No part named exactly "{text}". Use: python talent_graph.py {hero} find "<word>"')
kind, guid, index = parts[text]
by_guid = {g: name for name, (_k, g, _i) in parts.items()}
labels = [lab for _n, (_k, _g, i) in parts.items() for g, lab in references(i) if g == guid]
labels = [lab for lab in labels if lab.endswith("\\" + text)] or labels
print(f"{text}\n  type:  {kind}")
print(f"  label: {labels[0] if labels else '(nothing points at it yet)'}")
print("\nUSES (what this part points at):")
for g, label in references(index):
    # The game follows the hidden identity, not the label text, and a rewire
    # changes only the identity. So name the part the identity really leads to.
    if g not in by_guid:
        print(f"  {label}   (in another file)")
        continue
    print(f"  {by_guid[g]}   ({parts[by_guid[g]][0]})")
    note = "" if label.endswith("\\" + by_guid[g]) else "   <- old text, changed by a rewire"
    print(f"      written as: {label}{note}")
print("\nUSED BY (parts that point at this one):")
seen = False
for name, (_k, _g, i) in sorted(parts.items()):
    for g, _label in references(i):
        if g == guid:
            print(f"  {name}")
            seen = True
            break
if not seen:
    print("  (nothing in this file)")
```

The hero name is the **first** spelling from the
[Talent name lookup](/reference/talent-names/) (`SunWukong`, `Snow_Queen`, …).

### Find parts

`find` lists every part whose name contains a word:

```sh
python talent_graph.py SunWukong find "Dash Attack"
```

```text
  Anim Clip                    Skill Dash Attack Clip
  Skill Controller             Skill Controller Dash Attack
  State                        Skill Dash Attack
  Tester                       Basic Attack Is Skill Dash Attack Condition
  Value Selector               Skill Dash Attack Damage Multiplier Value Selector
  ...
27 part(s) in Hero_SunWukong
```

A good first step for any talent is to `find` the **Search word** from the lookup
page.

### Look at one part

`show` takes an exact part name, copied from `find`:

```sh
python talent_graph.py SunWukong show "Basic Attack Clip Selector Step 1"
```

```text
Basic Attack Clip Selector Step 1
  type:  Selector
  label: [Component Selector] Hero_SunWukong\Ability Basic\Basic Attack Clip Selector Step 1

USES (what this part points at):
  Skill Dash Attack Clip   (Anim Clip)
      written as: [Anim Clip] Hero_SunWukong\Skill Dash Attack\Skill Dash Attack Clip
  Basic Attack Is Skill Dash Attack Condition   (Tester)
      written as: [Cpnt Value Tester] Hero_SunWukong\Skill Dash Attack\Basic Attack Is Skill Dash Attack Condition
  Basic Attack Clip 1   (Anim Clip)
      written as: [Anim Clip] Hero_SunWukong\Ability Basic\Basic Attack Clip 1

USED BY (parts that point at this one):
  State Basic Attack Step 1
```

| Line | Meaning |
|---|---|
| `label:` | How other parts write this part's name. Copy it when a recipe asks for a part's **label**. |
| `USES` | What this part points at, and where each link really goes. |
| `written as:` | The label text stored inside this part. Recipes that change a link inside a part match this text. |
| `USED BY` | Which parts point at this one. |

Following `USES` and `USED BY` from part to part is how you work out a chain like
the Stick Twirl diagram above. Start at the talent's `Skill Controller`, then
`show` its State, and keep going.

### Check your own mod

After `rsmm apply`, add `--mod <your-mod-id>` to see the changed file instead of
the original:

```sh
python talent_graph.py SunWukong show "Basic Attack Clip Selector Step 1" --mod twirl-finisher
```

If a link now goes where you wanted, your rewire worked in the file. A link whose
label text is out of date gets a `<- old text, changed by a rewire` note, which
is normal.

## Recipe 1: Make a talent play a different attack

<Badge text="Tested in game" variant="success" />

**Goal:** Stick Twirl's spinning attack becomes the 4th hit of Wukong's normal
combo, with that hit's animation, damage, effects and sound.

**How:** in the chain above, the Selector points at `Skill Dash Attack Clip`.
Point that link at `Basic Attack Clip 4` instead. An Anim Clip carries its hits,
effects and sounds with it, so the whole attack moves.

```toml
[[content]]
kind = "talent"
id   = "twirl_plays_hit_four"
hero = "SunWukong"
file = "Hero_SunWukong.entity"
rewires = [
  { trigger = '[Anim Clip] Hero_SunWukong\Skill Dash Attack\Skill Dash Attack Clip', action = '[Anim Clip] Hero_SunWukong\Ability Basic\Basic Attack Clip 4', exact = true, within = "Basic Attack Clip Selector Step 1", within_span = 600 },
]
```

What each part of the rewire means:

| Field | Meaning |
|---|---|
| `trigger` | The link to change: its `written as:` text from the inspector. |
| `action` | Where it should point now: the target's `label:`, or just its name. |
| `exact = true` | Match the whole label, not just part of it. |
| `within = "..."` | Only change the link inside this part. |
| `within_span = 600` | How far past the part's name to search, in bytes. A few hundred covers a small part. |

<Aside type="tip" title="Use single quotes for labels">
Labels contain backslashes `\`. In TOML, text in `'single quotes'` is taken
exactly as written. Inside `"double quotes"` a backslash starts a special code
and breaks the label.
</Aside>

**Why `exact` and `within`?** A rewire changes the **first** link in the file
whose label matches. In this file the Stick Twirl clip is used by only one part,
so here they are a safety net. Many labels are used by several parts, though, and
without `within` you change whichever comes first, which is often not the one you
mean. Add both whenever you target a link inside one specific part. Recipe 3
shows what goes wrong without them.

**The talent's gate stays:** only the link after "if yes" changed. Without Stick
Twirl, your attacks behave exactly as before.

## Recipe 2: Add an "if this, else that" rule

<Badge text="Tested in game" variant="success" />

**Goal:** after a dash, Wukong's attack becomes **Celestial Pillar**'s slam if you
also own Celestial Pillar, and the 4th combo hit if you do not.

**The problem:** no part says "Pillar owned ? slam : hit 4", so there is nothing
to rewire to.

**The trick:** find a part that already has the right *shape*, copy it, and change
what the copy points at. The copy is called a **clone**.

Wukong's `Basic Attack Combo Selector` has exactly that shape. Check it:

```sh
python talent_graph.py SunWukong show "Basic Attack Combo Selector"
```

```text
USES (what this part points at):
  Skill Attack Finisher Combo   (Attack Combo)
  Skill Attack Finisher   (State)
  Basic Attack Combo   (Attack Combo)
```

In words: "if the State `Skill Attack Finisher` (Celestial Pillar owned) is on,
pick `Skill Attack Finisher Combo`, otherwise pick `Basic Attack Combo`." We copy
it, swap its two results for the two attacks we want, and point Stick Twirl at the
copy:

```toml
[[content]]
kind = "talent"
id   = "twirl_pillar_or_hit_four"
hero = "SunWukong"
file = "Hero_SunWukong.entity"

clone_nodes = [
  { source = "Basic Attack Combo Selector", name = "Twirl Finisher Clip Selector", retarget = [
    { from = '[Dt Attack Combo] Hero_SunWukong\Skill Attack Finisher\Skill Attack Finisher Combo', to = '[Anim Clip] Hero_SunWukong\Skill Attack Finisher\Skill Attack Finisher Clip' },
    { from = '[Dt Attack Combo] Hero_SunWukong\Ability Basic\Basic Attack Combo', to = '[Anim Clip] Hero_SunWukong\Ability Basic\Basic Attack Clip 4' },
  ] },
]

rewires = [
  { trigger = '[Anim Clip] Hero_SunWukong\Skill Dash Attack\Skill Dash Attack Clip', action = "Twirl Finisher Clip Selector", exact = true, within = "Basic Attack Clip Selector Step 1", within_span = 600 },
]
```

| Field | Meaning |
|---|---|
| `source` | The part to copy. |
| `name` | A new, unused name for the copy. |
| `retarget` | Links to change **inside the copy**. `from` is the `written as:` text inside the source part; `to` is the new target's `label:`. |

A clone on its own does nothing, because nothing points at it yet. The `rewires`
entry connects it: `action` is the copy's `name`. Clones are always built first,
so a rewire in the same block can use them.

The tested part is the Pillar branch: with both talents owned, the dash attack
became the Pillar slam. The "no Pillar" branch uses the same file change as
Recipe 1 but has not been played on its own.

## Recipe 3: Make a talent switch on a different effect

<Badge text="Partly tested" variant="caution" />

**Goal:** Scarlet (Red) has a finished POWER finisher in her files, but no talent
ever switches it on. We make **Short Wick** switch it on instead of its own effect.

First look at both controllers:

```sh
python talent_graph.py Red show "Skill Controller Secondary Quick Bombs"
python talent_graph.py Red show "Skill Primary Finisher Finisher Damage Multiplier Selector"
```

Short Wick's controller switches on the State `Skill Secondary Quick Bombs`. The
finisher's damage Value Selector points at `Skill Controller Primary Finisher`, a
controller nobody can ever own, three times, once for each rarity condition. So we
make two changes:

```toml
[[content]]
kind = "talent"
id   = "short_wick_runs_finisher"
hero = "Red"
file = "Hero_Red.entity"
rewires = [
  # 1. The effect: Short Wick switches on the finisher's State.
  { trigger = '[State] Hero_Red\Skill Secondary Quick Bombs\Skill Secondary Quick Bombs', action = '[State] Hero_Red\Skill Primary Finisher\Skill Primary Finisher', exact = true, within = "Skill Controller Secondary Quick Bombs", within_span = 400 },

  # 2. The damage: the finisher reads its rarity from Short Wick.
  { trigger = "Skill Controller Primary Finisher", action = "Skill Controller Secondary Quick Bombs", all = true },
]
```

Two new things here:

- **`all = true`** changes every matching link, not just the first. A Value
  Selector points at its controller once per rarity, and changing only one link
  leaves the other rarities reading the old controller.
- **Why the first rewire needs `exact` and `within`:** the text `Skill Secondary
  Quick Bombs` also appears inside the label of Short Wick's cooldown Modifier,
  which comes earlier in the file. An earlier version of this mod matched that
  shorter text without `exact` and `within`, and changed the Modifier instead of
  the controller's State link. Nothing reported an error.

Pair it with a new name and description from the beginner tutorial, and
optionally flatten the damage with `union_patches`.

**Tested so far:** the damage change reached the game. Whether POWER now ends with
the finisher attack has not been confirmed yet.

## Recipe 4: Add a stat bonus, with a new number on the card

<Badge text="Tested in game" variant="success" />

**Goal:** Sun Wukong's **Fiery Dragon** also reduces his TRAIT cooldown: −10 %
Common, −15 % Rare, −20 % Epic, −25 % Legendary. The card shows the number.

### The short way: `add_stats`

<Badge text="Partly tested" variant="caution" />

One field does all of the wiring below. In the editor, it is the **+ Add a stat**
button under a talent card.

```toml
[[content]]
kind = "talent"
id   = "fiery_dragon_cooldown"
hero = "SunWukong"
add_stats = [
  { talent = "Trait Fire", stat = "CD reduce trait", values = [0.10, 0.15, 0.20, 0.25] },
]
```

- `talent` is the card's row name (`Skill Controller Trait Fire` → `Trait Fire`).
- `stat` is any stat from the stat list: the same names the item editor offers.
- `values` is one number for every rarity, or four (Common, Rare, Epic, Legendary).
  The number is in the stat's own unit: `0.25` on a cooldown stat is −25 %.
- The card gets a new number slot, the next `{N}` after the ones it has. Write it in
  the description with a `skill` block, for example `• #TRAIT@ cooldown &-{1}%~`.
  `percent = false` shows the number as it is, without multiplying by 100.

`add_stats` is not quite the hand-built version below. It adds the new modifier to
the talent's own State instead of swapping that State for a copy, so talents whose
State already does something keep doing it. The parts are the proven ones; this
exact arrangement has not been played yet.

Ultimates cannot take a stat this way: they have no State that marks them as owned.

**Talents two heroes share.** Romeo and Juliet build their shared talents (Love
Shield, Ignite, …) in one file both inherit, `Hero_Juliet/Hero_Romeo_Juliet_Common`;
each hero's own file only overrides the card. `add_stats` and `include` find the
talent there and write that file, so the change reaches **both** heroes. `during`
and `after` then take the abilities that file builds (SPECIAL and TRAIT).
`rebuild` is refused for these for now: the hero's own card would keep
pointing at the old effect.

<Badge text="Tested in game" variant="success" /> **Only while an ability is in use:** add `during = "DEFENSE"` (or `ATTACK`, `POWER`,
`SPECIAL`, `TRAIT`, `DASH`) to an entry, e.g. "During #DEFENSE@, #ATTACK@ damage
&+{0}%~". The bonus then reads a copy of a selector the game ships ("ability in use
→ the number, else 0"). The ability is found through the hero's controller for that
button, never by name. A hero whose ability only signals its start (Merlin's POWER,
DEFENSE and TRAIT) cannot use `during` for it; the editor leaves those out.

<Badge text="Tested in game" variant="success" /> **For a while after an ability:** add `after = "DEFENSE", seconds = 3`
to an entry, e.g. "For #3@ second(s) after using #DEFENSE@, #ATTACK@ damage
&+{0}%~". Each use of the ability restarts the 3 seconds. It is built the way
Beowulf's **Defense Damage Aura** builds its window: using the ability fires an
event that switches a new, empty State off and on again, that State runs a timer,
and the timer switches the State off when the time is up. (A timer's State link only
*ends* that State; it never switches it on.) The bonus is then "during" that State. Because it only needs the moment the
ability starts, `after` also works for abilities that only signal their start
(Merlin). In the editor, pick **For a while after …** under **When**.

```toml
add_stats = [
  { talent = "Trait Fire", stat = "Attack power", values = 0.3, after = "DEFENSE", seconds = 3 },
]
```

<Badge text="Tested in game" variant="success" /> **At most once every N seconds:** add `cooldown = 8` to an
`after` entry and a use only restarts the window when the last restart was at least
8 seconds ago; uses in between do nothing. This is how Romeo's **Love Shield** limits
itself ("every 3 s max"), and the gate is a copy of his: the ability fires a tester
that passes only while a new Cooldown State is off, and that State then restarts the
window and switches itself off after `cooldown` seconds. In the editor, fill in **At
most once every … second(s)** under the "Lasts" box; leave it empty for every use.

```toml
add_stats = [
  { talent = "Trait Fire", stat = "Attack power", values = 0.3, after = "DEFENSE", seconds = 3, cooldown = 8 },
]
```

<Badge text="Tested in game" variant="success" /> **Your next ability after another:** add `next = "ATTACK"` to an
`after` entry and the bonus ends once ATTACK has been used, like Beowulf's
**Retaliation** ("your next ATTACK within … after DEFENSE"). The window is the same
`after` window; ATTACK's in-use State ends it as it finishes, so the bonus covers that
whole attack and is gone after it. `next` takes an ability whose use lasts (the same
ones `during` takes) and must differ from `after`. In the editor, pick it under
**Used up by**. `next` and `cooldown` can be combined.

```toml
add_stats = [
  { talent = "Trait Fire", stat = "Attack power", values = 0.5, after = "DEFENSE", seconds = 4, next = "ATTACK" },
]
```

**Stats that land on enemies are refused.** `add_stats` builds a modifier on the
hero itself, so a stat the game only ever puts on whoever is hit (Ignite, Bleed,
Chilled, Vulnerable, Weak, Marked, Rooted, …) would debuff your own hero. The list
is read from the game's files; the editor shows those stats greyed out.

### Give a talent another talent's effect: `include`

<Badge text="Tested in game" variant="success" />

Owning one talent can also switch on another of the same hero's talents. What a
talent does hangs off its State, so `include` keeps the other talent's State on
while this one is owned, and everything that State does or unlocks runs. In the
editor, it is **Also gives the effect of** on a card.

```toml
[[content]]
kind    = "talent"
id      = "shapeshifter_wick"
hero    = "Red"
include = [{ talent = "Trait Active", from = "Secondary Quick Bombs" }]
```

This gives Scarlet's **Shapeshifter** the bomb from **Short Wick** that explodes as
soon as it hits the ground: that behaviour is a switch wired to Short Wick's State,
which the bomb reads. You get all of the other talent, not a piece of it: here
Short Wick's faster SPECIAL recharge comes too. Numbers that scale with the other
card's rarity use their Common value, because that card is not owned. Mention the
effect in the card's text with a `skill` block.

#### From another hero

<Badge text="Tested in game" variant="success" />

Add `hero` to take a talent from another hero. Its effect is copied into your
hero's file, and its numbers follow **your** card's rarity:

```toml
[[content]]
kind    = "talent"
id      = "virtuoso_focus"
hero    = "Piper"
include = [{ talent = "Attack Move Speed", from = "Power Hold", hero = "SunWukong" }]
```

Owning Piper's **Virtuoso** now also gives Wukong's **Focused Strikes** bonus.

Most talents cannot move. They work inside their hero's abilities: Aladdin's
Defense Tornado is a number his DEFENSE tornado reads, and Piper has no such
tornado. RSMM refuses those and says why. These 9 can be given to any hero:

| Hero | Talent (card) | `from` |
|------|---------------|--------|
| Aladdin | Master Thief | `Passive Extra MO` |
| Aladdin | Jinniya's Gift | `Trait Extra Wish` |
| Carmilla | Bat Master | `Defense Master` |
| Juliet | Wedding Gifts | `Passive Bonus Object` |
| Melusine | Soothing Presence | `Passive Heal In Combat` |
| Melusine | Dance Step | `Trait Dash` |
| Merlin | Astrology | `Passive Gain Reroll High Talent` |
| Piper | Virtuoso | `Attack Move Speed` |
| Sun Wukong | Focused Strikes | `Power Hold` |

In the editor, they are under **Other heroes** in the **Also gives the effect of**
list.

### Make an ability bigger: `scale`

<Badge text="Tested in game" variant="success" />

Range is not a stat: each ability works out its own size in its own files. `scale`
grows one of those numbers (a radius, a length, a width) while the talent is
owned, by `1 + amount`, so `0.3` is +30%:

```toml
[[content]]
kind    = "talent"
id      = "rising_tide"
hero    = "Melusine"
rebuild = ["Trait Dash"]
scale   = [
  { talent = "Trait Dash", node = "Primary Ability Radius Operation", file = "Hero_Melusine_Power_Caster_Model", values = [0.2, 0.3, 0.4, 0.5] },
]
```

`node` is the number to grow and `file` the hero file it is in, which is needed
only when the name is in more than one. The number can sit in an entity the hero
spawns (Melusine's POWER caster, Piper's projectile), as long as that entity
already reads values from the hero. The card gets a `{N}` for the amount. Only the
hit area is sure to change; an ability's visual effect may keep its old size.

In the editor, this is **Make an ability bigger** in the custom-talent builder: it
lists each hero's sizes by ability.

### Make hits put a status on enemies: `on_hit`

<Badge text="Not yet tested" variant="danger" />

While the talent is owned, one of the hero's hits also puts a status on whoever
it hits: Chilled, Ignite, Bleed, Vulnerable, Weak or Rooted.

```toml
[[content]]
kind = "talent"
id   = "fire_tide"
hero = "Melusine"

[[content.on_hit]]
talent = "Attack Speed"
damage = "Primary Ability Damage"
status = "Ignite"
```

`damage` is one of the hero's damage records, the thing a hit deals: an ability
can have more than one (Melusine's POWER has a normal and a geyser hit), so add
an entry for each. `file` narrows it to one entity file when the name repeats.
The status is copied from a hit in the game that already applies it, with its
own duration and strength. Mention it in the card's text with a `skill` block.

In the editor, this is **Hits apply a status** in the custom-talent builder: it
lists each hero's hits by ability.

### Rebuild a talent from scratch: `rebuild`

<Badge text="Not yet tested" variant="danger" />

The number of talents a hero has is fixed, so a new talent replaces one you pick.
`rebuild` turns that talent's own effect off and keeps only its card slot; the
stats you add are then all it does. In the editor, press **Build a custom talent**
on the Talents tab (or **Replace with a custom talent** on a card): pick the talent
to replace, name it, and add building blocks or start from an example. An idea the
blocks can't build yet ("POWER spawns a tornado") can be sent from the same screen
as a **Talent idea** on GitHub; that is how new blocks get made.

```toml
[[content]]
kind = "talent"
id   = "keen_eye"
hero = "Beowulf"
rebuild   = ["Attack Fire Cone"]
add_stats = [
  { talent = "Attack Fire Cone", stat = "Crit chance primary", values = [0.05, 0.10, 0.15, 0.20] },
]

[[content]]
kind        = "skill"
id          = "keen_eye_card"
hero        = "Beowulf"
source      = "Attack Fire Cone"
name        = "Keen Eye"
description = "• #POWER@ Crit Chance &+{0}%~"
```

How it works: the talent's controller is pointed at a new, empty State, so the
State everything the talent did hangs off never switches on. The card's old
numbers are removed too, which is why the first added stat is `{0}`. Give the card
new text: without a `skill` block it keeps the old wording.

### The long way: four clones

This recipe needs four clones, because a stat bonus is a small chain of its own:

```mermaid
flowchart LR
    C["Skill Controller Trait Fire"] -->|switches on| S["Skill Trait Fire With Cooldown<br/><i>new State</i>"]
    S -->|child| M["Skill Trait Fire Cooldown Reduction Modifier<br/><i>new Modifier: TRAIT cooldown</i>"]
    M -->|amount| V["Skill Trait Fire Cooldown Reduction Selector<br/><i>new Value Selector</i>"]
    V -->|rarity of| C
    C -->|card| F["Skill String Desc Trait Fire With Cooldown<br/><i>new String Format, 2 numbers</i>"]
```

### Where the pieces come from

Look at what exists:

```sh
python talent_graph.py SunWukong show "Skill Trait Fire"
python talent_graph.py SunWukong show "Skill Power Hold"
python talent_graph.py SunWukong show "Skill String Desc Dash Sprint"
```

- Fiery Dragon's State `Skill Trait Fire` has **no children** (its `USES` list is
  empty), so there is nowhere to hang a Modifier.
- Wukong's **Power Hold** State has exactly one child, a Modifier, which reads its
  amount from a Value Selector. That is the shape we need, so we copy Power Hold's
  State and Modifier.
- The amount: copy Fiery Dragon's own damage Value Selector. It already reads
  Fiery Dragon's rarity, so we only replace its numbers.
- The card: Fiery Dragon's String Format fills one gap, and we need two. Dash
  Sprint's has two, so we copy that.

### Which stat a Modifier changes

A copied Modifier changes the same stat as the Modifier it was copied from. Power
Hold's changes attack power, not TRAIT cooldown. `modifier_stat` takes the stat from any
other shipped Modifier instead, even another hero's:

| Stat | Copy it from (`hero`, `node`) |
|---|---|
| POWER cooldown | `Snow_Queen`, `Skill Trait Abilities Cooldown Primary CD Modifier` |
| SPECIAL cooldown | `Red`, `Skill Secondary Quick Bombs CD Reduction Modifier` |
| DEFENSE cooldown | `Snow_Queen`, `Skill Trait Abilities Cooldown Defensive CD Modifier` |
| TRAIT cooldown | `Beowulf`, `Skill Trait Quest Complete CD Reduction Modifier` |

To look for other stats, `find "Modifier"` on any hero and read the names.

### The mod

```toml
[[content]]
kind = "talent"
id   = "trait_fire_cooldown_wiring"
hero = "SunWukong"
file = "Hero_SunWukong.entity"

clone_nodes = [
  # The amount: Fiery Dragon's own per-rarity selector, numbers replaced below.
  { source = "Skill Trait Fire Damage Multiplier Selector", name = "Skill Trait Fire Cooldown Reduction Selector" },

  # The Modifier: Power Hold's, reading the new amount, changing TRAIT cooldown.
  { source = "Skill Power Hold AP Modifier", name = "Skill Trait Fire Cooldown Reduction Modifier", modifier_stat = { hero = "Beowulf", node = "Skill Trait Quest Complete CD Reduction Modifier" }, retarget = [
    { from = '[Value Selector] Hero_SunWukong\Skill Power Hold\Skill Power Hold AP Selector', to = '[Value Selector] Hero_SunWukong\Skill Trait Fire\Skill Trait Fire Cooldown Reduction Selector' },
  ] },

  # The State: Power Hold's, holding the new Modifier as its child.
  { source = "Skill Power Hold", name = "Skill Trait Fire With Cooldown", retarget = [
    { from = '[Modifier] Hero_SunWukong\Skill Power Hold\Skill Power Hold AP Modifier', to = '[Modifier] Hero_SunWukong\Skill Trait Fire\Skill Trait Fire Cooldown Reduction Modifier' },
  ] },

  # The card: Dash Sprint's two-number format. {0} = cooldown, {1} = damage.
  { source = "Skill String Desc Dash Sprint", name = "Skill String Desc Trait Fire With Cooldown", retarget = [
    { from = '[Value Selector] Hero_SunWukong\Skill Dash Sprint\Skill Dash Sprint Move Speed Increase Selector', to = '[Value Selector] Hero_SunWukong\Skill Trait Fire\Skill Trait Fire Cooldown Reduction Selector' },
    { from = '[Value] Hero_SunWukong\Skill Dash Sprint\Skill Dash Sprint Max Duration', to = '[Multi values operations] Hero_SunWukong\Skill Trait Fire\Skill Trait Fire Supposed Damage Operation' },
  ], rename = [
    { from = "Skill_Dash_Sprint_Desc", to = "Skill_Trait_Fire_Desc" },
  ] },
]

# 0.25 means -25 %, the same scale Beowulf's Draconic Binds uses.
union_patches = [
  { label = "Skill Trait Fire Cooldown Reduction Selector", index = 1, old = 3.85, new = 0.25 },
  { label = "Skill Trait Fire Cooldown Reduction Selector", index = 3, old = 3.3,  new = 0.20 },
  { label = "Skill Trait Fire Cooldown Reduction Selector", index = 5, old = 2.75, new = 0.15 },
  { label = "Skill Trait Fire Cooldown Reduction Selector", index = 7, old = 2.2,  new = 0.10 },
]

rewires = [
  # Everything that used Fiery Dragon's State now uses the new one.
  { trigger = '[State] Hero_SunWukong\Skill Trait Fire\Skill Trait Fire', action = "Skill Trait Fire With Cooldown", exact = true, all = true },
  # The card reads its numbers from the new two-number format.
  { trigger = '[String Format] Hero_SunWukong\Skills\Skill String Desc Trait Fire', action = "Skill String Desc Trait Fire With Cooldown", exact = true },
]

[[content]]
kind   = "skill"
id     = "trait_fire_cooldown_text"
hero   = "Sun_Wukong"
mode   = "relabel"
source = "Skill_Trait_Fire"
description = "• Adds an explosion of fire to the activation effects of $YANG STANCE*, dealing &{1}~ area damage and inflicting enemies with #IGNITE@\n• #TRAIT@ cooldown &-{0}%~"
```

Three details worth copying into your own work:

- **`rename`** replaces a whole piece of text inside the copy. A String Format
  names the text entry it fills in, so the copy must name Fiery Dragon's
  description, not Dash Sprint's.
- **`all = true` on the State rewire** moves both the controller's link *and* the
  Tester that adds the fire explosion. If you moved only the controller, the
  explosion would stop working.
- **The `old` values in `union_patches`** are the numbers copied along with the
  Value Selector, which were the damage numbers. The new values are percentages
  written as fractions.

## Recipe 5: Build an "every N attacks" effect

<Badge text="Partly tested" variant="caution" />

**Goal:** Piper's **Horde** also summons 3/4/5 rats that attack at once, every 16
basic attacks.

This is the largest recipe. It reuses one idea many times: **find a machine that
already does something similar, clone it, and give the copy its own inputs and
outputs.**

Piper's **Ghost Notes** already counts notes and does something every N of them:

```text
Event Attack Shoot Active          (every note Piper plays)
  -> Ghost Notes Notify Tester     (only if Ghost Notes is owned)
  -> SKILL_ATTACK_GHOST_NOTES_COUNTER_INC Event Sender
Skill Attack Ghost Notes Counter   (listens for that signal, counts to the
                                    Requirement Selector, then fires the proc)
```

The mod builds a second copy of that machine for Horde:

| Clone | Copied from | Changed |
|---|---|---|
| `Horde Attacks Required Selector` | Ghost Notes' threshold | Reads Horde's rarity. All four numbers set to 16. |
| `Horde Attacks Counter` | Ghost Notes' counter | Fires the rat proc. **Listens for its own signal**, `HORDE_ATTACKS_COUNTER_INC`. |
| `HORDE_ATTACKS_COUNTER_INC Event Sender` | Ghost Notes' sender | Sends the new signal. |
| `Horde Attacks State` | Ghost Notes' State | Holds the new counter. Horde's controller points here. |
| `Horde Basic Attack Shoot`, `Horde Basic Attack Notify` | Piper's shot events | Only the **basic** attack sends the new signal. |
| `Horde Rats Count Selector`, `Horde Rats Proc`, `Horde Rats Count Switch` | Invasive Blast's spawn | Spawns Horde's own number of rats, which attack at once. |
| `Skill String Desc Horde Rats` | Sound Barrier's 5-number card format | Shows the new numbers on Horde's card. |

The one new rule this recipe teaches:

<Aside type="caution" title="A copied Counter must listen for a new signal">
Counters and Event Senders find each other **by name**, not by link. A copied
Counter that keeps the original signal name counts the original talent's events
too. Use `rename` on both the Counter and its Event Sender to give them a signal
of their own, like `HORDE_ATTACKS_COUNTER_INC`. In testing, a signal name made up
by a mod was delivered like the game's own.
</Aside>

**Tested so far:** the cloned counter and the made-up signal name worked in the
game, and rats spawned. The final version, with rats counted only from basic
attacks and the corrected card numbers, has not been played yet.

<details>
<summary><strong>Show the full Horde mod</strong></summary>

```toml title="mods/piper-horde/manifest.toml"
[mod]
id          = "piper-horde"
name        = "Piper: Horde of Rats"
version     = "0.1.0"
author      = "YourName"
description = "Horde also summons 3 / 4 / 5 rats that attack at once, every 16 basic attacks."
license     = "MIT"
sdk_version = ">=3.0,<4"
enabled     = true
experimental = true
tags        = ["talents", "piper"]
multiplayer_scope = "deterministic-shared"

[[content]]
kind = "talent"
id   = "horde_rats_wiring"
hero = "Piper"
file = "Hero_Piper.entity"

clone_nodes = [
  # -- the rat count ----------------------------------------------------------
  { source = "Skill Defense Spawn Pets Max Count Selector", name = "Horde Rats Count Selector", retarget = [
    { from = '[Dt Skill Controller] Hero_Piper\Skills\Skill Controller Defense Spawn Pets', to = '[Dt Skill Controller] Hero_Piper\Skills\Skill Controller Trait More Controllable Pets' },
  ] },
  { source = "Event Skill Attack Ghost Notes Notify Default", name = "Horde Rats Proc", retarget = [
    { from = '[Named Event Sender] Hero_Piper\Skill Attack Ghost Notes\SKILL_ATTACK_GHOST_NOTES_COUNTER_INC Event Sender', to = '[State] Hero_Piper\Skill Defense Spawn Pets\Event Skill Defense Spawn Pets Proc' },
  ] },
  { source = "Trait Ability Max Controllable Pets Selector", name = "Horde Rats Count Switch", retarget = [
    { from = '[State] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets', to = '[State] Hero_Piper\Skill Trait More Controllable Pets\Horde Rats Proc' },
    { from = '[Value Operation] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets Count Operation', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Horde Rats Count Selector' },
    { from = '[Value] Hero_Piper\Ability Trait\Trait Ability Max Controllable Pets Default Amount', to = '[Value Selector] Hero_Piper\Skill Defense Spawn Pets\Skill Defense Spawn Pets Max Count Selector' },
  ] },

  # -- the counter and its state ----------------------------------------------
  { source = "Skill Attack Ghost Notes Requirement Selector", name = "Horde Attacks Required Selector", retarget = [
    { from = '[Dt Skill Controller] Hero_Piper\Skills\Skill Controller Attack Ghost Notes', to = '[Dt Skill Controller] Hero_Piper\Skills\Skill Controller Trait More Controllable Pets' },
  ] },
  { source = "Skill Attack Ghost Notes Counter", name = "Horde Attacks Counter", retarget = [
    { from = '[State] Hero_Piper\Skill Attack Ghost Notes\Event Skill Attack Ghost Notes Proc', to = '[State] Hero_Piper\Skill Trait More Controllable Pets\Horde Rats Proc' },
    { from = '[Value Selector] Hero_Piper\Skill Attack Ghost Notes\Skill Attack Ghost Notes Requirement Selector', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Horde Attacks Required Selector' },
  ], rename = [
    { from = "SKILL_ATTACK_GHOST_NOTES_COUNTER_INC", to = "HORDE_ATTACKS_COUNTER_INC" },
    { from = "SKILL_ATTACK_GHOST_NOTES_COUNTER_DEC", to = "HORDE_ATTACKS_COUNTER_DEC" },
  ] },
  { source = "Skill Attack Ghost Notes", name = "Horde Attacks State", retarget = [
    { from = '[Counter] Hero_Piper\Skill Attack Ghost Notes\Skill Attack Ghost Notes Counter', to = '[Counter] Hero_Piper\Skill Trait More Controllable Pets\Horde Attacks Counter' },
    { from = '[Entity 3d Node] Hero_Piper\Skill Attack Ghost Notes\Skill Attack Ghost Notes 3d Node Left', to = '[Cpnt Value Tester] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets Legendary Tester' },
  ] },

  # -- the basic-attack-only signal -------------------------------------------
  { source = "SKILL_ATTACK_GHOST_NOTES_COUNTER_INC Event Sender", name = "HORDE_ATTACKS_COUNTER_INC Event Sender", rename = [
    { from = "SKILL_ATTACK_GHOST_NOTES_COUNTER_INC", to = "HORDE_ATTACKS_COUNTER_INC" },
  ] },
  { source = "Event Primary Ability Shoot", name = "Horde Basic Attack Notify", retarget = [
    { from = '[State] Hero_Piper\Ability Common\Event Attack Shoot Active', to = '[Cpnt Value Tester] Hero_Piper\Skill Attack Ghost Notes\Skill Attack Ghost Notes Notify Tester' },
    { from = '[Named Event Sender] Hero_Piper\Ability Primary\Primary Ability Increase Shoot Spawn Index Event Sender', to = '[Named Event Sender] Hero_Piper\Skill Trait More Controllable Pets\HORDE_ATTACKS_COUNTER_INC Event Sender' },
  ] },
  { source = "Event Attack Shoot Active", name = "Horde Basic Attack Shoot", retarget = [
    { from = '[Cpnt Value Tester] Hero_Piper\Skill Attack Ghost Notes\Skill Attack Ghost Notes Notify Tester', to = '[State] Hero_Piper\Skill Trait More Controllable Pets\Horde Basic Attack Notify' },
  ] },

  # -- the card: {0} rats per trigger, {1} attacks needed, {2} rats per group,
  #    {3} rats per group without Horde, {4} extra max rats --------------------
  { source = "Skill String Desc Defensive Armor Quest", name = "Skill String Desc Horde Rats", retarget = [
    { from = '[Value Selector] Hero_Piper\Skill Defensive Armor Quest\Skill Defensive Armor Quest Objective Count Selector', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Horde Rats Count Selector' },
    { from = '[Value] Hero_Piper\Skill Defensive Armor Quest\Skill Defensive Armor Quest Armor Per Proc', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Horde Attacks Required Selector' },
    { from = '[Value] Hero_Piper\Skill Defensive Armor Quest\Skill Defensive Armor Quest Character Impacts Required', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets Per Spawn Amount Selector' },
    { from = '[Multi values operations] Hero_Piper\Skill Defensive Armor Quest\Skill Defensive Armor Quest Complete Shield Operation', to = '[Value] Hero_Piper\Ability Trait\Trait Ability Pets Per Spawn Default Amount' },
    { from = '[Value] Hero_Piper\Skill Defensive Armor Quest\Skill Defensive Armor Quest Complete Shield Duration', to = '[Value Selector] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets Amount Selector' },
  ], rename = [
    { from = "Skill_Defense_Armor_Quest_Desc", to = "Skill_Trait_More_Controllable_Pets_Desc" },
  ] },
]

union_patches = [
  # Every 16 basic attacks at every rarity.
  { label = "Horde Attacks Required Selector", index = 1, old = 6, new = 16 },
  { label = "Horde Attacks Required Selector", index = 3, old = 7, new = 16 },
  { label = "Horde Attacks Required Selector", index = 5, old = 8, new = 16 },
  { label = "Horde Attacks Required Selector", index = 7, old = 10, new = 16 },
  # 3 rats Common, 4 Rare, 5 Epic and Legendary.
  { label = "Horde Rats Count Selector", index = 1, old = 7, new = 5 },
  { label = "Horde Rats Count Selector", index = 3, old = 6, new = 5 },
  { label = "Horde Rats Count Selector", index = 5, old = 5, new = 4 },
  { label = "Horde Rats Count Selector", index = 7, old = 4, new = 3 },
]

rewires = [
  # Invasive Blast's count store reads the switch instead of its own numbers.
  { trigger = '[Value Selector] Hero_Piper\Skill Defense Spawn Pets\Skill Defense Spawn Pets Max Count Selector', action = "Horde Rats Count Switch", exact = true, within = "Skill Defense Spawn Pets Count Operation Store", within_span = 400 },
  # Horde's controller and both rat selectors use the new State.
  { trigger = '[State] Hero_Piper\Skill Trait More Controllable Pets\Skill Trait More Controllable Pets', action = "Horde Attacks State", exact = true, all = true },
  # Horde's card reads the 5-number format.
  { trigger = '[String Format] Hero_Piper\Skills\Skill String Desc Trait More Controllable Pets', action = "Skill String Desc Horde Rats", exact = true },
  # Only the BASIC attack shot goes through Horde's notify.
  { trigger = '[State] Hero_Piper\Ability Common\Event Attack Shoot Active', action = "Horde Basic Attack Shoot", exact = true, within = "Event Basic Attack Shoot Active", within_span = 300 },
]

[[content]]
kind   = "skill"
id     = "horde_rats_text"
hero   = "Piper"
mode   = "relabel"
source = "Skill_Trait_More_Controllable_Pets"
description = "• For every #{1}@ notes played with #ATTACK@, summon &{0}~ rats that immediately attack nearby enemies\n• Rats spawn in groups of #{2}@ (instead of {3})\n• Increase maximum controllable rats by &{4}~"
```

</details>

## Unlock a LOCKED number

<Badge text="Not yet tested" variant="danger" />

`talent_info.py` marks some single numbers `LOCKED`: the game ignores them and
reads a per-rarity list instead. Usually the right move is to change that list
with `union_patches`. If you want one fixed number at every rarity instead, add
`clear_override = true`:

```toml
value_patches = [
  { label = "Skill Special Marked Value", old = 10.0, new = 12.0, clear_override = true },
]
```

This cuts the link to the per-rarity list, so the talent stops scaling with
rarity.

## All advanced fields

Everything here goes inside a `kind = "talent"` block. A block that uses
`rewires`, `clone_nodes`, `union_patches` or `int_patches` needs a `file = "..."`
line that names exactly one hero file.

### `rewires`

| Field | Required | Meaning |
|---|---|---|
| `trigger` | yes | The link to change, matched against label text. Copy the `written as:` text. |
| `action` | yes | The new target: its `label:`, or just its name. For a clone, use the clone's `name`. |
| `exact` | no | `true` matches the whole label. Without it, any label *containing* the text matches. |
| `within` | no | Only change links inside the part with this exact name. |
| `within_span` | no | How many bytes after that name to search. Default 2048. |
| `all` | no | `true` changes every match. Default: only the first. |
| `count` | no | Change this many matches. |
| `subtest_of` | no | Only change the links a named Tester checks. |

### `clone_nodes`

| Field | Required | Meaning |
|---|---|---|
| `source` | yes | Exact name of the part to copy. |
| `name` | yes | A name no part has yet. |
| `retarget` | no | A list of `{ from, to }`. `from` is a label written inside the source part; `to` is the new target's label. |
| `rename` | no | A list of `{ from, to }` whole pieces of text replaced inside the copy, such as a signal name or a text entry name. |
| `modifier_stat` | no | `{ hero, node }`: make a copied Modifier change the same stat as that Modifier. |

Clones are built before every other change in the block, so a rewire in the same
block can point at them.

### Other fields

| Field | Meaning |
|---|---|
| `value_patches` | Single numbers (beginner tutorial). Add `clear_override = true` to unlock a `LOCKED` one. |
| `union_patches` | Per-rarity numbers (beginner tutorial). |
| `int_patches` | An older way to write whole numbers inside a part. Use `union_patches` instead. |
| `add_stats` | Give a talent a stat it does not have, with a number on its card ([Recipe 4](#the-short-way-add_stats)). |
| `rebuild` | Turn a talent's own effect off, keeping its card: the start of a new talent ([Recipe 4](#rebuild-a-talent-from-scratch-rebuild)). |

## Rules that save hours

- **Look before you rewire.** `show` the part you want to change *and* the part
  you want to point at. Most mistakes are pointing at a part with a similar name.
- **Use `exact` and `within`** whenever the label text could also appear inside a
  longer label. Recipe 3's Short Wick mistake is the classic case.
- **Use `all = true` for Value Selectors and States that many parts share.** A
  per-rarity list points at its controller once per rarity.
- **Shared parts are shared.** If two talents use the same part, rewiring that
  part changes both talents. Clone it first and change the copy, as Recipe 5 does
  with Invasive Blast's numbers.
- **Clone small logic parts only:** Selectors, Value Selectors, States, Testers,
  Counters, Modifiers, Event Senders, String Formats. Parts that own animations,
  visual effects or spawners contain pieces RSMM does not copy. Point *at* those
  instead of cloning them.
- **Card numbers come from a String Format.** To show a new number, clone a String
  Format with enough gaps, retarget each gap, `rename` its text entry to your
  talent's `_Desc`, and rewire the controller's `[String Format]` link to the copy.
  Keep the description's `{0}`…`{N}` in the same order as the gaps.
- **Check the file, then check the game.** `talent_graph.py … --mod <id>` proves
  the link is in the file. Only playing with the talent owned proves it works.

## Troubleshooting

| Message | What it means | How to fix it |
|---|---|---|
| `no picker reference matching '...'` | No link has that label text. | Copy the `written as:` text from `show`, including the `[Type]` part. |
| `rewire '...' -> '...': already points there` | The link already goes to that target. | Nothing to do, or you picked the wrong `trigger`. |
| ``rewires/int_patches need `file` to select exactly one entity file`` | The block has no `file` line. | Add `file = "Hero_<Hero>.entity"`. |
| `a component named '...' already exists` | The clone's `name` is taken. | Pick a new name. |
| `expected exactly one component named '...', found 0` | The clone's `source` is misspelled. | Copy the exact name from `find`. |
| `clone of '...': no reference labelled '...'` | A `retarget` `from` is not a link inside the source part. | `show` the source part and copy a `written as:` text. |

**It builds, but the game shows no change:**

1. Check with `talent_graph.py … --mod <id>` that the link goes where you meant.
2. Make sure you own the talent (use the testing file) and are playing that hero.
3. Make sure no other mod changes the same hero file.
4. Make sure you changed the link the game actually uses. A hero often has similar
   parts for different forms, such as Wukong's `… Condition` and `… Condition Yin`.
   `USED BY` shows which ones are really connected.

<CardGrid>
  <LinkCard title="Talent modding, step by step" href="/guides/talent-tutorial/" description="The beginner tutorial this page builds on." />
  <LinkCard title="Talent name lookup" href="/reference/talent-names/" description="Every hero's talents with the names a mod needs." />
</CardGrid>

---

# Uncooked asset mirror

> The decoded asset mirror for local reference, and why it's git-ignored.

Source: https://docs.rsmm.me/guides/uncooked-assets/

`data/uncooked/` is a human-readable view of every cooked asset
Ravenswatch ships. Generated locally, **never committed**, intended
solely as a development reference so modders can see what they're
overriding before they override it.

## What's in there

```
data/uncooked/
    3D/                  characters, scenery, animations
    Audio/               FMOD banksets
    Definitions/         enemies, items, modes, modifiers, achievements
    EntitySettings/      cooked entity property bodies
    Heroes/              hero-specific assets
    Materials/           shader / material defs
    Maps/                level definitions
    Text/                localization GAM XLS dumps
    Ui/                  UI sprites, portraits, menus
    _root/
        DarkTalesResources/
            ApplicationSettings.ot   verbatim copy
            EngineSettings.ini       verbatim copy
            UsedRscList.ot           verbatim copy
    ... ~20 more top-level dirs
```

Totals after a full run on the current build:

| Bucket | Count | Notes |
|---|---|---|
| `.png` (decoded textures) | 4,776 | BC1, BC3, BC5, RGBA8, font atlases |
| `.gen` (cooked binary)    | 15,431 | engine-native, body schemas in `Ravenswatch.exe` |
| `.gen.txt` (sidecar)      | 15,362 | structural dump per .gen (class table + section ranges + embedded strings) |
| `.dxil`                   | 116    | compiled HLSL — no decompiler in repo |
| `.fnb`                    | 6      | proprietary font binary |
| `.ot`                     | 2      | plain oCTextSaver text |
| Root files                | misc   | settings + manifests |
| **Total**                 | **35,696** files, **3.2 GB** |

## How it's built

Two scripts, both idempotent:

```sh
# 1. extract cooked → readable (decodes .tpi/.zux/.nrm textures to PNG,
#    copies the rest raw).
python3 scripts/extract_uncooked.py

# 2. for each .gen file, dump structural decode as a sibling .gen.txt
python3 scripts/decode_gen_sidecars.py
```

Re-run both after a game update. Both walk `data/asset_map.csv` (encoded
↔ decoded path index), so they pick up new assets automatically once
`./rsmm rebuild-asset-map` regenerates the map.

### Texture decoder

`extract_uncooked.py` parses the `oCTexture` (.tpi) / `oCTextureNorm`
(.zux) container header to find width, height, format, and the
pixel-data offset:

```
ff ff ff ff                         end of class table
22 22 bb aa 11 11 bb aa 00 00 00 00 sentinel 1
22 22 bb aa 11 11 bb aa 00 00 00 00 sentinel 2
<extra_mip_count: u32>
<width: u32>
<height: u32>
<unk: u32>
<format: u32>      ← 0=BGRA8, 4=BC1, 5=BC3, 35=BC5 (ATI2)
<mip0_size: u32>
<mip0_size: u32>   duplicate
<pixel data: mip0_size bytes>
[<mip1, mip2, ... if extra_mip_count > 0>]
```

Format 35 is BC5 normal data — only X,Y stored, the script reconstructs
Z = sqrt(1 − X² − Y²) so the saved PNG looks like a real normal map.

### Structural sidecars

`decode_gen_sidecars.py` invokes the existing `rsmm.engine.ot_decoder`
(see `docs/INTERNALS.md` — same module that powers `./rsmm decode`).
For each `.gen` it writes a `.gen.txt` containing:

- header (`//OPROJECT oCTextSaver`, flags, hdr_size)
- class table (every class name + class ID + version)
- section ranges (offset + length)
- every embedded string inside each section

Per-class property bodies stay opaque — the schemas live inside
`Ravenswatch.exe` (`docs/INTERNALS.md` §schema). The sidecars are still
enough to identify *what* each cooked file references (which texture,
which material, which shader, which donor file).

The 69 `*LocalText.gen` files fail decode — they don't use the standard
oCTextSaver class header. Tracked as a follow-up.

## Why it's gitignored

`data/uncooked/` is git-ignored. Two reasons:

1. **Size** — 3.2 GB. Each contributor regenerates it locally.
2. **Copyright** — these are Ravenswatch's own assets in readable form.
   Distributing them is redistribution of game content, not modding.

The same logic applies inside mods. `rsmm pack <id>` SHA1s every file
in `mods/<id>/assets/` and `_root/` against the original cooked asset
(and the `data/uncooked/` mirror). Byte-identical files cause pack to
refuse:

```
$ ./rsmm pack MyMod
refusing to pack MyMod: contains files byte-identical to original game assets ...
  assets/Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt
        (matches original cooked asset)
```

Override with `--allow-vanilla` for personal backups only.

## How modders use the mirror

1. **Find what to override** — grep the tree to discover decoded
   paths.
   ```sh
   find data/uncooked/Ui -name "*Portrait*"
   ```
2. **See what's already there** — open the PNG in any image viewer,
   or read the `.gen.txt` sidecar to see which donor files / shaders
   the asset references.
3. **Author the override** in `mods/<id>/assets/<same/decoded/path>`,
   using either a raw byte replacement or a `[[patch]]` block in
   `manifest.toml` (see `docs/MODDING.md`).
4. **Verify** — `./rsmm apply` swaps the cooked file in place;
   `./rsmm pack <id>` ships only changed bytes.

---

# Web editor

> Build item, talent, ability and map mods in your browser, from your own game files, with nothing to install.

Source: https://docs.rsmm.me/guides/web-editor/

The [web editor](/editor/) is `rsmm editor` running in
your browser. It has the same five tabs (Items, Talents, Scripts, Abilities, Map) and
the same checks, and it saves the same mods. You need no Python, no CLI and no
desktop app to use it. Installing the mod it gives you still takes one of those.

## Using it

1. Open [docs.rsmm.me/editor](/editor/). The first visit
   downloads the Python runtime (about 12 MB); later visits use your browser's
   cache.
2. Choose your Ravenswatch folder. In Steam: right-click **Ravenswatch** →
   **Manage** → **Browse local files**. Choosing `DarkTalesResources` inside it
   works too.
3. Your browser asks whether to "upload" the folder. That is its standard
   wording for letting a page read a folder: the files are read on your
   computer and are never sent anywhere.
4. Make your changes. Where the local editor says *Add to mod*, the web
   editor saves the mod and hands it to you as a `.zip`.
5. Unzip it into your mods folder and apply it with the desktop app, or with
   `rsmm restore --all && rsmm apply`.

## What it can and cannot do

| Tab | In the browser |
|---|---|
| **Items** | everything: pick an item, choose *Replace this item* (change the shipped one) or *Make a copy* (a new item beside it), change name, text, rarity (copies only), icon, values and the stat each effect gives, *Check*, save |
| **Talents** | everything: card names and texts, each card's numbers per rarity, every value and the stat each effect gives, *Check*, save |
| **Scripts** | everything: test grants (items, talents and XP handed out when a run starts), for every hero or one |
| **Abilities** | everything: numbers, the graph, *Save to mod* (by default an in-place edit of the shipped hero, or a separate custom hero built on it, as you choose; saved changes load back when you pick the mod; *New mod…* asks for the same details as the other tabs and makes the mod and its block when you press *Create mod…*; *Open a mod folder…* brings a saved mod back), *Copy manifest code* |
| **Map** | the recipe, the spots, the 3D terrain, and the chapter's scenery and tiles drawn with the game's own models and textures, read from your install |

To keep working on a mod you saved earlier, press *Open a mod folder…* and
pick that mod's folder. The editor reads its `manifest.toml`, its `init.lua` and
its `icons/`, and nothing else. A mod you save here exists only until you close
the tab, so download it before you leave.

### Opening a mod

Choose the mod beside *Save* and press *Open* (in the browser: *Open a mod
folder…*). Each item, talent card and test grant in it comes back as a change in
the bar, ready to edit. *Save to mod* then writes only the changes you made since
opening it, in place of the blocks they came from. Anything else in the
manifest stays exactly as it was: your comments, other blocks, and kinds the
editor does not edit. A block the editor cannot show exactly (a field it has no
control for, a value the base item no longer has) is listed when you open the
mod and left alone. After a save the mod stays open, so you can keep going.

### Test grants (Scripts)

The Scripts tab makes a mod hand you items, talents and XP at the start of every
run, so you can try a change at once instead of waiting for the game to offer
it. For example: 15 Ace of Spades, a Legendary talent, and 5000 XP (level 1 to 4).
Pick a hero under *Only for* and the grants happen only with that hero. Without
it they reach every hero you play, and a test mod left enabled levels up all of
them. Talents are chosen from that hero's own cards.

The grants are written into the mod's `init.lua`, between two marker lines the
editor owns. Code of your own in that file is left alone. They are for testing:
take them out (remove every row and save) before you publish the mod.

The Items and Talents tabs show each card the way the game will, drawn with the
compendium's own frames and fonts read from your install: highlighted words,
numbers, and the value behind every `{0}`, updated as you type. On the Talents
tab each card sits beside its text and numbers; a number that changes with the
card's rarity has one box per rarity, and *Show cards as* switches the previews
between Common, Rare, Epic and Legendary.

Both tabs take your own icon. On the Items tab, *Upload your own icon* gives the
item a picture of its own (scaled to 192×192 and cooked into a new texture
named after the item). On the Talents tab, *Replace icon* swaps a card's picture
(scaled to 128×128 and cooked over that card's icon), which is how a replacement
talent gets a look to match its new name and text. The PNG is saved in the mod's
`icons/` folder next to `manifest.toml`. Each
change has an undo button (↺), *Reset this item* / *Reset this hero* drops every
change to the one that is open, *Reset everything* (in the bar at the bottom)
drops every pending change in every tab after you confirm, and an unfinished edit is kept in your browser until you add it to a
mod (a dot marks it in the list). Private windows and some browsers do not keep
it.

It works in current Chrome, Edge, Firefox and Safari on a computer. Phones
cannot choose a folder.

## How it works

The page runs the real `rsmm` Python package in a
[Pyodide](https://pyodide.org) worker: the same code as the CLI, built from the
same commit as these docs. Each editor tab is the page `rsmm editor` serves
locally. Its requests go to the worker instead of a local server, and are
answered by the same routes (`rsmm.cli.editor`).

The folder you choose is mounted read-only, and each file is read only when
the engine opens it. Building the item list reads about a megabyte of a
multi-gigabyte install. The asset map is rebuilt from your own
`DarkTalesResources/UsedRscList.ot`, so the site hosts no game files at all.

---

# Ravenswatch Mod Manager

> Install, manage and make mods for Ravenswatch. Free, open source, for Windows, Linux and Steam Deck.

Source: https://docs.rsmm.me/

import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';

## Play with mods

<CardGrid>
  <Card title="1. Install the app" icon="download">
    Download it for Windows, Linux or Steam Deck. No commands to type.
    [How to install →](/getting-started/install/)
  </Card>
  <Card title="2. Pick some mods" icon="magnifier">
    Browse mods shared by the community and install one with a single click.
    [Using the app →](/getting-started/desktop-app/)
  </Card>
  <Card title="3. Press Launch Modded" icon="rocket">
    The game starts through Steam with your mods switched on.
  </Card>
  <Card title="4. Back to normal any time" icon="approve-check">
    When you quit, RSMM puts the original game files back. **Launch Vanilla** plays
    without mods.
  </Card>
</CardGrid>

## Make mods

<CardGrid>
  <Card title="In your browser" icon="laptop">
    Change items, talents and abilities with the [web editor](/editor/). Nothing to
    install.
  </Card>
  <Card title="With the modding tools" icon="pencil">
    Change looks, numbers, text and add new content with a short text file. Add
    Lua scripts for new gameplay.
  </Card>
</CardGrid>

<CardGrid>
  <LinkCard title="Make your first mod" href="/getting-started/first-mod/" description="A beginner walkthrough, from nothing to your change in the game." />
  <LinkCard title="Example mods" href="/guides/examples/" description="Complete mods to copy and change." />
  <LinkCard title="Coming from Minecraft?" href="/concepts/from-minecraft/" description="How Forge and Fabric ideas map to RSMM." />
  <LinkCard title="Modding guide" href="/guides/modding/" description="Everything a mod can do, in detail." />
</CardGrid>

## Need help?

<CardGrid>
  <LinkCard title="Frequently asked questions" href="/getting-started/faq/" description="Safety, co-op, Steam Deck, saves and game updates." />
  <LinkCard title="Troubleshooting" href="/getting-started/troubleshooting/" description="Fixes for the most common problems." />
</CardGrid>

RSMM is free and open source. If you'd like to support it, you can
[buy the developer a coffee on Ko-fi](https://ko-fi.com/W7W41FW3YE).

---

# CLI reference

> Every rsmm subcommand and what it does.

Source: https://docs.rsmm.me/reference/cli/

All commands are run via the `rsmm` entry point:

```sh
./rsmm <command> [options]     # Linux
rsmm <command> [options]       # Windows
```

Commands that take a mod id (`enable`, `disable`, `lint`, `diff`, `pack`, `publish`,
`test`) accept the folder name under `mods/` in any case, with the trailing slash tab
completion adds, or as a path (`mods/MyMod`). A misspelled id or subcommand gets a
"did you mean …?" instead of a list.

---

## Core commands

### `rsmm apply`

Install all enabled mods into the game directory. Backs up originals, applies patches, and merges `[[patch]]` blocks from `manifest.toml`.

```sh
./rsmm apply
./rsmm apply --game-dir /custom/path
./rsmm apply --verbose        # list every file installed, restored or registered
```

By default it prints one line per mod (`+ nyx  installed 359 file(s), 345 new`)
plus any warnings, merges and errors, with a live counter while it works on a
terminal. `-v` / `--verbose` (or `RSMM_VERBOSE=1`) lists every file instead;
`restore --all` follows the same rule. Warnings raised while a mod's content is
built name that mod (`[warn] custom-hero-test: custom mesh does not overlap…`).

Rollback: `./rsmm restore --all`

### `rsmm list`

Show installed mods and their status.

```sh
./rsmm list
```

### `rsmm doctor`

Health check, and the repair path for what it finds. Run this often — it is the
first thing to try when something "just doesn't work".

```sh
./rsmm doctor                      # report only (never writes)
./rsmm doctor --fix                # run the safe repairs, then re-check
./rsmm doctor --fix --force        # also run destructive repairs
./rsmm doctor --only loader        # one section; --only list names them all
./rsmm doctor --json               # machine-readable findings
```

Findings carry a stable `code` and, where one exists, the exact rsmm command
that repairs them. `--fix` runs those repairs and then re-runs every check, so a
repair is only reported as fixed when the check actually goes green.

| Flag | Meaning |
|------|---------|
| `--fix` | Run each finding's automated repair (`apply`, `install-loader`, `rebuild-asset-map`, `update-data`). Repairs are ordinary rsmm commands — doctor never reimplements one. |
| `--force` | With `--fix`, also run repairs that roll the install back or delete installed files (`restore --all`). |
| `--only CHECK` | Restrict to named checks; repeatable. `--only list` prints them. |
| `--json` | Structured report: per-finding kind, code, detail, and whether a repair is automatic. |
| `--game-dir` | Point at a non-default install. |

Plain `doctor` is read-only on purpose: a health check that silently rewrites a
game install on every run is a footgun, so repairs are opt-in.

What it covers: game install reachable and writable, asset map freshness, game
version drift, the loader (DLL bytes by hash, the disk-loaded Lua SDK under
`<game>/rsmm/lib`, the planted pattern DB, dangerous feature flags left armed,
and — on Proton — whether Steam's launch options still carry the
`WINEDLLOVERRIDES` the loader needs), mod manifests and asset paths, raw-file
and `[[patch]]` conflicts, whole-file overrides a declarative block could
replace, the dependency graph, applier state versus what is actually on disk,
`UsedRscList.ot` record alignment, and recent crash dumps.

A whole-file override is a mod shipping a complete game file where a
`[[patch]] kind = "stat"` (stat files), `[[patch]] kind = "ot"`
(`ApplicationSettings.ot` via `_root/`) or `[[content]] kind = "talent"` (hero
talent values) would do. The copy works, but it cannot merge with another mod
and it silently reverts whatever the next game patch changes in that file.
`rsmm lint <id>` prints the replacement block. It only offers one it has proven:
the block is parsed back and run through the same code `apply` uses, and must
rebuild the mod's file byte for byte. Without a readable game copy it names the
route but cannot write the block.

:::tip
A planted `winhttp.dll` is only half an install. The Lua SDK and pattern DB are
loaded from `<game>/rsmm/`, and a Steam update replaces the DLL while deleting
that tree — which looks exactly like "the loader is broken". Doctor checks all
three.
:::

### `rsmm run`

Launch Ravenswatch from the CLI.

```sh
./rsmm run
./rsmm run --game-dir /custom/path
```

### `rsmm watch`

Re-apply mods automatically whenever a file changes under `mods/`. Keeps running in the background.

```sh
./rsmm watch
./rsmm watch --no-lint             # apply even when a changed mod has lint errors
```

Each save prints which mods and files changed, then lints those mods before applying. A
changed mod with lint errors is not applied: the errors are printed and the game keeps the
last good apply until you fix them and save again. Without that, a manifest caught
half-written would be skipped by `apply`, which takes the mod out of the game until the
next save. Files `apply` writes itself (emitted content, its caches, `mods/_merged/`) and
editor swap files don't count as changes.

### `rsmm restore`

Restore original game files. Reverses `rsmm apply`.

```sh
./rsmm restore --all               # Restore everything
./rsmm restore --mod MyMod         # Restore files for one mod
```

### `rsmm log`

Read the loader log file (`<game>/mods/_log.txt`).

```sh
./rsmm log                         # Full dump
./rsmm log -n 80                   # Last 80 lines
./rsmm log -f                      # Follow live (Ctrl-C to stop)
./rsmm log --grep lua              # Filter (case-insensitive)
./rsmm log --clear                 # Clear the log before a fresh launch
```

### `rsmm overlay`

Read the live HUD data a mod publishes. Overlays are **declared by mods** (an
`[overlay]` block in `manifest.toml`) and filled at runtime with
`R.overlay.publish` — the client hardcodes none of them.

```sh
./rsmm overlay                     # every installed mod that declares one
./rsmm overlay damage-meter        # that mod's board
./rsmm overlay damage-meter -w     # live, e.g. on a second monitor
./rsmm overlay damage-meter --json # machine-readable
```

Columns, sorting and the highlighted row come from the declaration, so the
terminal view and the desktop app's overlay window show the same thing.

---

## Mod management

### `rsmm new <id>`

Scaffold a new mod directory:

```sh
./rsmm new MyMod
# Creates: mods/MyMod/manifest.toml

./rsmm new MyMod --kind item        # also seeds a [[content]] block
./rsmm new MyMod --desc "Faster dodges" --tags balance,heroes --license MIT
```

The author comes from `--author`, else your `git config user.name`. Fill in
`--desc`, `--tags` and `--license` too and the new mod passes `rsmm lint` with no
warnings; leave them out and the scaffold says what is still missing.

`--kind` takes `item`, `talent`, `enemy`, `boss`, `map` or `hero`. Kinds that
aren't confirmed are scaffolded with `experimental = true` and `enabled = false`.

For `--kind item` the block is read out of the base you clone rather than
templated — its icon, rarity and every patchable value field with its true
current value, so the scaffold applies without hand-editing:

```sh
./rsmm new IronCrabHide --kind item --base Common/Armor_Per_Object \
    --name "Iron Crab Hide" --desc "Bonus armor per rare object."
```

| Flag | Meaning |
|------|---------|
| `--base ID` | Vanilla id to clone. Bare (`Armor_Per_Object`) or rarity-qualified (`Common/Armor_Per_Object`). Omit it at a terminal to get a searchable picker. |
| `--name TEXT` | Display name for the mod and its content. |
| `--desc TEXT` | Description shown in-game and on the store card. |
| `--icon ID` | Vanilla icon stem (`rsmm items icons`) or `assets/<file>.png`. Defaults to the base's own icon. |
| `--rarity R` | `Common`, `Rare`, `Epic`, `Legendary`, `Cursed` or `Powerups`. Defaults to the base's rarity. |
| `--author NAME` | Who made it. Defaults to `git config user.name`. |
| `--tags a,b` | Store tags, comma-separated: lower-case letters, digits and `-`, at most 16. |
| `--license ID` | SPDX id (`MIT`, `CC-BY-4.0`) or a licence name. |

See [Custom items](/guides/custom-items/) for the full walkthrough.

### `rsmm pack <id>`

Package a mod for distribution. Verifies no vanilla (unmodified game) bytes are included.

```sh
./rsmm pack MyMod                  # Writes dist/MyMod.zip
./rsmm pack MyMod --allow-vanilla  # Skip vanilla-byte check (personal backups only)
```

### `rsmm publish <id>`

Upload a mod to the store in one command: lint, pack (with the vanilla-byte
check), upload with its checksum, queue the malware scan, and wait until the
version is live. A version can only be downloaded once its scan comes back
clean; that gate is on the server and a token cannot skip it.

```sh
./rsmm publish login        # paste a token from rsmm.me/account (input hidden)
./rsmm publish whoami       # which account the token publishes as
./rsmm publish MyMod        # pack, upload, scan, wait until live
./rsmm publish MyMod --no-wait
./rsmm publish logout
```

Create the token on your account page under **API tokens**. It is shown once,
and it can publish new versions of **your own** mods and nothing else. It cannot
change your account, create more tokens, delete mods or moderate. Every token
expires (30 days to a year), you can hold ten at a time, and you get an email
whenever one is created.

The CLI reads the token from `RSMM_API_TOKEN` or from the file `login` writes
(`~/.config/rsmm/credentials.json`, `%APPDATA%\rsmm\credentials.json` on
Windows, owner-only permissions). There is deliberately no `--token` flag,
because command arguments end up in shell history and the process list. It
refuses to send a token anywhere but HTTPS (plain HTTP only for `localhost`).
If a token may have leaked, revoke it on the account page. Revocation takes
effect on the next request.

| Failure | Meaning |
|---|---|
| `the API token was rejected` | Revoked, expired, or the account is not verified. Make a new one. |
| `version … is already published` | Bump `[mod].version` in `manifest.toml`. |
| `this mod slug belongs to another account` | Someone else owns that id. Rename the mod. |
| `upload rate limit reached` | Five uploads per hour per account. |
| `the malware scan came back flagged` | The version stays unavailable. Report it if you think it is a false positive. |

### `rsmm install-loader`

Copy the loader DLL (`dist/winhttp.dll`) into the game installation directory.

```sh
./rsmm install-loader
```

---

## Asset editing

### `rsmm assets search <text>` / `rsmm assets show <path>`

Find a cooked asset by its readable path. The install holds ~43,000 files
whose names are cipher-encoded, so `ls` and `grep` cannot answer "where does
the wolf enemy live" — but `data/asset_map.json` already carries the whole
decoded ↔ encoded mapping (derived from the engine's `UsedRscList.ot`), so
this is a lookup, not a scan. No game install required.

```sh
./rsmm assets search wolf                  # every readable path containing "wolf"
./rsmm assets search enemies wolf          # both terms, any order (ANDed)
./rsmm assets search "Ui/*.png"            # glob when the term has * or ?
./rsmm assets search wolf --encoded -n 0   # print on-disk names too, no limit
./rsmm assets show Audio/Music.bank        # encoded name + install state
```

Terms are case-insensitive and accept either slash direction. `show` also
answers for the two families that are in no manifest because the engine
ciphers them by convention — `Audio/*.bank` and `*.UsedRscCache.ot` — and
reports whether the installed copy is vanilla or currently overridden by a
mod.

### `rsmm decode <file>`

Structural dump of a cooked file (class table, sections, embedded strings).

```sh
./rsmm decode path/to/cooked.gen
./rsmm decode path/to/cooked.gen --raw   # Include hex payloads
```

### `rsmm uncook <file>`

Extract a cooked asset to an editable source-format file. Per-class schemas
are reversed-engineered incrementally (see `docs/RE_NOTES.md`); when the
schema isn't ready yet, `--raw` extracts section bytes directly so byte-level
mods are unblocked.

```sh
./rsmm uncook path/to/cooked.yqz                # uncook to source format (schema-dependent)
./rsmm uncook path/to/cooked.yqz --info         # print container header + class table
./rsmm uncook path/to/cooked.yqz --raw          # dump all section payloads to <name>.raw
./rsmm uncook path/to/cooked.yqz --raw --section 3 -o sec3.bin
```

### `rsmm cook --from <reference> <source>`

Pack a source asset into a cooked Ravenswatch file. Until per-class encoders
land, `--from <reference.yqz>` is required: the reference supplies the
container header + class table + version. `--raw` substitutes the input
bytes verbatim as section payload, giving a byte-level edit path today.

```sh
# Round-trip section 3 byte-identically:
./rsmm uncook --raw --section 3 ref.yqz -o sec3.bin
./rsmm cook   --raw --from ref.yqz --section 3 sec3.bin -o out.yqz

# Once schemas land, cook from source format:
./rsmm cook --from ref.yqz model.gltf -o out.yqz
```

### `rsmm editor`

One local page with four editors, each on its own tab. Each one reads your own
install when the page asks for something, and each saves an ordinary mod that
`rsmm apply` installs. Nothing from the game is bundled with the editor. The
same editors also run in the browser with no install:
[the web editor](/guides/web-editor/).

| Tab | What it builds |
|---|---|
| **Items** | a copy of a shipped magical item with its own id, name, text, rarity, icon, values and the stat each effect gives (`kind = "item"`) |
| **Talents** | changed talent values (`kind = "talent"`, one block per entity file) and renamed talent cards (`kind = "skill"`) |
| **Abilities** | `[[content.abilities]]` steps for a custom hero: every number an ability uses, plus a graph for re-pointing links and copying parts |
| **Map** | a chapter's map-generation recipe (`kind = "tilegen"`) on a 3D view of its terrain |

```sh
./rsmm editor                      # serve on 127.0.0.1:8765 and open a browser
./rsmm editor --tab map            # open on another tab: items, talents, abilities, map
./rsmm editor --port 9000          # pick the port (falls back to a free one)
./rsmm editor --no-browser         # just print the URL
./rsmm editor --game-dir "D:\SteamLibrary\steamapps\common\Ravenswatch"   # when it isn't found
./rsmm restore --all && ./rsmm apply   # install what you saved
```

`item-editor`, `talent-editor`, `ability-editor` and `map-editor` still work:
each opens this editor on its tab.

The tab bar names the install the editor reads. When none is found, every tab
says so and shows the `--game-dir` command to start it with; the folder can be
Ravenswatch itself or `DarkTalesResources` inside it (`RSMM_GAME_DIR` works
too). A dot on a tab means it holds changes that are in no mod yet. Item,
talent, test-grant and ability changes are kept in your browser until you save
them; Map changes are not, so closing the page with unsaved Map changes asks
first.

**Items and Talents.** *Check* builds the blocks with the real kind builders,
so it reports exactly what `rsmm apply` would refuse. *Add to mod* appends them
to a mod's `manifest.toml`, or creates the mod. An item copy's id must be as
long as its base's: the copy keeps every byte offset. A hero's number of
talents is fixed, so the Talents tab edits existing talents rather than adding
new ones.

**Abilities.** The page never writes a mod: press *Copy manifest code* and paste
the steps under your custom hero's `[[content]]` block (`kind = "hero"`).

**Map.** The page shows every tile slot of a chapter on a 3D (or top-down) view of
its painted terrain: height, design paths, blocked ground and water. Each slot
is coloured by whether the selected tile can land there in the selected
scenario. You can change how many of each tile kind the generator places,
their minimum spacing, which footprints each kind fits, the per-flag quotas,
and which kinds each slot may hold. Saving writes `mods/<id>/manifest.toml` with
one `tilegen` declaration, which reopens in the editor. The `tilegen` kind is
⚠️ experimental: the recipe round-trips byte-identically, but an edited recipe
has not yet been shown to change what generates.

The server answers only loopback hosts, and every write needs a token that
exists only in the pages it served.

### Numeric values and texture swaps

There is no dedicated command for these. A mod declares them as `[[patch]]`
blocks in its manifest (or with `m.stat(...)` from the SDK), and `rsmm apply`
merges every enabled mod's patches — see
[Numeric balance](/guides/modding/#numeric-balance--modifier--camp-difficulty)
and [Texture swap](/guides/modding/#texture-swap-donor-reference). Find the
names with `rsmm assets search`:

```sh
./rsmm assets search globalvalue Bleed     # a global value: Bleed_Duration_Value
./rsmm assets search enemycampdifficultydef  # camp difficulty bands (Easy, …)
./rsmm assets search Heroes Portrait png   # texture paths
```

### `rsmm values` — back up a patch before a game update

A game update rebalances values in place, and afterwards the old ones exist
nowhere: the update overwrites the files `apply` backed up from. Take a
snapshot while the current patch is still installed:

```sh
./rsmm values snapshot                     # saves <date>-build<steam build id>
./rsmm values list
./rsmm values diff 2026-10-01-build23766761              # vs the install now
./rsmm values diff <old> <new> --filter Snow_Queen       # two snapshots
./rsmm values extract <old> EntitySettings/Heroes/Hero_Snow_Queen/Hero_Snow_Queen_Ice_Clone.entity.ot.EntitySettingsResource.gen -o old.gen
```

A snapshot holds every entity field as the editors show it, each magical
object's values and modifiers, and the pristine cooked bytes of
`EntitySettings/`, `Definitions/` and `GlobalValues/` (about 9 MB). It is read
from the install, never the authoring mirror, and stored in the per-user data
directory (`~/.local/share/rsmm/snapshots`, `%LOCALAPPDATA%\rsmm\snapshots`),
so `restore --all` and Steam's file check leave it alone.

---

## Debugging

### `rsmm doctor`

See [Core commands](#core-commands).

### `rsmm apply --dry-run`

Show which cooked files the enabled mods would change, touching nothing.
See [`rsmm apply`](#rsmm-apply).

```sh
./rsmm apply --dry-run
```

### `rsmm diff <id>`

Show what applying one mod changes, without touching anything. Every file the
mod ships is listed as replacing a game file (`~`), adding a new one (`+`), or
being skipped because no game path can be derived for it (`?`). A file another
enabled mod also writes is marked as merged (text banks, tile pools, resource
caches and alias tables combine) or as a conflict naming the mod whose copy
lands. `[[patch]]` fields set to a different value by another mod say which one
wins under `load_order`. When the game is found, the summary also counts files
that are installed and files that still need `rsmm apply`.

```sh
./rsmm diff my-mod            # first 15 files per section; conflicts always shown
./rsmm diff my-mod --all      # every file
./rsmm diff my-mod --json     # for scripts
```

### Reading the loader log

Read the loader log of the last game launch. See [`rsmm log`](#rsmm-log).

### `rsmm decode <file>`

See [Asset editing](#asset-editing).

---

## Common workflows

| Goal | Commands |
|---|---|
| First-time setup | `./rsmm doctor` |
| Install all mods | `./rsmm apply` |
| Iterate on a mod | `./rsmm watch` (runs in background) |
| Package for sharing | `./rsmm pack MyMod` |
| Roll back everything | `./rsmm restore --all` |
| Launch the game | `./rsmm run` |

---

## Global options

| Flag | Description |
|---|---|
| `--game-dir <path>` | Custom Ravenswatch installation path |
| `--help` | Show help for any command |
| `--version` | Show RSMM version |

---

# Conventions & best practices

> Mod structure, naming, and the confidence gate — the rules that keep mods shippable.

Source: https://docs.rsmm.me/reference/conventions/

Follow these and `rsmm lint` stays green and your mod survives game updates.
They mirror the "best practices" pages every mature Minecraft loader ships.

## Mod structure

```
mods/<id>/
  manifest.toml        # the only required file
  assets/
    <decoded path>/...  # overrides, e.g. Ui/.../Portrait.png.Texture.dxt
  lang/<locale>.toml    # optional i18n
  tags.json             # generated by Mod.tag(...)
```

- **One id, one directory.** `id` in `manifest.toml` must match the folder
  name and be unique across the user's mods.
- **Forward slashes in decoded paths.** Always, regardless of OS.
- **No stray `.py`.** The deliverable is data. See
  [Mods ship data, not code](/concepts/data-not-code/).

## Naming

- **Mod `id`** — stable, namespaced-feeling, no spaces (`RubyBlades`, not
  `Ruby Blades`). Renaming it orphans a user's applied state.
- **Content ids** — unique within the mod per kind. Prefer descriptive names
  over vanilla collisions (`RubyDagger`, not `Knife`).
- **Tags** — lower-kebab, topic-first (`daggers`, `fire-immune`).

## The confidence gate

Every content kind is `confirmed`, `experimental`, or `guess`
([details](/concepts/content-kinds/)).

:::caution
Non-`confirmed` kinds require `sdk.Mod(..., experimental=True)`. Don't ship an
`experimental`/`guess` mod to other users without testing it in-game — the
emitted bytes are not verified and may not appear or may crash.
:::

## Surviving game updates

- Address engine functions by **name** (`R.call("Name")`), never by raw
  address — the [symbol map](/concepts/mappings/) re-resolves by byte pattern.
- Declare `target_game_build` in your manifest so RSMM can warn on drift.
- Prefer `[[patch]]` over whole-file overrides where possible: patches merge
  and are far more update-resilient than replacing a whole cooked file.

## Distribution

- Ship a `repo.json` with SHA256 (and optional Ed25519 signature) so users can
  verify downloads — see the [`repo` SDK reference](/reference/sdk-api/repo/).
- No central host is required; the spec is open.

## Pre-flight checklist

- [ ] `rsmm lint` passes (no stray scripts, confidence gate satisfied).
- [ ] `rsmm apply` then launch the game — content actually appears.
- [ ] `rsmm restore --all` returns to vanilla cleanly.
- [ ] `manifest.toml` has `id`, `name`, `version`, `author`, `description`.

---

# Glossary

> Plain-language meanings of the words used in RSMM and these docs, from "vanilla" to "cooked asset".

Source: https://docs.rsmm.me/reference/glossary/

What the words in these docs mean. The first section is for everyone. The later
sections are for mod makers and people digging into how the game works.

## Everyday words

- **Mod** — short for *modification*: an add-on that changes something in the
  game, such as how a hero looks, how strong an item is, or what the text says.
- **Vanilla** — the game exactly as it comes from Steam, with no mods.
- **RSMM** — Ravenswatch Mod Manager: the app, the website
  [rsmm.me](https://rsmm.me/registry), the web editor and the `rsmm` modding
  tools, together.
- **Registry** — the list of mods shared on rsmm.me. The app's **Browse** page
  shows it.
- **Apply** — write your switched-on mods into the game's files, keeping a copy of
  each original first. The app does this for you when you press **Launch
  Modded**.
- **Restore** — put the original game files back, undoing every mod.
- **Launch Modded / Launch Vanilla** — the app's two play buttons: start the game
  with your mods, or without any.
- **Profile** — a saved set of mods you can switch between. The **Default**
  profile is always the plain game.
- **Enabled / disabled** — whether a mod is switched on in the current profile. A
  disabled mod stays on your computer but isn't used.
- **Load order** — the order mods are applied in. When two mods change the same
  thing, the one applied later wins.
- **Conflict** — two switched-on mods that change the same file.
- **Dependency** — another mod a mod needs in order to work. A missing one shows as
  *missing deps*.
- **Config** — a mod's own settings, changed with its settings button in the app.
- **Overlay** — a small window some mods show on top of the game, like a damage
  meter.
- **Script mod / Lua mod** — a mod that includes a small program written in the
  Lua language, which runs inside the game. Most mods are not script mods.
- **Loader** — a small file (`winhttp.dll`) RSMM puts next to the game so that
  script mods can run. Mods that only change looks, numbers or text don't need it.
- **Experimental** — a kind of change RSMM doesn't fully understand yet. It may not
  work completely, and may crash the game.
- **Doctor** — RSMM's health check. In the app: **Commands → Doctor**. In a
  terminal: `rsmm doctor`.
- **Terminal / command line / CLI** — a window where you type commands instead of
  clicking. Only needed for the modding tools.
- **Web editor** — a page on this site that makes item, talent and ability mods in
  your browser. See [Web editor](/guides/web-editor/).

## Mod-making words

- **`manifest.toml`** — the text file at the heart of every mod. It says what the
  mod is called and what it changes.
- **`[[content]]` block** — a section of the manifest that adds or changes one
  thing, such as an item or an enemy.
- **`[[patch]]` block** — a section of the manifest that changes one value, such
  as a number. Several mods can patch different values of the same file without
  clashing.
- **Kind** — what a `[[content]]` block changes: `item`, `talent`, `enemy`,
  `map` and so on.
- **Base** — the existing game thing a new one is copied from, or the one being
  changed.
- **Lint** — `rsmm lint`: checks a mod for mistakes before you play.
- **Pack** — `rsmm pack`: bundles a mod into one `.zip` file to share.
- **Publish** — upload a mod to rsmm.me so others can install it.

## Assets & cooking

- **Cooked asset** — a game-ready binary baked from a source ("uncooked") asset. Ravenswatch loads everything from `<install>/DarkTalesResources/_Cooking/`. RSMM mods replace cooked files in place.
- **Uncooked asset** — the pre-bake source form (e.g. a PNG before it becomes a `.Texture.dxt`). The `data/uncooked/` mirror is decoded for local reference and is git-ignored.
- **`.gen` file** — a cooked binary that is *positionally serialized* against a per-class schema living inside `Ravenswatch.exe`. Building one from scratch needs the text-`.ot` → binary-`.gen` re-encoder.
- **`.ot` file** — the text/structured form of a cooked object (header + class table + section ranges). The `.ot` decoder parses these.
- **Encoded path / IYG cipher** — cooked files live under obfuscated names: the plaintext path run through a fixed Caesar substitution cipher (`src/rsmm/engine/cipher.py`, `find_iyg.py`). `asset_map.json` maps decoded ↔ encoded.
- **`asset_map.json`** — generated map of every decoded path to its encoded cooked path. Built by walking `UsedRscList.ot` and applying the cipher.
- **`UsedRscList.ot` / `UsedRscCache.ot`** — engine manifests of which resources are cooked. New custom assets register through these.

## Applying & lifecycle

- **Apply** — `./rsmm apply`: copy a mod's overrides into the game, backing up each original as `<file>.rsmm.bak`. Reversible with `./rsmm restore --all`.
- **Patch vs raw** — a mod changes the game either by dropping whole cooked files (**raw**) or by composing declarative `[[patch]]` blocks the applier merges per file (**patch** — conflict-friendly).
- **`manifest.toml`** — the one artifact every mod ships: metadata plus `[[content]]` / `[[patch]]` blocks. Mods ship *data, not code*.
- **Content kind** — a typed builder (`item`, `enemy`, `boss`, `hero`, `map`, `texture`, …) that clones a vanilla **base** and emits a new definition. Each carries a confidence: `confirmed`, `experimental`, or `guess`.

## Entities & gameplay state

Covered end to end in [Anatomy of an entity](/reverse-engineering/entity-anatomy/).

- **Entity (`oCEntity`)** — the world object: hero, enemy, barrel, shrine, dropped item. It holds a transform, links to the scene and its definition, and a map of components — almost no gameplay state of its own.
- **Component** — what gives an entity behaviour. 188 classes; a component is found by *asking its class*, never at a fixed offset on the entity.
- **`…Settings` / `…NetworkData` / `…PersistentData`** — the three companion classes a component can have: the authored data a mod edits, the slice that replicates to other players, and the slice that survives a chapter transition.
- **Definition (`oCEntitySettings`)** — the cooked template an entity is built from. Mods edit definitions; the engine builds instances.
- **HitPoint component** — where health actually lives (current and max). Every damageable entity has one, enemies included. HP is host-authoritative in co-op.
- **Entity value** — a gameplay number in the generic keyed store (attack power, cooldowns, status stacks — ~221 of them). Stored as *base + folded modifiers*, so a raw write is discarded on the next recompute; a durable change must be a modifier.
- **Hit data (`oCEntityHitData`)** — the object an attack travels as. There is no "deal N damage" call; the struct is built inline by the resolver, so mods ride an existing attack rather than fabricating one.
- **Display cache** — the numbers the in-run stat strip prints. A separate copy from the value store, refreshed only when the engine folds a modifier, which is why a working stat change can still show as `0`.

## Engine internals

- **oCEntity / oCEntitySettings** — the engine's entity object and its serialized settings tree. UI pages, enemies, items — all entities composed of component classes.
- **Symbol map** — `data/symbols.json`: the canonical name → address map for engine functions/globals/events. See [Engine symbols](/reference/symbols/).
- **Pattern resolver** — byte-signature database (`function_patterns.json`) that re-finds a function across game updates so mods can call it by name (`rsmm.call`).
- **Loader DLL** — `winhttp.dll` proxy + MinHook + Lua VM injected into the game for Lua-scripted mods (Windows). Texture/asset mods work without it.
- **Anti-tamper / protector** — the protector in `Ravenswatch.exe`. It does not block hooks at function entries; asset mods avoid the runtime path entirely and the loader hooks carefully.  See [Anti-tamper protector](/reverse-engineering/protector/).

---

# SDK API reference

> Generated symbol-level reference for the rsmm.sdk Python API.

Source: https://docs.rsmm.me/reference/sdk-api/

# SDK API reference

Generated reference for the `rsmm.sdk` Python API (API version **1.0.0**). One page per submodule, built from `@sdk_export` registrations.

:::tip[New to the SDK?]
Start with the [Authoring mods guide](/guides/modding/) and the [SDK design notes](/guides/sdk/). This section is the exhaustive symbol-level reference.
:::

## CLI

- [CLI command inventory](/reference/sdk-api/cli/) — every `rsmm` subcommand.

## Content kinds

- [Content kinds & confidence](/reference/sdk-api/kinds/) — every kind, its rating, and its builder.

## Modules

- [`rsmm.sdk.builder`](/reference/sdk-api/builder/)
- [`rsmm.sdk.config`](/reference/sdk-api/config/)
- [`rsmm.sdk.content`](/reference/sdk-api/content/)
- [`rsmm.sdk.health`](/reference/sdk-api/health/)
- [`rsmm.sdk.i18n`](/reference/sdk-api/i18n/)
- [`rsmm.sdk.repo`](/reference/sdk-api/repo/)
- [`rsmm.sdk.testkit`](/reference/sdk-api/testkit/)

---

# rsmm.sdk.builder

> Mod-builder used by `from rsmm import sdk; with sdk.Mod(...) as m:`.

Source: https://docs.rsmm.me/reference/sdk-api/builder/

# rsmm.sdk.builder

Mod-builder used by `from rsmm import sdk; with sdk.Mod(...) as m:`.

Collects config/i18n/content/dependency declarations in memory, then
materializes the whole mod on `__exit__`. One transactional write per
mod build avoids half-built mod trees on the disk.

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `Mod`

### `Mod.asset`

```python
Mod.asset(self, decoded_path: 'str', source: 'str | Path') -> 'None'
```

Stage a source asset to override the game file at `decoded_path`.

`decoded_path` is the plaintext asset path as it appears in
`data/asset_map.json` (forward slashes), e.g.
``3D/Characters/Heroes/Melusine/Textures/T_Melusine_ALB.png``.
The file is copied verbatim into ``mods/<id>/assets/<decoded_path>``;
`rsmm apply` auto-cooks source formats (.glb/.png/.dds/...) into the
cooked container and installs them. Pre-cooked inputs pass through.

### `Mod.boss`

```python
Mod.boss(self, id: 'str', *, base: 'str', becomes: 'str | None' = None, **fields)
```

Make the arena of boss ``base`` spawn boss ``becomes`` instead.

### `Mod.enemy`

```python
Mod.enemy(self, id: 'str', *, base: 'str', name: 'str | None' = None, **fields)
```

Register a custom enemy cloned from vanilla ``base``.

### `Mod.hero`

```python
Mod.hero(self, id: 'str', *, base: 'str', name: 'str | None' = None, abilities: 'list | None' = None, **fields)
```

Register a custom hero cloned from vanilla ``base``.

### `Mod.item`

```python
Mod.item(self, id: 'str', *, base: 'str', name: 'str | None' = None, **fields)
```

Register a custom item cloned from vanilla ``base``.

### `Mod.map`

```python
Mod.map(self, id: 'str', *, base: 'str', **fields)
```

Register a custom map/level cloned from vanilla ``base``.

### `Mod.model`

```python
Mod.model(self, decoded_path: 'str', source: 'str | Path', rotate_deg: 'tuple[float, float, float] | None' = None, scale: 'float | None' = None, skin: 'str | None' = None, fit: 'str | None' = None, submeshes: 'str | None' = None, bones: 'dict[str, str] | None' = None, drop_bones: 'list[str] | None' = None) -> 'None'
```

Override a mesh asset. Source must be a `.glb`/`.gltf`.

A custom mesh is cooked at apply-time by retargeting it onto the
game asset's skeleton (`engine.geometry_cook`). It is auto-scaled and
recentered into the original's space; orientation defaults to an
auto-upright guess (tallest axis -> up). If the mesh comes out turned
or upside down, pass `rotate_deg=(x, y, z)` — a rigid rotation in
degrees applied before the fit (e.g. `(90, 0, 0)` to flip upright,
`(0, 180, 0)` to face the other way).

The auto-fit matches only the tallest axis, so a mesh with a
different aspect ratio than the original can come out too big or
small. Pass `scale=` to multiply the auto-fit (e.g. `scale=0.5` to
halve it).

**Replacing a SKINNED mesh — a character, not a prop — has one rule
the fit cannot do for you: author your mesh in the original's bind
pose.** The cooker has no bones of yours to use; it keeps the game's
skeleton and gives each of your vertices the weights of the game
vertices nearest to it. That copy is positional, so an arm vertex
that lands nearest a leg bone gets weighted to the leg, and the model
tears itself apart the moment it animates. Line the limbs, head and
torso up with the original in Blender before exporting.

`skin="rigid"` binds the whole mesh to a single bone instead: it
follows the character but never deforms. Right for a prop or a static
shape carried by a character, wrong for a body.

`skin="gltf"` uses the weights in your OWN `.glb` — the way to replace
a character properly. Rig the mesh to the game's skeleton in Blender
(the bone names have to match the original's) and export with the
armature; bones are then bound by name and nothing is guessed from
proximity, so the bind-pose rule above stops applying. It implies
`fit="rig"` (no scale, no recentre), because a mesh rigged to the
game's skeleton is already in the right place. `bones={"mine": "theirs"}`
renames on the way in, for a rig that came from elsewhere.

`drop_bones=[...]` deletes the geometry a bone drives — for a donor
body carrying something that has to become a separate object, like a
chain or a slung weapon. Needs `skin="gltf"`, since only your own
weights say which bone owns which triangle.

`fit="none"` keeps the mesh's own size rather than matching the
original's height — what a structure usually wants, since its donor is
a mounting point rather than a size reference. `fit="rig"` goes
further and does not move the mesh at all.

`submeshes="map"` lays your submeshes onto the original's one for one
instead of merging them all into the first. A character is usually
several submeshes because each one draws with a different material, and
merging leaves the rest as empty stubs — so everything renders with the
first material and your second texture never appears. The pairing is by
order, so order your objects in Blender to match the original's.

### `Mod.ot`

```python
Mod.ot(self, selector: 'str', field: 'str', value, *, file: 'str | None' = None, selector_field: 'str | None' = None) -> 'None'
```

Change one field of a plaintext ``.ot`` the game ships uncooked.

``selector`` picks the block by its ``m_sLabel`` (pass
``selector_field`` for a different key), ``field`` is the field inside
that block, and ``value`` replaces what the file holds. The field must
already exist — an ``ot`` patch edits, it never invents a field the
engine would ignore.

``file`` defaults to ``DarkTalesResources/ApplicationSettings.ot``, the
one uncooked file with anything worth changing in it (entity-value
modifier descriptors, friendly-fire factors, the forced-seed option).

    mod.ot("Merlin DMG Zone", "m_eComputerType", 0)

The game's own bytes are the base, so this ships three strings instead
of a copy of a game file, and survives a patch that edits other parts of
the same file.

### `Mod.skinpack`

```python
Mod.skinpack(self, name: 'str', key: 'int', *, ac_id: 'str' = '', al_id: 'str' = '', base_id: 'str' = '') -> 'None'
```

Register a custom selectable skin-pack slot.

The skin roster is hardcoded in the engine (a fixed 9 `oCAdditionalContent`
"SkinPack" entries); see `docs/_re/kinds/skins.md`. A new slot can only be
added at runtime, so this is realized by the native loader DLL
(`src/loader/src/hook_skins.cpp`), which post-detours the roster builder and
appends a standalone entry per def. Defs are staged to
``mods/<id>/skinpacks.json``; the loader aggregates them across enabled mods.

Args:
    name:    display name shown in the skin grid.
    key:     pack key (int) the engine matches against a hero's pack-id
             field (entry ``+0x3c``). Must be unique across packs.
    ac_id:   AC content id (entry ``+0x50``), e.g. ``RW000PSAC000000A``.
    al_id:   AL content id (entry ``+0x60``), e.g. ``RW000PSAL000000A``.
    base_id: base content id (entry ``+0x70``).

Note: registering the slot is verified, but the engine's skin-grid
populate (``FUN_1401f0f10``) only renders a node as a button when the
manager filter (vtable[1]) returns ``3``. Two derived filter variants
exist: the Steam build checks ``ISteamApps::BIsDLCEnabled`` via the
node key (``+0x3c``); the local build checks a DLC entitlement file
path at ``node+0x80``. A brand-new key is rejected by both gates, so
the slot is on the roster list but invisible by default. To prove the
button path in-game, build the loader and run with
``RSMM_SKIN_FORCE_SHOW=1`` — it force-pushes the node into the grid
and logs the filter verdict (see ``docs/_re/kinds/skins.md`` A1/A2).
The ``dlc_path`` field can be set in ``skinpacks.json`` for the local
filter variant. Asset resolution for a new slot is likewise unconfirmed;
stage the per-skin cooked assets with
:meth:`asset`/:meth:`texture`/:meth:`model`, and until the resolver
is mapped, prefer reusing an existing slot's AC/AL id.

### `Mod.summary`

```python
Mod.summary(self) -> 'dict'
```

Snapshot of everything staged so far — print before :meth:`commit`
to see exactly what the mod will write (no disk writes).

### `Mod.tag`

```python
Mod.tag(self, tag_id: 'str', members) -> 'None'
```

Group content into a named, cross-mod-extensible tag (Minecraft
``#namespace:path`` tags analog).

``members`` is a ContentRef / id string, or an iterable of them.
Calling ``tag()`` again with the same id **appends** (de-duped,
order-preserved), so several mods — or several call sites — can grow
one tag. Members are deref'd to raw ids, so you can pass the handles
returned by :meth:`item`/:meth:`enemy`/… directly::

    dagger = m.item("RubyDagger", base="Knife")
    m.tag("daggers", [dagger, "VanillaKnife"])

Tags are written to ``mods/<id>/tags.json``; downstream tooling/mods
aggregate them (same model as ``skinpacks.json``).

### `Mod.texture`

```python
Mod.texture(self, decoded_path: 'str', source: 'str | Path') -> 'None'
```

Override a texture asset. Source must be a `.png`/`.dds`/`.tga`.

### `Mod.validate`

```python
Mod.validate(self) -> 'list[str]'
```

Return human-readable warnings about the current state (does not
raise). Empty list = clean. Called automatically by :meth:`commit`;
run it yourself for a fast pre-flight.

---

# CLI command inventory

> Every rsmm subcommand, auto-generated.

Source: https://docs.rsmm.me/reference/sdk-api/cli/

# rsmm CLI reference

Every `rsmm` subcommand, auto-generated from the dispatch table (`rsmm.cli._dispatch.iter_commands`).

:::note
Do not edit by hand — run `rsmm docs-gen` after adding or renaming a subcommand. For task-oriented prose, see the [CLI guide](/reference/cli/).
:::

**64 commands.**

| Command | Module | Summary |
|---|---|---|
| `rsmm ability-editor` | `rsmm.cli.cmd_editor` | `rsmm editor` — items, talents, abilities and maps in one local page. |
| `rsmm apply` | `rsmm.cli.apply_mods` | Ravenswatch Mod Manager — install-time mod applier. |
| `rsmm assets` | `rsmm.cli.cmd_assets` | `rsmm assets` — find a cooked asset by its readable path. |
| `rsmm backend` | `rsmm.cli.cmd_backend` | rsmm backend - point the game at a self-hosted online backend. |
| `rsmm build` | `rsmm.cli.build` | rsmm build — full pipeline. |
| `rsmm changelog` | `rsmm.cli.cmd_changelog` | `rsmm changelog` — read the release-notes channel. |
| `rsmm cmd` | `rsmm.cli.console_cmd` | rsmm cmd — send /commands to the in-game console runtime. |
| `rsmm collection` | `rsmm.cli.cmd_collection` | rsmm collection <subcommand> — manage mod collections. |
| `rsmm compat` | `rsmm.cli.compat` | Manifest compatibility graph. |
| `rsmm completion` | `rsmm.cli.cmd_completion` | rsmm completion — emit a shell tab-completion script. |
| `rsmm cook` | `rsmm.cli.cook` | rsmm cook — pack an editable source-format file into a cooked asset. |
| `rsmm decode` | `rsmm.engine.ot_decoder` | oCTextSaver binary decoder. |
| `rsmm diff` | `rsmm.cli.cmd_diff` | `rsmm diff <mod>` — what applying one mod changes in the game. |
| `rsmm disable` | `rsmm.cli.cmd_mods` | `rsmm enable` / `rsmm disable` — toggle mods from the terminal. |
| `rsmm docs-gen` | `rsmm.cli.docs_gen_cmd` | `rsmm docs-gen` — write the SDK/CLI reference from @sdk_export registrations. |
| `rsmm doctor` | `rsmm.cli.doctor` | rsmm doctor — system health check, and the repair path for what it finds. |
| `rsmm editor` | `rsmm.cli.cmd_editor` | `rsmm editor` — items, talents, abilities and maps in one local page. |
| `rsmm enable` | `rsmm.cli.cmd_mods` | `rsmm enable` / `rsmm disable` — toggle mods from the terminal. |
| `rsmm enemies` | `rsmm.cli.cmd_enemies` | `rsmm enemies` — discover vanilla enemies for enemy modding. |
| `rsmm entity-graph` | `rsmm.cli.cmd_entity_graph` | `rsmm entity-graph` — read an entity's components and their links. |
| `rsmm exp` | `rsmm.cli.cmd_exp` | rsmm exp — read back the hypotheses a mod answered during a playtest. |
| `rsmm export-character` | `rsmm.cli.cmd_export_character` | `rsmm export-character` — a hero as one rigged glTF for Blender / Maya. |
| `rsmm export-model` | `rsmm.cli.cmd_export_model` | `rsmm export-model` — any of the game's 3D models as a textured glTF. |
| `rsmm home` | `rsmm.cli.cmd_shell` | Interactive home screen — what bare `rsmm` opens in a terminal. |
| `rsmm import-character` | `rsmm.cli.cmd_import_character` | `rsmm import-character` — turn a character .glb edited in Blender into a mod. |
| `rsmm install` | `rsmm.cli.cmd_install` | rsmm install — fetch, verify, and unpack a packed mod. |
| `rsmm install-loader` | `rsmm.cli.install_loader` | rsmm install-loader — copy winhttp.dll + SDK lib into the game install. |
| `rsmm item-editor` | `rsmm.cli.cmd_editor` | `rsmm editor` — items, talents, abilities and maps in one local page. |
| `rsmm items` | `rsmm.cli.cmd_items` | `rsmm items` — discover vanilla magical objects for item modding. |
| `rsmm json` | `rsmm.cli.json_bridge` | rsmm json — machine-readable bridge for the desktop / web UI. |
| `rsmm keygen` | `rsmm.cli.repo_cmd` | `rsmm repo`, `rsmm sign`, `rsmm verify`, `rsmm keygen`. |
| `rsmm lint` | `rsmm.cli.lint` | rsmm lint — per-mod manifest + assets validator. |
| `rsmm list` | `rsmm.cli.apply_mods` | Ravenswatch Mod Manager — install-time mod applier. |
| `rsmm log` | `rsmm.cli.cmd_log` | rsmm log — read the loader log from the game install directory. |
| `rsmm map-editor` | `rsmm.cli.cmd_editor` | `rsmm editor` — items, talents, abilities and maps in one local page. |
| `rsmm merge` | `rsmm.cli.merge` | Patch-merge layer. |
| `rsmm modpack` | `rsmm.cli.cmd_modpack` | rsmm modpack — the identity of this install's applied mod set. |
| `rsmm new` | `rsmm.cli.cmd_new` | rsmm new — scaffold a mod directory. |
| `rsmm overlay` | `rsmm.cli.cmd_overlay` | rsmm overlay — read the live HUD data a mod publishes. |
| `rsmm pack` | `rsmm.cli.cmd_pack` | rsmm pack — bundle a mod for distribution. |
| `rsmm poi` | `rsmm.cli.cmd_poi` | `rsmm poi` — browse the tiles and kinds a `poi` content def can use. |
| `rsmm publish` | `rsmm.cli.cmd_publish` | rsmm publish — upload a mod to the store from the command line. |
| `rsmm rebuild-asset-map` | `rsmm.engine.find_iyg` | Ravenswatch Asset Decrypter — builds a full obfuscated -> plaintext |
| `rsmm rebuild-fn-patterns` | `rsmm.cli.cmd_rebuild_patterns` | `rsmm rebuild-fn-patterns` — regenerate the byte-pattern DB for the installed game. |
| `rsmm repo` | `rsmm.cli.repo_cmd` | `rsmm repo`, `rsmm sign`, `rsmm verify`, `rsmm keygen`. |
| `rsmm restore` | `rsmm.cli.apply_mods` | Ravenswatch Mod Manager — install-time mod applier. |
| `rsmm run` | `rsmm.cli.run` | rsmm run — launch Ravenswatch via Steam, ensuring the WINEDLLOVERRIDES |
| `rsmm safe-mode` | `rsmm.cli.safe_mode` | `rsmm safe-mode` — drive the SDK health quarantine. |
| `rsmm save` | `rsmm.cli.cmd_save` | `rsmm save` — inspect Ravenswatch profile saves. |
| `rsmm schema` | `rsmm.cli.cmd_schema` | rsmm schema — list the vanilla ids a content kind's ``base`` accepts. |
| `rsmm sdk-doctor` | `rsmm.cli.sdk_doctor` | `rsmm sdk-doctor` — SDK v3 self-check. |
| `rsmm sign` | `rsmm.cli.repo_cmd` | `rsmm repo`, `rsmm sign`, `rsmm verify`, `rsmm keygen`. |
| `rsmm symbols` | `rsmm.cli.cmd_symbols` | ``rsmm symbols`` — the engine symbol map (Minecraft-style mappings). |
| `rsmm talent-editor` | `rsmm.cli.cmd_editor` | `rsmm editor` — items, talents, abilities and maps in one local page. |
| `rsmm talents` | `rsmm.cli.cmd_talents` | `rsmm talents` — discover + edit hero talent ("Skill") values. |
| `rsmm test` | `rsmm.cli.test` | rsmm test — diff a mod's patch plan against a checked-in fixture. |
| `rsmm uncook` | `rsmm.cli.uncook` | rsmm uncook — extract a cooked asset to an editable source-format file. |
| `rsmm unify` | `rsmm.cli.unify` | rsmm unify — assemble one Blender-loadable GLB per hero. |
| `rsmm update` | `rsmm.cli.update_cmd` | `rsmm update` — pull updates for installed mods from configured repos. |
| `rsmm update-data` | `rsmm.cli.cmd_update_data` | `rsmm update-data` — pull the latest pattern DB without an app release. |
| `rsmm update-loader` | `rsmm.cli.cmd_update_loader` | `rsmm update-loader` — pull the loader DLL + Lua SDK without an app release. |
| `rsmm values` | `rsmm.cli.cmd_values` | `rsmm values` — back up a game patch's values and see what an update changed. |
| `rsmm verify` | `rsmm.cli.repo_cmd` | `rsmm repo`, `rsmm sign`, `rsmm verify`, `rsmm keygen`. |
| `rsmm watch` | `rsmm.cli.watch` | rsmm watch — live re-apply on mods/ change. |

---

# rsmm.sdk.config

> Per-mod config: schema validation + persisted store.

Source: https://docs.rsmm.me/reference/sdk-api/config/

# rsmm.sdk.config

Per-mod config: schema validation + persisted store.

Schema:
    {fields.<key>.{type, default, min, max, label, choices, enum, source}}

Types: bool, int, float, string, enum, multiselect, item-grid.

A `multiselect` field holds a LIST of ids. Its options are either spelled out
in `choices`, or fetched from an allowlisted provider named by `source` — see
`rsmm.sdk.config_choices`. A provider supplies a label, a group and an icon per
option, which is what lets the client draw a searchable grid of game art
instead of a wall of internal ids.

An `item-grid` field holds game items sorted into mod-declared sections, with an
optional number per item. Its layout, filters and optional theme of game
textures are declared in the schema itself — see `rsmm.sdk.config_grid`.

Storage:
    mods/<id>/config.toml  — user-edited values
    mods/<id>/config_schema.toml  — schema (authored by modder)

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `ConfigStore`

### `ConfigStore.get`

```python
ConfigStore.get(self, key: 'str', fallback: 'Any' = None) -> 'Any'
```

Read a config value by key, returning ``fallback`` if unset.

### `ConfigStore.set`

```python
ConfigStore.set(self, key: 'str', value: 'Any') -> 'None'
```

Set a config value, coercing to the schema field's type and persisting.

Raises ``ConfigError`` if ``key`` is not declared in the schema.

---

# rsmm.sdk.content

> Content kinds registry — façade over per-kind builders.

Source: https://docs.rsmm.me/reference/sdk-api/content/

# rsmm.sdk.content

Content kinds registry — façade over per-kind builders.

A mod registers content via `ContentRegistry.register("item", id=..., ...)`
which delegates to the `kinds/<kind>.py` implementation. Each kind owns
its own template + field-patcher + emit step.

Kinds that aren't fully schema-mined yet (bosses, maps, heroes at v3.0)
register their builder but fail with a clear `SchemaNotMined` error on
emit, so authors see exactly which class needs RE work next.

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `ContentRegistry`

### `ContentRegistry.register`

```python
ContentRegistry.register(self, kind: 'str', *, id: 'str', schema_version: 'int' = 1, **fields) -> 'ContentRef'
```

Register a content definition of ``kind`` and return its :class:`ContentRef`.

The low-level primitive behind :meth:`Mod.item` / :meth:`Mod.enemy`
/ etc. ``kind`` must be a known builder (``item``, ``enemy``,
``boss``, ``hero``, ``map``, …); non-``confirmed`` kinds require the
mod to opt in with ``experimental=True``. ``id`` must be unique
within the mod for that kind. Extra ``**fields`` are passed to the
kind builder.

---

# rsmm.sdk.health

> Health system — boot canary + crash history, as written by the LOADER.

Source: https://docs.rsmm.me/reference/sdk-api/health/

# rsmm.sdk.health

Health system — boot canary + crash history, as written by the LOADER.

The loader is the only process that can observe a crashy boot, so it owns the
file. `src/loader/src/health.cpp` opens `<game>/mods/_health.json` before any
mod code runs, stamps `canary.step` as each `init.lua` executes, and closes the
canary ~2 s after `ready`. A canary still open at the next launch means the
previous run died at that step, so the crash is attributed to that mod; three
consecutive failed boots disable it.

    {
      "version": 1,
      "canary": {"open": false, "step": "boot_ok", "session": "fd1d"},
      "mods": {
        "Foo": {"crashes": 2, "last_error": "...",
                "disabled": false, "disabled_reason": ""}
      }
    }

This module is the read/write side for the CLI. It used to describe — and
address — a completely different pair of files: `.rsmm_boot.json` and
`.rsmm_health.json` under `_Cooking`, with `last_step` instead of
`canary.step` and `disabled_by_health` instead of `disabled`. Nothing has ever
written those, so every consumer silently no-opped: `rsmm doctor` reported "no
crash records" while the loader had a mod disabled, `apply`'s quarantine pass
never quarantined anything, and `safe-mode --bisect` wrote its findings where
the loader would never read them. Two health systems that never met.

Writes are read-modify-write on the whole document so the CLI can never clobber
the canary node the loader is keeping, and land via temp-file + rename — the
whole point of this file is to survive a process that dies at an arbitrary
instant, so it must never be observed truncated.

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `Health`

### `Health.disabled_mods`

```python
Health.disabled_mods(self) -> 'set[str]'
```

Ids of mods the loader (or a bisect) has quarantined.

These were disabled after a crashy launch; the user re-enables each
with :meth:`re_enable` once fixed.

### `Health.re_enable`

```python
Health.re_enable(self, mod_id: 'str') -> 'None'
```

User manually re-enables after fixing the crash.

### `Health.record_crash`

```python
Health.record_crash(self, mod_id: 'str', error: 'str' = '') -> 'HealthState'
```

Bump the mod's crash counter, persist, return the updated state.

At `threshold` the mod is marked disabled, which the loader honours at
load and the applier honours at apply.

---

# rsmm.sdk.i18n

> Localization bundle.

Source: https://docs.rsmm.me/reference/sdk-api/i18n/

# rsmm.sdk.i18n

Localization bundle.

Each mod ships `lang/<locale>.toml`:

    [strings]
    title = "Frost Blade"
    desc  = "An icy weapon."

At apply time, RSMM merges strings into per-locale text-bank overrides
under namespaced keys: `RSMM_<modid>_<key>`. Locale codes match the
game's existing 12 (`apply_mods.LANG_DECODED_TO_ENCODED`) plus `RAW`.

At runtime, `R.i18n.t("key")` reads from a flat dict published by the
loader. This module is the host-side authoring + merging surface.

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `i18n`

### `i18n.merge_bundles`

```python
i18n.merge_bundles(bundles: 'list[I18nBundle]') -> 'dict[str, dict[str, str]]'
```

Produce locale -> {namespaced_key: value} ready for text-bank merge.

Two mods can't collide because keys are namespaced per `mod_id`.

---

# Content kinds & confidence

> Per-kind honesty ratings, generated from KIND_CONFIDENCE.

Source: https://docs.rsmm.me/reference/sdk-api/kinds/

# Content kinds & confidence

Every content kind carries an honesty rating — how much the bytes it emits are trusted. This page is generated from `rsmm.sdk.content.KIND_CONFIDENCE`, which is what the SDK and `rsmm lint` actually enforce, so it cannot drift from the code.

:::note
Do not edit by hand, and do not restate a rating in prose — link here. Run `rsmm docs-gen` after changing a rating; CI `--check`s it.
:::

**18 kinds** — 14 confirmed, 3 experimental, 1 guess.

| Kind | Confidence | Builder | What it does |
|---|---|---|---|
| `item` | ✅ confirmed | `rsmm.sdk.kinds.items` | Item (magical-object) content builder. |
| `enemy` | ✅ confirmed | `rsmm.sdk.kinds.enemies` | Enemy content builder — two modes. |
| `boss` | ✅ confirmed | `rsmm.sdk.kinds.bosses` | Boss content builder — make a boss arena fight a different boss. |
| `map` | ⚠️ experimental | `rsmm.sdk.kinds.maps` | Map (biome) content builder: clone a shipped mapdef and point a chapter at it. |
| `hero` | ✅ confirmed | `rsmm.sdk.kinds.heros` | Hero content builder: clone a shipped hero into a new roster entry. |
| `talent` | ✅ confirmed | `rsmm.sdk.kinds.talents` | Talent (in-game "Skill") value content builder. |
| `ability` | ⚠️ experimental | `rsmm.sdk.kinds.hero_abilities` | Ability edits to a SHIPPED hero, in place. |
| `skill` | ✅ confirmed | `rsmm.sdk.kinds.skills` | Hero **skill** (talent) content builder. |
| `modifier` | ⚠️ experimental | `rsmm.sdk.kinds.modifiers` | Custom **game modifier** ("negative mode") content builder. |
| `game_mode` | ✅ confirmed | `rsmm.sdk.kinds.game_modes` | Custom **game mode** (run chapter sequence) builder. |
| `reward` | ✅ confirmed | `rsmm.sdk.kinds.rewards` | **Reward placement** editor — ban/tune what spawns at reward points. |
| `melody` | ❓ guess | `rsmm.sdk.kinds.melodies` | **Melody** editor — retune the Piper's lost-melody definitions. |
| `poi` | ✅ confirmed | `rsmm.sdk.kinds.poi` | **POI / structure** builder — put a point of interest into any chapter. |
| `mesh` | ✅ confirmed | `rsmm.sdk.kinds.meshes` | **Mesh** content builder — put the mod's model in place of a shipped one. |
| `tilegen` | ✅ confirmed | `rsmm.sdk.kinds.tilegen` | Chapter map-generation recipe content builder. |
| `shop` | ✅ confirmed | `rsmm.sdk.kinds.shops` | **Shop** editor — change what the Sandman sells and what it costs. |
| `animation` | ✅ confirmed | `rsmm.sdk.kinds.animations` | **Animation** content builder — play the mod's animation in place of a shipped clip. |
| `entity` | ✅ confirmed | `rsmm.sdk.kinds.entities` | Edits to ONE shipped entity file, in place. |

## What a rating means

| Rating | Meaning | To ship it |
|---|---|---|
| ✅ `confirmed` | The emitted bytes were verified in-game, end to end. | Nothing extra. |
| ⚠️ `experimental` | Codecs round-trip and the emit succeeds, but the in-game path is unproven. | `sdk.Mod(..., experimental=True)` / `experimental = true`. |
| ❓ `guess` | The byte layout is an educated guess. May be rejected, may crash. | Same opt-in, plus your own testing. |

A mod that registers any non-`confirmed` kind must opt in, and its manifest records it — so nobody ships speculative content believing it works. `rsmm lint` fails the mod otherwise.

The *reason* behind each rating — what was proven, when, and what the rating is still waiting on — is written beside the rating in `src/rsmm/sdk/content.py`. Start there before changing one.

## Starting one

[First mod, by kind](/guides/first-mod-by-kind/) has a minimal, working `manifest.toml` for every row above.

---

# rsmm.sdk.repo

> Distribution: `repo.json` schema + SHA256/Ed25519 sign + verify.

Source: https://docs.rsmm.me/reference/sdk-api/repo/

# rsmm.sdk.repo

Distribution: `repo.json` schema + SHA256/Ed25519 sign + verify.

Open spec. No central host. Anyone can publish a `repo.json` at a URL of
their choice; users add it with `rsmm repo add <url>`.

Signing is optional but recommended. We use Ed25519 from `cryptography`
when available and fall back to "unsigned mode" otherwise. Keys live in
`~/.rsmm/keys/`:

    <id>.pub        # base64 Ed25519 public key
    <id>.key        # base64 Ed25519 private key (mode 0600)

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `repo`

### `repo.sha256_file`

```python
repo.sha256_file(path: 'Path') -> 'str'
```

Hex SHA256 of a file, streamed (no full-file buffering).

The integrity primitive behind `repo.json` manifests and
:func:`sign_file` / :func:`verify_file`.

### `repo.sign_file`

```python
repo.sign_file(path: 'Path', private_key_path: 'Path') -> 'str'
```

Return base64 Ed25519 signature of `path`'s SHA256 digest.

Signing the digest (not the whole file) lets verifiers stream-hash
without buffering the file.

### `repo.verify_file`

```python
repo.verify_file(path: 'Path', sig_b64: 'str', public_key_path: 'Path') -> 'bool'
```

Verify a base64 Ed25519 signature over `path`'s SHA256 digest.

Returns ``True`` if ``sig_b64`` (from :func:`sign_file`) matches under
``public_key_path``, ``False`` otherwise — a malformed signature is simply
one that does not verify. Raises ``RepoError`` only for a malformed or
unreadable public key.

Verification must not depend on ``cryptography``: the CLI ships frozen
with no runtime dependencies, so every released build lacked it and this
raised on every call — which ``rsmm update`` then read as "verify skipped"
and installed the archive without checking the signature at all. Without
the package it uses the stdlib Ed25519 verifier the signed loader channel
already relies on (:mod:`rsmm.engine.minisign`).

---

# rsmm.sdk.testkit

> Offline testing helpers for mod authors.

Source: https://docs.rsmm.me/reference/sdk-api/testkit/

# rsmm.sdk.testkit

Offline testing helpers for mod authors.

Lets a mod be unit-tested without the game: build a mod in-memory with
:class:`~rsmm.sdk.builder.ModBuilder`, then assert over what it staged via
a small fluent API. Everything reads the builder's accumulated state (the
same data :meth:`ModBuilder.summary` exposes) — no disk writes, no apply,
no Ravenswatch.

    from rsmm import sdk
    from rsmm.sdk.testkit import expect

    def test_my_pack():
        m = sdk.builder.ModBuilder("MyPack", version="1.0.0",
                                   author="me", name="My Pack")
        blade = m.item("FrostBlade", base="VanillaSword", name="Frost Blade")
        m.tag("daggers", [blade])
        m.i18n("EN", {"hello": "Hi"})

        (expect(m)
            .has_item("FrostBlade")
            .has_tag("daggers", "FrostBlade")
            .i18n_complete()
            .clean())            # no validate() warnings

Assertions raise ``AssertionError`` with a readable message and return the
same :class:`ModExpect` so calls chain. Use :func:`conflicts` to check a
set of mods don't collide before shipping a collection.

:::note
Auto-generated from `@sdk_export` registrations by `rsmm docs-gen`. Edit the docstrings in the source module, not this page.
:::

## `testkit`

### `testkit.assert_no_conflicts`

```python
testkit.assert_no_conflicts(*mods: 'ModBuilder') -> 'None'
```

Raise ``AssertionError`` if :func:`conflicts` finds any collision.

### `testkit.conflicts`

```python
testkit.conflicts(*mods: 'ModBuilder') -> 'list[str]'
```

Return human-readable conflict messages across several mods (empty =
safe to ship together). Catches colliding asset overrides, duplicate
``(kind, id)`` content, and duplicate skin-pack keys — the things that
make two mods silently clobber each other at apply time.

### `testkit.expect`

```python
testkit.expect(mod: 'ModBuilder') -> 'ModExpect'
```

Begin a fluent assertion chain over a :class:`ModBuilder`.

---

# Security

> Security model, threat surface, and reporting.

Source: https://docs.rsmm.me/reference/security/

## Supply-chain audit

Every `pnpm install` in CI is followed by `pnpm audit:supply-chain`,
which runs `scripts/audit-supply-chain.mjs`. It scans `pnpm-lock.yaml`
against a baked-in list of known-compromised `package@version` pairs
and exits non-zero on any hit.

`pnpm install` in CI uses `--ignore-scripts`. Lifecycle scripts run
only after the audit gate passes (`pnpm rebuild`). This prevents a
compromised tarball's `prepare`/`postinstall` from executing before
the audit notices it.

### Updating the known-bad list

When a new advisory is published:

1. Identify affected `package@version` pairs from the GHSA or vendor advisory.
2. Append them to `KNOWN_BAD` in `scripts/audit-supply-chain.mjs`.
3. Add a `# Source:` comment with the GHSA / CVE / blog URL.
4. Run `pnpm audit:supply-chain` locally — it must pass before committing.

### Current baked-in advisories

| ID | Date | Packages | Notes |
|---|---|---|---|
| [GHSA-g7cv-rxg3-hmpx](https://github.com/advisories/GHSA-g7cv-rxg3-hmpx) | 2026-05-11 | 42 `@tanstack/*` packages, 84 versions | TanStack supply-chain incident. `@tanstack/query*`, `@tanstack/table*`, `@tanstack/form*`, `@tanstack/virtual*`, `@tanstack/store`, `@tanstack/start` (meta) confirmed clean. |

## Incident response — if the audit fails

Treat the install host as potentially compromised. Even a partial
install of a malicious tarball can run the `prepare` lifecycle script
before npm/pnpm errors out.

1. **Stop.** Do not run further `pnpm`/`npm`/`yarn` commands on the host.
2. **Rotate credentials reachable from the host** — AWS, GCP, Kubernetes,
   Vault, GitHub, npm, SSH. (Per GHSA-g7cv-rxg3-hmpx, the exfil channel
   is the Session/Oxen messenger network at `filev2.getsession.org` /
   `seed{1,2,3}.getsession.org`. End-to-end encrypted, so DNS/IP blocks
   are the only network mitigation.)
3. **Audit dotfiles** that contained credentials:
   - `~/.npmrc`
   - `~/.git-credentials`
   - `~/.aws/credentials`
   - `~/.kube/config`
   - `~/.ssh/`
4. **Wipe and reinstall** the workspace:
   ```sh
   rm -rf node_modules pnpm-lock.yaml
   pnpm store prune
   pnpm install --ignore-scripts
   pnpm audit:supply-chain
   pnpm rebuild
   ```
5. **Check your maintained npm packages** — the GHSA-g7cv-rxg3-hmpx
   malware self-propagates by republishing other packages owned by the
   victim. Verify with `npm view <pkg> versions --json` that no
   unexpected version was published from your account.

## Threat model — what RSMM ships

The desktop app (`apps/desktop`) is a Tauri 2 shell. It executes the
`rsmm` Python CLI as a sidecar with a narrowly scoped allow-list in
`src-tauri/capabilities/default.json`. The webview cannot execute
arbitrary shell commands; only `rsmm <args>` invocations are permitted.

The API (`apps/api`) trusts only the origins enumerated in
`TRUSTED_ORIGINS`. Better Auth sessions are HTTP-only cookies; the
client sends them via `credentials: 'include'`.

The signed-PUT upload flow (`/mods/upload`) only issues URLs to
authenticated users and requires `x-amz-checksum-sha256` matching the
declared body hash — the storage backend rejects mismatched uploads.

After a mod zip lands in object storage, the API submits the public
download URL to VirusTotal using `VIRUS_TOTAL_API_KEY`. The upload is
only considered finished once that scan submission succeeds.

VirusTotal is an additional signal, not a sandbox. Keep the usual code
review and moderation workflow in place for uploaded mods.

## Reporting a vulnerability

Email `security@rsmm.me` (or, until that is provisioned, open a
private security advisory on the GitHub repo). Do not file public
issues for security reports.

---

# Talent name lookup

> Every hero's talents, with the internal names you need to mod them.

Source: https://docs.rsmm.me/reference/talent-names/

The game shows a talent by its English name, like **Short Wick**. Inside the
game files the same talent has other names, like `Secondary Quick Bombs`. This
page connects the two, so you can go from the card you see in game to the name
a mod needs.

This is the companion page for the
[Talent modding tutorial](/guides/talent-tutorial/). Every hero section gives
you three things to copy:

| Column | What it is for |
|---|---|
| **Hero spelling** | Two spellings of the hero's name. `kind = "talent"` needs the first one and `kind = "skill"` needs the second. They differ only for Sun Wukong. |
| **Search word** | Goes into the helper script to find the talent's numbers. It usually also works as the talent name in the testing file that gives you the talent at the start of a run. |
| **Rename with** | Goes into `source = "..."` when you change the talent's name or description. |

A dash (—) under **Search word** means the helper cannot find that talent's
numbers by name.

:::note
The table was generated from the game's own English text on 2026-09-14. A game
update can add, remove or rename talents. If a name here stops working, the
helper script in the tutorial always reads the files you have now.

The two basic ultimates each hero starts with are not listed. Their names are
stored in more than one place and renaming them has not been tested. The
ultimate **upgrades** are listed.
:::

Jump to a hero:

[Aladdin](#aladdin) · [Beowulf](#beowulf) · [Carmilla](#carmilla) · [Geppetto](#geppetto) · [Juliet](#juliet) · [Melusine](#melusine) · [Merlin](#merlin) · [The Pied Piper](#the-pied-piper) · [Romeo](#romeo) · [Scarlet](#scarlet) · [The Snow Queen](#the-snow-queen) · [Sun Wukong](#sun-wukong)

## Aladdin

**Hero spelling:** `hero = "Aladdin"` for `kind = "talent"`, and `hero = "Aladdin"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Dive | Attack | `Attack Dive` | `Skill_Attack_Dive` |
| Dream Scimitars | Attack | `Attack Spawns DS` | `Skill_Attack_Spawns_DS` |
| Shard Blades | Attack | `Attack Wide` | `Skill_Attack_Wide` |
| Slide Attack | Attack | `Attack No Weapon` | `Skill_Attack_No_Weapon` |
| Spinning Strikes | Attack | `Attack Flurry` | `Skill_Attack_Flurry` |
| Cyclonic Appearance | Power | `Power Start AOE` | `Skill_Power_Start_AOE` |
| Enchanted Jinn | Power | `Power Energy` | `Skill_Power_Energy` |
| Jinn's Fury | Power | `Power Multi Hit` | `Skill_Power_Multi_Hit` |
| Jinn's Might | Power | `Power Quest` | `Skill_Power_Quest` |
| Swordjinn | Power | `Power Blades` | `Skill_Power_Blades` |
| Aerial Catch | Special | `Special Quest` | `Skill_Special_Quest` |
| Dancing Blades | Special | `Special Extra Spins` | `Skill_Special_Extra_Spins` |
| Healing Blades | Special | `Special Healing` | `Skill_Special_Healing` |
| Sand Vortex | Special | `Special Vacuum` | `Skill_Special_Vacuum` |
| Acrobatics | Defense | `Defense Energy` | `Skill_Defense_Energy` |
| Air Dash | Defense | `Defense Dash` | `Skill_Defense_Dash` |
| Tornado Jump | Defense | `Defense Tornado` | `Skill_Defense_Tornado` |
| Leaping Strike | Dash | `Dash Attack` | `Skill_Dash_Attack` |
| Jinniya's Gift | Trait | `Trait Extra Wish` | `Skill_Trait_Extra_Wish` |
| Wish of Omnipotence | Trait | `Trait Wish Omnipotence` | `Skill_Trait_Wish_Omnipotence` |
| Major Enchantment | Passive | `Passive Energy` | `Skill_Passive_Energy` |
| Master Thief | Passive | `Passive Extra MO` | `Skill_Passive_Extra_MO` |
| Dream Stride | Ultimate | `Ultimate 2 Carpet DS` | `Skill_Ultimate_2_Carpet_DS` |
| Infinite Wishes | Ultimate | `Ultimate 1 More Wish` | `Skill_Ultimate_1_More_Wish` |
| Quick Ride | Ultimate | `Ultimate 2 Carpet Dash` | `Skill_Ultimate_2_Carpet_Dash` |
| Wondrous Wishes | Ultimate | `Ultimate 1 Better Wish` | `Skill_Ultimate_1_Better_Wish` |

## Beowulf

**Hero spelling:** `hero = "Beowulf"` for `kind = "talent"`, and `hero = "Beowulf"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Blademaster | Attack | `Attack Speed` | `Skill_Attack_Speed` |
| Blazing Runes | Attack | `Attack Special Crit` | `Skill_Attack_Special_Crit` |
| Breath of Fire | Attack | `Attack Fire Cone` | `Skill_Attack_Fire_Cone` |
| Furious Blows | Attack | `Attack After Special` | `Skill_Attack_After_Special` |
| Heavy Strikes | Attack | `Attack Wide` | `Skill_Attack_Wide` |
| Retaliation | Attack | `Attack Flurry` | `Skill_Attack_Flurry` |
| Double Shock | Power | `Power Double` | `Skill_Power_Double` |
| Eruption | Power | `Power End AOE` | `Skill_Power_End_AOE` |
| Scorched Earth | Power | `Power Trail` | `Skill_Power_Trail` |
| Bladestorm | Special | `Special Loop` | `Skill_Special_Loop` |
| Fiery Seismo | Special | `Special Multi Shock` | `Skill_Special_Multi_Shock` |
| Secondary Tremor | Special | `Special Sends Power` | `Skill_Special_Sends_Power` |
| Rampart | Defense | `Defense Quest` | `Skill_Defense_Quest` |
| Runes of War | Defense | `Defense Damage Aura` | `Skill_Defense_Damage_Aura` |
| Shield Charge | Defense | `Defense Dash` | `Skill_Defense_Dash` |
| Sparkling Shield | Defense | `Defense Block Deals Damage` | `Skill_Defense_Block_Deals_Damage` |
| Fiery Slash | Dash | `Dash Attack` | `Skill_Dash_Attack` |
| Battle Cry | Trait | `Trait Battlecry` | `Skill_Trait_Battlecry` |
| Draconic Binds | Trait | `Trait Quest` | `Skill_Trait_Quest` |
| Fire Wings | Trait | `Trait AOE` | `Skill_Trait_AOE` |
| Explosive Fire | Passive | `Passive Ignite Explosion` | `Skill_Passive_Ignite_Explosion` |
| Furnace | Passive | `Passive Better Ignite` | `Skill_Passive_Better_Ignite` |
| Fireball | Ultimate | `Ultimate 2 Fireball Dash` | `Skill_Ultimate_2_Upgrade_Fireball_Dash` |
| Immolation | Ultimate | `Ultimate 1 Immolation` | `Skill_Ultimate_1_Upgrade_Immolation` |
| Sudden Growth | Ultimate | `Ultimate 1 Big Wyrm` | `Skill_Ultimate_1_Upgrade_Big_Wyrm` |
| Volcanic Rage | Ultimate | `Ultimate 2 Volcanic` | `Skill_Ultimate_2_Upgrade_Volcanic` |

## Carmilla

**Hero spelling:** `hero = "Carmilla"` for `kind = "talent"`, and `hero = "Carmilla"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Cruel Strike | Attack | `Attack Last Combo Move` | `Skill_Attack_Last_Combo_Move` |
| Onslaught | Attack | `Attack Special Rush` | `Skill_Attack_Special_Rush` |
| Razor Claws | Attack | `Attack Bleed` | `Skill_Attack_Bleed` |
| Blood Rage | Power | `Power Quest` | `Skill_Power_Quest` |
| Flesh Rip | Power | `Power Bleed Crit` | `Skill_Power_Bleed_Crit` |
| Furious Tempest | Power | `Power Maintained Damage` | `Skill_Power_Maintained_Damage` |
| Injection | Power | `Power Special Bomb` | `Skill_Power_Special_Bomb` |
| Wild Heart | Power | `Power Range` | `Skill_Power_Range` |
| Go for the Throat | Special | `Special Critical Distance` | `Skill_Special_Critical_Distance` |
| Life Essence | Special | `Special Quest` | `Skill_Special_Quest` |
| Victimization | Special | `Special Marked` | `Skill_Special_Marked` |
| Aggressive Flock | Defense | `Defense Projectile` | `Skill_Defense_Projectile` |
| Bat Master | Defense | `Defense Master` | `Skill_Defense_Master` |
| Dispersion | Defense | `Defense Aoe Bleed` | `Skill_Defense_Aoe_Bleed` |
| Puncture | Dash | `Dash Blood` | `Skill_Dash_Blood` |
| Seductive Provocation | Dash | `Dash Taunt` | `Skill_Dash_Taunt` |
| Angel and Demon | Trait | `Trait Heal Buff` | `Skill_Trait_Heal_Buff` |
| Gust | Trait | `Trait Push back` | `Skill_Trait_Push_Back` |
| Life Tap | Trait | `Trait Life Tap` | `Skill_Trait_Life_Tap` |
| Blood Reserve | Passive | `Passive Blood Reserve` | `Skill_Passive_Blood_Reserve` |
| Boiling Blood | Passive | `Passive Life Use Regen` | `Skill_Passive_Life_Use_Regen` |
| Sadism | Passive | `Passive Critical Bleed` | `Skill_Passive_Critical_Bleed` |
| Heartbreak | Ultimate | `Ultimate 1 Combo Pike` | `Skill_Ultimate_1_Combo_Pike` |
| Mass Punishment | Ultimate | `Ultimate 2 Add Zone Attack` | `Skill_Ultimate_2_Add_Zone_Attack` |
| Mistress of Pain | Ultimate | `Ultimate 2 Increase Max Attack` | `Skill_Ultimate_2_Increase_Max_Attack` |
| Torture of the Pale | Ultimate | `Ultimate 1 Return` | `Skill_Ultimate_1_Return` |

## Geppetto

**Hero spelling:** `hero = "Geppetto"` for `kind = "talent"`, and `hero = "Geppetto"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Family Meeting | Attack | `Attack Group Speed` | `Skill_Attack_Group_Speed` |
| Nailing Strike | Attack | `Attack Finisher` | `Skill_Attack_Finisher` |
| Oiled Mechanisms | Attack | `Attack Makes Dummies Attack` | `Skill_Attack_Makes_Dummies_Attack` |
| Flux Capacitor | Power | `Power Overcharge` | `Skill_Power_Overcharge` |
| Magnetic Hammer | Power | `Power Magnet` | `Skill_Power_Magnet` |
| Unstable Cores | Power | `Power Unstable` | `Skill_Power_Unstable` |
| Clockwork Medicine | Special | `Special Regeneration` | `Skill_Special_Regeneration` |
| Dummyball | Special | `Special Creates Dummy` | `Skill_Special_Creates_Dummy` |
| Vacuum Capsule | Special | `Special Pushback` | `Skill_Special_Pushback` |
| Forked Lightning | Defense | `Defense Lightning` | `Skill_Defense_Lightning` |
| Laser Lenses | Defense | `Defense Laser Eyes` | `Skill_Defense_Laser_Attack` |
| Lightning Rod Dummies | Defense | `Defense AOE` | `Skill_Defense_AOE` |
| Rocket Science | Dash | `Dash Deals Damage` | `Skill_Dash_Deals_Damage` |
| Explosive Builds | Trait | `Trait Blast Construction` | `Skill_Trait_Blast_Construction` |
| Fireworks | Trait | `Trait Missiles` | `Skill_Trait_Missiles` |
| Heart Ties | Trait | `Trait Max Health` | `Skill_Trait_Max_Health` |
| Large Family | Trait | `Trait Extra Charge` | `Skill_Trait_Extra_Charge` |
| Mourning Rage | Trait | `Trait Buff On Dummy Death` | `Skill_Trait_Buff_On_Dummy_Death` |
| Pogo-Hoppers | Trait | `Trait Attack Move` | `Skill_Trait_Attack_Move` |
| Sharp Noses | Trait | `Trait Nose Attack` | `Skill_Trait_Nose_Attack` |
| Twin Dummies | Trait | `Trait Twins` | `Skill_Trait_Twins` |
| Flash of Genius | Passive | `Passive Create Objects` | `Skill_Passive_Create_Object` |
| Bomb Reserve | Ultimate | `Ultimate 1 Bomber` | `Skill_Ultimate_1_Bomber` |
| High Voltage | Ultimate | `Ultimate 2 Overclock Hit` | `Skill_Ultimate_2_Overclock_Hit` |
| Hyperclock | Ultimate | `Ultimate 2 Overclock Ignite` | `Skill_Ultimate_2_Overclock_Ignite` |
| Master Puppet | Ultimate | `Ultimate 1 Big Meca Puppet` | `Skill_Ultimate_1_Big_Meca_Puppet` |

## Juliet

**Hero spelling:** `hero = "Juliet"` for `kind = "talent"`, and `hero = "Juliet"` for `kind = "skill"`.

:::caution
Juliet's talent names are stored differently from every other hero's. You can change a Juliet talent's **description** and numbers, but changing its **name** fails with `text key ... not in bank`.
:::

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Hot Shots | Attack | `Attack Ignite` | `Skill_Attack_Ignite` |
| Knockout | Attack | `Attack Close Combat` | `Skill_Attack_Close_Combat` |
| Lucky Shot | Attack | `Attack Power` | `Skill_Attack_Power` |
| Swirling Rose | Attack | `Attack Rose AOE` | `Skill_Attack_Rose_AOE` |
| Volcanic Shots | Attack | `Attack Burst` | `Skill_Attack_Burst` |
| Double Tap | Power | `Power Double Shot` | `Skill_Power_Double_Shot` |
| Explosive Backstep | Power | `Power Attack Backstep` | `Skill_Power_Attack_Backstep` |
| Guns & Roses | Power | `Power Quest Explode` | `Skill_Power_Quest_Explode` |
| Longshot | Power | `Power More Range` | `Skill_Power_More_Range` |
| Shadow Round | Power | `Power Vulnerable` | `Skill_Power_Vulnerable` |
| Shrapnel | Power | `Power Cone Damage` | `Skill_Power_Cone_Damage` |
| Kiss the Groom | Special | `Special Quest Dream Shard` | `Skill_Special_Quest_Dream_Shard` |
| Love Sparks | Special | `Special Projectile` | `Skill_Special_Projectile` |
| Overflowing Passion | Special | `Special Heal` | `Skill_Special_Heal` |
| Blind Shots | Defense | `Defense More Shot` | `Skill_Defense_More_Shots` |
| Bullet Ballet | Defense | `Defense Ricochet` | `Skill_Defense_Ricochet` |
| Defensive Reload | Defense | `Defense Reload` | `Skill_Defense_Reload` |
| Comforting Presence | Dash | `Dash Shield` | `Skill_Dash_Shield` |
| Heartbeat | Trait | `Trait AOE` | `Skill_Trait_AOE` |
| Valiant Hearts | Trait | `Trait Buff` | `Skill_Trait_Buff` |
| Large Chambers | Passive | `Passive More Ammo` | `Skill_Passive_More_Ammo` |
| Wedding Gifts | Passive | `Passive Bonus Object` | `Skill_Passive_Bonus_Object` |
| Flashy Ending | Ultimate | `Ultimate 1 End AOE` | `Skill_Ultimate_1_End_AOE` |
| Passion Dance | Ultimate | `Ultimate 1 Heal` | `Skill_Ultimate_1_Heal` |
| Plague Flask | Ultimate | `Ultimate 2 Marked` | `Skill_Ultimate_2_Marked` |
| Unstable Concoction | Ultimate | `Ultimate 2 Dash AOE` | `Skill_Ultimate_2_Dash_AOE` |

## Melusine

**Hero spelling:** `hero = "Melusine"` for `kind = "talent"`, and `hero = "Melusine"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Deep Beat | Attack | `Attack Beat` | `Skill_Attack_Beat` |
| Protective Flow | Attack | `Attack Shield` | `Skill_Attack_Shield` |
| Submerging Attack | Attack | `Attack Amplifies` | `Skill_Attack_Amplifies` |
| Wisp Surge | Attack | `Attack Speed` | `Skill_Attack_Speed` |
| Aftershock | Power | `Power Core` | `Skill_Power_Water_Core` |
| Freezing Splash | Power | `Power Chill` | `Skill_Power_Chill` |
| Geyser | Power | `Power Geyser` | `Skill_Power_Geyser` |
| Backwash | Special | `Special Backwards` | `Skill_Special_Backwards` |
| Spring Water | Special | `Special Heal` | `Skill_Special_Heal` |
| Tidal Wave | Special | `Special Large Waves` | `Skill_Special_Large_Waves` |
| Waterlogging | Special | `Special Growth` | `Skill_Special_Growth` |
| Power Dive | Defense | `Defense Power` | `Skill_Defense_Power` |
| Razor Tail | Defense | `Defense Deals Damage` | `Skill_Defense_Deals_Damage` |
| Underwater Predation | Defense | `Defense Hold` | `Skill_Defense_Hold` |
| Water Bubble | Defense | `Defense Block` | `Skill_Defense_Block` |
| Water Communion | Defense | `Defense Improve Special` | `Skill_Defense_Improve_Special` |
| Bewitching Song | Trait | `Trait Weakens` | `Skill_Trait_Weakens` |
| Sea Dance | Trait | `Trait Teleport` | `Skill_Trait_Teleport` |
| Shimmering Scales | Trait | `Trait Armor` | `Skill_Trait_Armor` |
| Enduring Wisp | Passive | `Passive Auto Wisp` | `Skill_Passive_Auto_Wisp` |
| Final Burst | Passive | `Passive Detonation` | `Skill_Passive_Detonation` |
| Soothing Presence | Passive | `Passive Heal In Combat` | `Skill_Passive_Heal_In_Combat` |
| Crescendo | Ultimate | `Ultimate 2 Spawn More` | `Skill_Ultimate_2_Upgrade_Spawn_More` |
| Healing Blast | Ultimate | `Ultimate 1 Heal` | `Skill_Ultimate_1_Upgrade_Heal` |
| Overtone Singing | Ultimate | `Ultimate 2 Sing Stance Wisp` | `Skill_Ultimate_2_Upgrade_Sing_Stance_Wisp` |
| Vortex Bomb | Ultimate | `Ultimate 1 Vortex` | `Skill_Ultimate_1_Upgrade_Vortex` |

## Merlin

**Hero spelling:** `hero = "Merlin"` for `kind = "talent"`, and `hero = "Merlin"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Wild Magic | Attack | `Attack Bleed After Power` | `Skill_Attack_Bleed_After_Power` |
| Brambles Whirlwind | Power | `Power Power AOE` | `Skill_Power_Power_AOE` |
| Freezing Stones | Power | `Power Defense Chilled` | `Skill_Power_Defense_Chilled` |
| Natural Harmony | Power | `Power Heal` | `Skill_Power_Heal` |
| Shooting Stars | Power | `Power Special Vulnerable` | `Skill_Power_Special_Vulnerable` |
| Arcane Shield | Special | `Special Block` | `Skill_Special_Block` |
| Arcanic Rune | Special | `Special Gain Potency` | `Skill_Special_Gain_Potency` |
| Fire Barrage | Special | `Special Special Missiles` | `Skill_Special_Missiles` |
| Frost Arcane | Special | `Special Defense Attack AOE` | `Skill_Special_Defense_Attack_AOE` |
| Lightning Storm | Special | `Special Power Lightning` | `Skill_Special_Power_Lightning` |
| Holy Fire | Defense | `Defense Special Ignite` | `Skill_Defense_Special_Ignite` |
| Retaliation | Defense | `Defense Power Shield` | `Skill_Defense_Power_Shield` |
| Sacred Ground | Defense | `Defense Defense DMG Buff Zone` | `Skill_Defense_Defense_DMG_Buff_Zone` |
| Sacred Strike | Defense | `Defense Attack Finisher` | `Skill_Defense_Attack_Finisher` |
| Life Seed | Dash | `Dash Heal` | `Skill_Dash_Heal` |
| Celestial Wrath | Trait | `Trait Lightning` | `Skill_Trait_Lightning` |
| Grace of Heaven | Trait | `Trait Reduce Cooldown After Defense` | `Skill_Trait_Reduce_Cooldown_After_Defense` |
| Trinity | Trait | `Trait Quest Gain Charge` | `Skill_Trait_Quest_Gain_Charge` |
| Astrology | Passive | `Passive Gain Reroll High Talent` | `Skill_Passive_Gain_Reroll_High_Talent` |
| Elemental Affinity | Passive | `Passive Crit Chance On Status` | `Skill_Passive_Crit_Chance_On_Status` |
| Eternal Dream | Passive | `Passive Repeatable Quest Gain DS` | `Skill_Passive_Repeatable_Quest_Gain_DS` |
| Runic Might | Passive | `Passive Quest Crit Chance` | `Skill_Passive_Quest_Crit_Chance` |
| Corrupted Arts | Ultimate | — | `Skill_Ultimate_2_Dmg_Per_Cursed` |
| Dark Swiftness | Ultimate | `Ultimate 2 Dash` | `Skill_Ultimate_2_Dash` |
| Energy Stone | Ultimate | `Ultimate 1 AOE` | `Skill_Ultimate_1_AOE` |
| Megalithic Site | Ultimate | `Ultimate 1 Multi Stone` | `Skill_Ultimate_1_Multi_Stone` |

## The Pied Piper

**Hero spelling:** `hero = "Piper"` for `kind = "talent"`, and `hero = "Piper"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Ghost Notes | Attack | `Attack Ghost Notes` | `Skill_Attack_Ghost_Notes` |
| Low Notes | Attack | `Basic Big Shots` | `Skill_Attack_Big_Shots` |
| Sniper | Attack | `Basic Primary Long Shots` | `Skill_Attack_Power_Long_Shots` |
| Virtuoso | Attack | `Attack Move Speed` | `Skill_Attack_Move_Speed` |
| Extra Measure | Power | `Primary More Waves After Defense` | `Skill_Power_More_Waves_After_Defense` |
| Quintuplets | Power | `Primary Wide Spread` | `Skill_Power_Wide_Spread` |
| Spinning Solo | Power | `Primary Evasion` | `Skill_Power_Evasion` |
| Acoustic Pulses | Special | `Secondary DOT` | `Skill_Special_DOT` |
| Chorus | Special | `Special Sends Attacks` | `Skill_Special_Sends_Attacks` |
| Freezing Trap | Special | `Secondary Chill` | `Skill_Special_Chill` |
| Grand Finale | Special | `Secondary Explosive Zone` | `Skill_Special_Explosive_Zone` |
| Explosive Blast | Defense | `Defensive Deals Damage` | `Skill_Defense_Deals_Damage` |
| Invasive Blast | Defense | `Defense Spawn Pets` | `Skill_Defense_Spawn_Pets` |
| Perfect Harmony | Defense | `Defensive Heal On Hit` | `Skill_Defense_Heal_On_Hit` |
| Sforzando | Defense | `Special Implosive` | `Skill_Defense_Implosive` |
| Sound Barrier | Defense | `Defensive Armor Quest` | `Skill_Defense_Armor_Quest` |
| Music of the Spheres | Dash | `Dash Trap` | `Skill_Dash_Trap` |
| Explosive Rats | Trait | `Trait Explosive Pets` | `Skill_Trait_Explosive_Pets` |
| Giant Rats | Trait | `Trait Big Pets` | `Skill_Trait_Big_Pets` |
| Horde | Trait | `Trait More Controllable Pets` | `Skill_Trait_More_Controllable_Pets` |
| Leeching Charm | Trait | `Trait Pets Heal` | `Skill_Trait_Pets_Heal` |
| Stimulant Vibes | Trait | `Trait Pets Within Special` | `Skill_Trait_Pets_Within_Special` |
| Jig | Ultimate | `Ultimate 1 Dash` | `Skill_Ultimate_1_Upgrade_Dash` |
| Rain of Notes | Ultimate | `Ultimate 1 Notes Rain` | `Skill_Ultimate_1_Upgrade_Notes_Rain` |
| Rat King | Ultimate | `Ultimate 2 Rat King` | `Skill_Ultimate_2_Upgrade_Rat_King` |
| Vermin Massacre | Ultimate | `Ultimate 2 Explosion` | `Skill_Ultimate_2_Upgrade_Explosion` |

## Romeo

**Hero spelling:** `hero = "Romeo"` for `kind = "talent"`, and `hero = "Romeo"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Deadly Brambles | Attack | `Attack Rose Seed` | `Skill_Attack_Rose_Seed` |
| Kick | Attack | `Attack Kick` | `Skill_Attack_Kick` |
| Panache | Attack | `Attack Panache` | `Skill_Attack_Panache` |
| Relentless Assaults | Attack | `Attack Power Ripost` | `Skill_Attack_Power_Ripost` |
| Bursting Bloom | Power | `Power Burst` | `Skill_Power_Burst` |
| Healing Rose | Power | `Power Heal` | `Skill_Power_Heal` |
| Ice Rose | Power | `Power Chilled` | `Skill_Power_Chilled` |
| Swarm of Petals | Power | `Power Cone Attack` | `Skill_Power_Cone_Attack` |
| Thorny Rose | Power | `Power Trail` | `Skill_Power_Trail` |
| Burning Kiss | Special | `Special Ignite` | `Skill_Special_Ignite` |
| Kiss the Bride | Special | `Special Quest Dream Shard` | `Skill_Special_Quest_Dream_Shard` |
| Love Shield | Special | `Special Invulnerable` | `Skill_Special_Invulnerable` |
| Surge of bravery | Special | `Special Buff Attack` | `Skill_Special_Buff_Attack` |
| Floral Dodge | Defense | `Defense Power` | `Skill_Defense_Power` |
| Secret Weapon | Defense | `Defense Quest` | `Skill_Defense_Quest` |
| Selfless Defender | Defense | `Defense Shield` | `Skill_Defense_Shield` |
| Wind Spiral | Defense | `Defense AOE` | `Skill_Defense_AOE` |
| Broad Stroke | Dash | `Dash AOE Attack` | `Skill_Dash_AOE_Attack` |
| Flash of Steel | Dash | `Dash Attack Return` | `Skill_Dash_Attack_Return` |
| Love Thread | Trait | `Trait Beam` | `Skill_Trait_Beam` |
| Thorns Aura | Trait | `Trait AOE` | `Skill_Trait_AOE` |
| Fencing Reflex | Passive | `Attack Block` | `Skill_Passive_Attack_Block` |
| Burning Dance | Ultimate | `Ultimate 1 Ignite` | `Skill_Ultimate_1_Ignite` |
| Explosive Performance | Ultimate | `Ultimate 1 Projectile` | `Skill_Ultimate_1_Projectile` |
| Funeral Bouquet | Ultimate | `Ultimate 2 Attack Rose` | `Skill_Ultimate_2_Attack_Rose` |
| Tempestuous Roses | Ultimate | `Ultimate 2 Wide And AOE` | `Skill_Ultimate_2_Wide_And_AOE` |

## Scarlet

**Hero spelling:** `hero = "Red"` for `kind = "talent"`, and `hero = "Red"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Cleave | Attack | `Basic Cleave` | `Skill_Attack_Cleave` |
| Slash Flurry | Attack | `Attack Flurry` | `Skill_Attack_Flurry` |
| Wide Attacks | Attack | `Basic Wide Attacks` | `Skill_Attack_Wide_Attacks` |
| Devourer | Power | `Primary Wolf Quest` | `Skill_Power_Wolf_Quest` |
| Energy | Power | `Primary Extra Combo Points` | `Skill_Power_Extra_Combo_Points` |
| Evisceration | Power | `Primary Bleed` | `Skill_Power_Bleed` |
| Explosive Rush | Power | `Primary Triggers Special` | `Skill_Power_Triggers_Special` |
| Armor Break | Special | `Secondary Reduce Armour` | `Skill_Special_Reduce_Armor` |
| Distant Explosions | Special | `Secondary Can Hold` | `Skill_Special_Can_Hold` |
| Pulverize | Special | `Secondary Use Combo Points` | `Skill_Special_Use_Combo_Points` |
| Pyromania | Special | `Secondary Ignite` | `Skill_Special_Ignite` |
| Short Wick | Special | `Secondary Quick Bombs` | `Skill_Special_Quick_Bombs` |
| Aggressive Defense | Defense | `Defensive AOE On Trigger` | `Skill_Defense_AOE_On_Trigger` |
| Murderous Intent | Defense | `Defensive Combo` | `Skill_Defense_Combo` |
| On the Hunt | Defense | `Defensive Mark` | `Skill_Defense_Mark` |
| Shadow Strikes | Defense | `Defensive Human Quest` | `Skill_Defense_Human_Quest` |
| Double Strike | Dash | `Dash Attack` | `Skill_Dash_Attack` |
| Fan of Spikes | Dash | `Dash Projectiles` | `Skill_Dash_Projectiles` |
| Shapeshifter | Trait | `Trait Active` | `Skill_Trait_Active` |
| True Instincts | Trait | `Trait Better Forms` | `Skill_Trait_Better_Forms` |
| Adrenaline | Passive | `Passive Combo Use Bonus` | `Skill_Passive_Combo_Use_Bonus` |
| Savagery | Passive | `Passive Combo Chain` | `Skill_Passive_Combo_Chain` |
| Bone Cracker | Ultimate | `Ultimate 2 Explosif` | `Skill_Ultimate_2_Explosif` |
| Fiery Maw | Ultimate | `Ultimate 1 Fire` | `Skill_Ultimate_1_Fire` |
| Pack Leader | Ultimate | `Ultimate 2 Heal` | `Skill_Ultimate_2_Heal` |
| Reload | Ultimate | `Ultimate 1 Reload` | `Skill_Ultimate_1_Reload` |

## The Snow Queen

**Hero spelling:** `hero = "Snow_Queen"` for `kind = "talent"`, and `hero = "Snow_Queen"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Dual Lances | Attack | `Attack Dual` | `Skill_Attack_Dual` |
| Windy Lances | Attack | `Attack Seeking` | `Skill_Attack_Seeking` |
| Frost Surge | Power | `Power Hold` | `Skill_Power_Hold` |
| Hailstorm | Power | `Power Ice Waves` | `Skill_Power_Ice_Waves` |
| Shattering Blast | Power | `Power Shatter` | `Skill_Power_Shatter` |
| Snowball | Power | `Power Snowball` | `Skill_Power_Snowball` |
| Flurry of Shards | Special | `Special Extra Waves` | `Skill_Special_Extra_Waves` (description only) |
| Ice Cores | Special | `Special Icicles` | `Skill_Special_Icicles` |
| Ice Spray | Special | `Special Double` | `Skill_Special_Double` |
| Ice Clone | Defense | `Defense Clone` | `Skill_Defense_Clone` |
| Ice Shield | Defense | `Defense Shield` | `Skill_Defense_Shield` |
| Pirouette | Defense | `Defense Final` | `Skill_Defense_Final` |
| Strafe | Defense | `Defense Sends Attacks` | `Skill_Defense_Sends_Attacks` |
| Freezing Stars | Dash | `Dash Freeze Trap` | `Skill_Dash_Freeze_Trap` |
| Slide | Dash | `Dash Frost` | `Skill_Dash_Frost` |
| Lance Burst | Trait | `Trait Sends Attacks` | `Skill_Trait_Sends_Attacks` |
| Protective Crown | Trait | `Trait Shield` | `Skill_Trait_Shield` |
| Radiant Crown | Trait | `Trait Charge` | `Skill_Trait_Charge` |
| Rupture | Trait | `Trait Quest` | `Skill_Trait_Quest` |
| Cold Heart | Passive | `Passive Chilled Crit` | `Skill_Passive_Chilled_Crit` |
| Frost Queen | Passive | `Passive Better Frost` | `Skill_Passive_Better_Frost` |
| Frostbite | Passive | `Passive Damage To Chilled` | `Skill_Passive_Damage_To_Chilled` |
| Ice Beam | Ultimate | `Ultimate 1 Ice Beam` | `Skill_Ultimate_1_Upgrade_Ice_Beam` |
| Rending Storm | Ultimate | — | `Skill_Ultimate_2_Upgrade_Abillity_Blast` |
| Royal Ray | Ultimate | `Ultimate 1 Casts Trait` | `Skill_Ultimate_1_Upgrade_Casts_Trait` |
| Shattering Storm | Ultimate | `Ultimate 2 Shatter` | `Skill_Ultimate_2_Upgrade_Shatter` |

## Sun Wukong

**Hero spelling:** `hero = "SunWukong"` for `kind = "talent"`, and `hero = "Sun_Wukong"` for `kind = "skill"`.

| Talent in game | Ability | Search word | Rename with |
|---|---|---|---|
| Celestial Pillar | Attack | `Attack Finisher` | `Skill_Attack_Finisher` |
| Ch'i Outburst | Attack | `Attack Beam` | `Skill_Attack_Beam` |
| Stick Twirl | Attack | `Dash Attack` | `Skill_Attack_After_Dash` |
| Airbender | Power | `Power Extra Targets` | `Skill_Power_Extra_Targets` |
| Focused Strikes | Power | `Power Hold` | `Skill_Power_Hold` |
| Thundercloud | Power | `Power Lightning` | `Skill_Power_Lightning` |
| Mantra of Balance | Special | `Special Debuff` | `Skill_Special_Debuff` |
| Resonance | Special | `Special Triggers Stance` | `Skill_Special_Triggers_Stance` |
| Ringing Beads | Special | `Special Attack AOE` | `Skill_Special_Attack_AOE` |
| Sacred Seal | Special | `Special Explosion` | `Skill_Special_Explosion` |
| Ōm | Special | `Special Beads Increase` | `Skill_Special_Beads_Increase` |
| Divine Palm | Defense | `Defense Perfect` | `Skill_Defense_Perfect` |
| One-Inch Punch | Defense | `Defense Retaliate` | `Skill_Defense_Retaliate` |
| Stone Monkey | Defense | `Defense Quest` | `Skill_Defense_Quest` |
| Sprint | Dash | `Dash Sprint` | `Skill_Dash_Sprint` |
| Fiery Dragon | Trait | `Trait Fire` | `Skill_Trait_Fire` |
| Frost Tiger | Trait | `Trait Frost` | `Skill_Trait_Frost` |
| Mind Fortress | Trait | `Trait Longer Effects` | `Skill_Trait_Longer_Effects` |
| Supreme Polarity | Trait | `Trait Better Stances` | `Skill_Trait_Better_Stances` |
| Way of Awakening | Trait | `Trait Awakened` | `Skill_Trait_Awakened` |
| Fiery Golden Eyes | Passive | `Passive Reveal` | `Skill_Passive_Reveal` |
| Thirst for Immortality | Passive | `Passive Objects Quest` | `Skill_Passive_Objects_Quest` |
| Army of Monkeys | Ultimate | `Ultimate 1 More Monkeys` | `Skill_Ultimate_1_More_Monkeys` |
| Divine Beverage | Ultimate | `Ultimate 2 Omnipotence` | `Skill_Ultimate_2_Omnipotence` |
| Mantra of Replication | Ultimate | `Ultimate 1 Special Monkey` | `Skill_Ultimate_1_Special_Monkey` |
| Perfect Copy | Ultimate | `Ultimate 2 Perfect Copy` | `Skill_Ultimate_2_Perfect_Copy` |