# Ravenswatch Mod Manager — Full documentation

Concatenated plain text of every docs page. Source: https://docs.rsmm.me


---

# Engine internals

> Asset cipher and cooked-format internals that ground the tooling.

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

:::note[Historical log]
This file is a reverse-engineering record. Where it references
`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 the
[development setup](/contributing/setup/) for the current repo layout.
:::

:::tip[Companion docs (newer)]
This file covers the asset pipeline + cipher + cooked-file format. For the
binary RE that backs `rsmm.call`, see:

- [RE pipeline](/reverse-engineering/pipeline/) — Ghidra setup, scripts, regen workflow.
- [Calling game functions](/reverse-engineering/calling-game-functions/) — runtime Lua API.
- [Seed + mapgen](/reverse-engineering/seed-mapgen/) — worked example.
- [Uncooked assets](/guides/uncooked-assets/) — `data/uncooked/` extract + texture container details.
:::

## Overview

This document consolidates observations from the DarkTalesResources directory in Ravenswatch, in a Steam + Proton environment. The structure points to a cooked, indexed, and heavily obfuscated asset pipeline, similar to Unreal Engine cooked content or a proprietary equivalent.

## Root Structure

Main directory:

```text
/home/ovilli/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/common/Ravenswatch
```

Key components:

- `_Cooking/`
- `UsedRscList.ot`

### `_Cooking/`

- Contains processed runtime assets
- Deep nested folders with obfuscated names
- Represents final cooked game data

### `UsedRscList.ot`

- Central resource index / manifest
- Maps logical IDs to actual asset files
- Core lookup table for runtime loading

## File Types

- `.tpi` - Final packaged asset
- `.tpdl` - Bundled/cooked resource container
- `.yqz` - Compressed or encoded payload
- `.jzy` - Intermediate cooked asset
- `.rvl` - Variant layer / resource variant

These appear to be engine-specific formats.

## Naming and Obfuscation

Examples:

```text
Qqpiwuq
vngtquv
UTS_Fgztxgz
Ni_Qqpiwuqt_Sngugbiquv
Qdlqv!6p6_Susvigl_01
```

Characteristics:

- Pseudo-random consonant-heavy strings
- No semantic meaning preserved
- Consistent structured naming
- Prefix grouping such as `UTS_`, `Ni_`, and `Qdlqv!`

## Encoding Behavior

Example:

```text
UTS_Fgztxgz~KWH.plv.GrbglQqpi.yqz
```

Breakdown:

- `UTS_` - category or group
- `Fgztxgz` - base identifier
- `KWH` - variant tag
- `.plv` / `.yqz` - container layers

This likely reflects a substitution or hash-based naming system.

How a mod's plaintext path resolves to the obfuscated file on disk:

```mermaid
flowchart LR
    P["Decoded path<br/>Ui/.../Portrait.png"] -->|"Caesar cipher<br/>cipher.py / find_iyg.py"| E["Encoded name<br/>UTS_Fgztxgz~KWH.yqz"]
    M["UsedRscList.ot"] --> AM["asset_map.json<br/>decoded ↔ encoded"]
    P --> AM
    AM --> E
    E --> D["_Cooking/&lt;encoded&gt;<br/>(file replaced in place)"]
```

## Variant System

Examples:

```text
Qdlqv!6p6_Susvigl_01
Qdlqv!3p3_Blrbmqu_Turjv_01
```

Interpretation:

- Quality tiers or build configurations
- Platform or gameplay variants
- Procedural asset duplication system

The same base asset appears in multiple variants.

### Variant Flags

Resolution / build splits seen in the data:

- `6p6`
- `3p3`

These consistently appear in:

- Qdlqv asset groups
- NgumAdllv pipeline outputs
- Srxjrvdidrzv bundles

Likely meaning:

- Different quality tiers
- Different platform scaling sets
- Or level-of-detail buckets

## Asset Pipeline

```mermaid
flowchart TD
    A["Raw assets"] --> B["_Cooking<br/>(preprocessing)"]
    B --> C[".tpdl bundles"]
    C --> D[".tpi final assets"]
    D --> E["UsedRscList.ot index"]
    E --> F["Runtime loader<br/>resolves assets"]
```

## Resource Index

`UsedRscList.ot` appears to serve as the main lookup layer.

Role:

- Maps logical identifiers to physical files
- Prevents direct filesystem scanning
- Acts as the core runtime lookup system

Evidence:

- No readable paths in the executable
- Assets are only resolved through the cooked system

## Frequency Analysis

From extracted filenames, the most frequent base tokens were:

- `01` - 3302
- `Aqurqv` - 3227
- `Aqur` - 2562
- `Wkglrz` - 2480
- `Mzqxdqv` - 2346
- `NgumAdllv` - 2238
- `FbqzqusOacqbiv` - 2046
- `VZ` - 2045
- `Wzdxgidrzv` - 1990
- `Qqpiwuqv` - 1507
- `Srxxrz` - 1267
- `Firux` - 1091
- `Hquldz` - 1048
- `KWH` - 996

## Asset Group Behavior

Example grouping pattern:

```text
Qdlqv!6p6_Susvigl_01
Qdlqv!6p6_Blrbmqu_01
Qdlqv!3p3_Blrbmqu_01
```

This suggests:

- Same asset family
- Multiple configuration outputs
- Shared base asset name plus variant suffix

## Pipeline Structure Identified

The system appears layered:

- Engine / Runtime Layer
  - Tokens: `Cooking`, `Qqpiwuq`, `tpi`, `jzy`
  - Role: pipeline and runtime orchestration, likely a noise layer in the analysis

- Asset Namespace Core
  - Tokens: `MzidisFqiidzyv`, `qzidis`, `NgumAdllv`
  - Role: root asset generation system

- Gameplay / System Modules
  - Tokens: `Sngugbiquv`, `Wzdxgidrz`, `Mzqxdqv`, `3N`
  - Role: gameplay mechanics and logic systems

- Entity / Content System
  - Tokens: `Fqiidzyv`, `Hgiqudgl`, `VZ`, `01`
  - Role: entity definitions and content registry

- Feature / Specialized Subsystems
  - Tokens: `KWH`, `GrbglQqpi`, `KlraglMzidisDglwqFqiidzyv`
  - Role: isolated feature modules or rendering/UI systems

- Container / File Format Layer
  - Tokens: `tpdl`, `rvl`, `vngtquv`, `Fngtqu2`, `Ni`
  - Role: packaged asset formats and compiled containers

## Key Structural Insight

The asset system is not random obfuscation. It appears to be a deterministic hierarchical naming system:

```text
Root Namespace -> Variant Expansion -> Subsystems -> Containers
```

## Observations

### Strong signals of:

- Packed / cooked asset system
- Deterministic naming obfuscation
- Multi-tier asset generation for performance scaling
- Platform-specific compiled bundles

### Weak signals, not confirmed:

- Unreal Engine-style cooking pipeline
- Compression and symbol mangling
- Resource manifest-driven loading system

## Index Summary

Main system:

- Base assets -> obfuscated tokens
- Variants -> `6p6 / 3p3`
- Build tags -> `KWH`
- Pipeline outputs -> `.plv / .rvl / .tpdl`

## Additional Examples

```text
AssetName~KWH.plv.GrbglQqpi.yqz
AssetName.yugjn.rvl.Fngtqu2.tpdl
```

Interpretation:

- `~KWH` - variant tag, likely platform or build config
- `.plv / .rvl / .tpdl` - cooked asset formats
- `GrbglQqpi / Fngtqu2` - intermediate compiled asset bundles
- `_Cooking` - build pipeline output directory

## Summary

This looks like a fully cooked and indexed game asset system with:

- Obfuscated identifiers
- Variant-based duplication system
- Centralized manifest indexing
- Runtime-only resolution

File names are not meaningful without decoding the index layer.

## Next Steps

1. Parse `UsedRscList.ot` into a mapping table
2. Classify file formats (`.tpdl`, `.tpi`, `.yqz`)
3. Inspect headers for compression signatures
4. Compare repeated prefixes for decoding patterns
5. Build an asset-to-file reconstruction script

## oCTextSaver — engine serialization format (CONFIRMED 2026-05-14)

The engine ships data in **two** forms:

* **Uncooked text** — `.ot` files starting with `//OPROJECT oCTextSaver`.
  Plain ASCII. Self-describing. Game ships at least
  `DarkTalesResources/ApplicationSettings.ot` in this form and loads it
  directly (no cooking). Format:

```
//OPROJECT oCTextSaver
//V1.16
//FLAGS=0
*Classes=N
*Class0=ClassName[class_id](v_major.v_minor)<[parent_class_id]
...
*Objects=M
*SingleObject0=Cidx           <- root object references
...
SingleObject0=C0              <- actual data, by class index
{
    plain_field=value
    typed_field|name=value    <- type prefix: b=bool, i=int, u=uint, f=float
    nested_obj=Cidx           <- nested instance reference
    {
        ...nested data block...
    }
}
```

* **Cooked binary** — `.gen` files (decoded extension; on disk encoded
  via the substitution cipher) under `DarkTalesResources/_Cooking/`.
  Same logical data, packed binary. Layout reverse-engineered so far:

```
[0x00] u32    header_field_0    = 0x10
[0x04] u32    flags             = 0x01
[0x08] str4   "Cooked"          (length-prefixed)
[..]   u32    extra             = 0x01
[..]   u8     tag               = 0x31
[..]   u32    magic             = 0xAABB1111
[..]   u32    class_count
[..]   N * { u32 name_len; bytes name; u32 class_id; u32 v_major; u32 v_minor; u32 parent_id }
[..]   --- object table + property streams (NOT YET DECODED) ---
```

Section markers seen later in stream: `0xAABB1111` and `0xAABB2222`.
Strings inside the data segment are length-prefixed too (e.g. property
values that are strings).

### Decoder

`tools/ot_decoder.py` parses the header + class table. Confirmed working
against `MzidisFqiidzyv/Xziqugbidkq_Srxxrz/Grbgl_Xziqugbidkq_Oacqbi_Hrtql.qzidis.ri.MzidisFqiidzyvLqvrwubq.yqz`
— produces a valid `*ClassN=...` table identical in spirit to the text
form. Class IDs and parent IDs cross-reference correctly.

### Asset extension chains

Cipher tables in `find_iyg.py` finalized 2026-05-14 (fixed bad mappings on
`y`, `Z`, etc). Re-decoded `asset_map.json` now produces clean filenames
end-to-end. Extension counts (top 20):

```
5064  .fbx                                          (raw mesh source)
4373  .entity.ot                                    entity definitions
4373  .entity.ot.EntitySettingsResource.gen         cooked counterpart
2837  .fbx.Geometry.gen
2679  .mat.ot                                       materials
2679  .mat.ot.Material.gen                          cooked counterpart
2661  .png
2654  .png.Texture.dxt
2229  .vfx.ot                                       VFX defs
2229  .vfx.ot.ScheduledVfxSettings.gen              cooked counterpart
2216  .fbx.Animation.gen
2058  .tga
1511  .tga.Texture.dxt
 544  .tga.Texture.nrm
 357  .level.ot                                     level defs
 357  .level.ot.GameStream.gen
 210  .tiledef.ot                                   tile defs
 210  .tiledef.ot.DtTileDefinition.gen
 204  .globalvalue.ot                               global values
 204  .globalvalue.ot.GlobalEntityValueSettings.gen
```

:::tip[Levels have their own page]
A cooked level is four nested layers, not one container, and the inner
`BufferLen` decides how much of it the engine ever reads. See
[Level format and build path](/reverse-engineering/level-format/).
:::

Key pattern: every `*.ot` source has a paired `*.ot.<KindResource>.gen`
cooked output. Means engine knows both forms exist; cooked form is the
*output* of cooking the text source.

The dominance of `.ot` suffixes means the game is fully data-driven from
oCTextSaver files. Modifying any of them gives us native gameplay
control, including UI / menus.

### Main menu asset locations

Decoded asset map points to:

```
encoded:  KgxqJdv\HgdzHqzw.lqkql.ri
decoded:  GameUis\MainMenu.level.ot                (text source, may not ship)

encoded:  Oi\KgxqJdv\HgdzHqzw.lqkql.ri.KgxqFiuqgx.yqz
decoded:  Ot\GameUis\MainMenu.level.ot.GameStream.gen   (cooked binary, ships)
```

The encoded layout uses Windows backslashes; engine loads via
`DarkTalesResources/_Cooking/<encoded-path>` (UsedRscList.ot only lists
encoded names).

### Probe plan — does the engine read uncooked .ot at runtime?

We know `ApplicationSettings.ot` is loaded uncooked (it ships as plain text).
Open question: is that special-cased, or does every `.ot` source get probed
before the engine falls back to the cooked `.gen`?

Step 1 — passive trace via Proton's own logging (no wrapper script;
pressure-vessel strips env from wrappers, so vars must be in launch
options directly):

  Steam Launch Options:
      WINEDLLOVERRIDES="winhttp=n,b" PROTON_LOG=1 WINEDEBUG=+file %command%

  Run game to main menu, quit. Log lands at:
      ~/.var/app/com.valvesoftware.Steam/steam-2071280.log

  Parse with:
      tools/trace_parse.py        # default path baked in

### Probe result (2026-05-14): Outcome B — cooked-only

One launch + main-menu + quit produced 203k log lines. Parser output:

  * 53,892 file opens under `DarkTalesResources/_Cooking/` (encoded names)
  * 85 opens outside `_Cooking/` — all to *named config files*:
        ApplicationSettings.ot     (uncooked oCTextSaver text — editable!)
        EngineSettings.ini
        UsedRscList.ot
        oFMod.ini
        Input/PadHid*.ini
        Ui/Ravenswatch_Cursor.cur

There are **zero** probes for uncooked `.ot` anywhere in the asset tree.
ApplicationSettings.ot is a one-off, special-cased config file the engine
reads at startup. The asset pipeline at runtime is cooked-only: every
asset is loaded by its *encoded* name under `_Cooking/` as binary `.gen`
(or `.tpi`, `.dxt`, `.bank`, etc).

Implication: to override any asset (including MainMenu), we must produce
a binary cooked file at the matching encoded path. Path forward:

  1. Finish object/property parser in `tools/ot_decoder.py`
  2. Build a re-encoder: text `.ot` → binary `.gen`
  3. Backup + replace the target cooked file at its encoded path

### Override mechanism — CONFIRMED 2026-05-14

End-to-end override of a cooked asset works with **no engine hook,
binary edit, or re-encoder**. Procedure that succeeded:

  1. Took two cooked Texture.dxt files in the same encoded directory:
     - target  = `_Cooking/Jd/BrrmHqzw/Aqurqv!JX_AqurTruiugdi_Lrxqr_Wbidkq.jzy.Qqpiwuq.tpi`
                 (decoded: `Ui/BookMenu/Heroes/UI_HeroPortrait_Romeo_Active.png.Texture.dxt`)
     - donor   = same dir, `Aqurqv!JX_AqurTruiugdi_FwzRwmrzy_Wbidkq.jzy.Qqpiwuq.tpi`
                 (SunWukong Active)
  2. Backed up target, copied donor's bytes onto target's path.
  3. Launched the game. Hovering Romeo in the hero-select screen showed
     SunWukong's portrait instead of Romeo's.

Implications:

- Mods at this layer are *file-replacement packages*. A mod just
  ships cooked `.gen` / `.tpi` files; loader symlinks or copies them
  onto the encoded paths under `_Cooking/`.
- No need to defeat anti-tamper for asset overrides — the engine itself
  loads them through the normal cooked-asset pipeline.
- We do *not* need the full text->binary re-encoder to ship a v1 mod
  manager. v1 = asset overrides. v2 = entity-level menu mods requiring
  the encoder.

Failed first attempt is also worth recording: we initially swapped
`Ui/Heroes/Romeo/Portrait_Romeo_01.png.Texture.dxt` and saw no change
in-game. That file is referenced from somewhere else (probably the
encounter / pause card UI), not from the main hero-select tile. The
hero-select uses the `Ui/BookMenu/Heroes/UI_HeroPortrait_<hero>_Active`
set. Lesson: hero-select tiles live under `BookMenu`, not `Heroes`.

### Mod manager v1 — `tools/apply_mods.py`

Because cooked overrides are accepted by the engine without any runtime
hook (see above), the v1 mod manager doesn't need the DLL, the IO hook,
or the Vulkan layer. It is a single Python script:

  tools/apply_mods.py              # apply current mods/ state
  tools/apply_mods.py --restore-all
  tools/apply_mods.py --list
  tools/apply_mods.py --dry-run

A mod is a directory under `mods/<ModId>/`:

  mods/<ModId>/
    manifest.toml          # id/name/version/author/enabled
    assets/<decoded-path>  # mirrors the human-readable decoded path

The script:

  1. Walks `mods/`, parses each manifest, collects override files.
  2. Resolves each decoded path -> encoded path via `asset_map.json`.
  3. Diffs against `<install>/DarkTalesResources/_Cooking/.rsmm_state.json`.
  4. For each newly-active override:
       - back up original cooked file to `<file>.rsmm.bak` (once)
       - copy mod file onto the encoded path
  5. For each no-longer-active override: move `.rsmm.bak` back.
  6. Writes new state file (sha1 of mod file + original).

Verified end-to-end with `mods/ExampleMod/` shipping Romeo's
`UI_HeroPortrait_Romeo_Active.png.Texture.dxt` replaced by SunWukong's.

### ApplicationSettings.ot — high-value tweakables

`DarkTalesResources/ApplicationSettings.ot` is plain-text oCTextSaver
loaded uncooked. Beyond game-balance fields, it contains:

- **External URLs** at lines 6668-6671. Editing them re-targets the
  main-menu button actions:

  ```
  m_sDiscordUrl     = https://discord.gg/passtechgames
  m_sPatchNoteUrl   = https://www.passtechgames.com/ravenswatch-year-1
  m_sBugReportsUrl  = https://my.nacongaming.com/support/game/ravenswatch
  m_sNewUpdateUrl   = https://store.steampowered.com/dlc/2071280/
  ```

  Combined with the text-bank relabel of `Common~EN:Menu_Discord` ->
  "Mods (RSMM)", this is enough to turn the Discord button into a real
  mod-manager entry point that opens an arbitrary URL (a GitHub repo, a
  locally-hosted mod-list HTML page, etc).

- **Cheats UI layer** at line 5573 (`Vector[13] = oCGameUiLayerDesc` with
  `m_sName=Cheats`, `m_iPriority=100`). The engine *registers* a Cheats
  UI layer; we don't yet know how to *show* it (likely gated by a hard
  check in `Ravenswatch.exe`, possibly a debug build flag or hotkey
  binding). Worth investigating: the layer's hash-ID 4-tuple
  (2586023665, 1153599675, 3382377381, 3432447172) may correlate with a
  runtime call site.

- **UI layer roster** (in order): Ground, Empty, LifeBar, InGame,
  Sandman, HUD, InGame menus, Book menus, Video, Loading, Fade In/Out,
  System messages, Now Saving, Watermarks, **Cheats**, Child, Woman, Man,
  Old Woman, Old Man, Corpse, Hero_Common.

### Adjacent attack surfaces (already editable, no encoder needed)

  * **`ApplicationSettings.ot`** — plain-text oCTextSaver, loaded
    uncooked. Contains: `oCGameUiApplicationSettingsSection`,
    `oCFlagsApplicationSettingsSection`, modifier sections, NG+ rules,
    bark configuration. Flipping flags or adding UI layer descriptors
    here is the cheapest mod hook the game offers.
  * **`EngineSettings.ini`** — top-level engine config. Likely contains
    renderer/loader flags. Worth scanning for path-redirect or
    mod-friendly options.
  * **`UsedRscList.ot`** — the manifest. Adding entries (encoded names)
    may make the engine accept *new* cooked files that don't exist in
    the shipped manifest. Untested but plausible.

  Outcome A: log contains opens of paths ending `.ot` outside `_Cooking/`
      -> engine probes for uncooked override. We can drop modded `.ot`
         files at those paths and skip the re-encoder entirely.

  Outcome B: log only shows opens inside `_Cooking/` for encoded names
      -> engine is cooked-only. Path forward is text `.ot` -> binary `.gen`
         re-encoder + replace the cooked file (with backup).

### Path to in-game native UI

Once probe outcome is known:

1. (If outcome B) Finish object/property parser in `ot_decoder.py`, then
   build the re-encoder (text `.ot` -> binary `.gen`).
2. Pull the MainMenu level — its cooked asset is at
   `DarkTalesResources/_Cooking/Oi/KgxqJdv/HgdzHqzw.lqkql.ri.KgxqFiuqgx.yqz`.
3. Inject a "Mods" button entity that references existing widget classes
   already used by the menu.
4. Wire the button: either (a) the button triggers an existing engine
   event we hijack from our `winhttp.dll` loader, or (b) we add new
   entity nodes that drive a native widget tree for the mod list.

## Class survey (2026-05-14)

`tools/class_survey.py` walks every `.yqz` in `_Cooking/` and buckets by
root class name. Counts + body-size spread highlight the easiest classes
to reverse-engineer (uniform body size = fixed-layout schema, no
length-prefixed strings).

Top of the table (24 distinct root classes total):

```
cls                                                count   min    max  uniform
oCDtEnemyCampDifficultyDefinition                      6    18     18  *
GameModeDefaultDefinition                              1    30     30  *
VersionDefinition                                      1 13303  13303  *
oCEntitySettingsResource                            4384    45   5150
oCGeometry                                          2842   200 4305425
oCMaterial                                          2686   159    364
oCScheduledVfxSettings                              2229    22     74
oCAnimation                                         2216   198  48932
oCGameStream                                         357    24  21778
oCDtTileDefinition                                   210    70    177
oCGlobalEntityValueSettings                          204    20     31
oCDtEnemyDefinition                                   80    28    172
AchievementDefinition                                 42    32     36
oCDtEnemyTribeDefinition                              24    21     70
GameModifierDefinition                                22    29     32
oCDtHeroDefinition                                    12    32     87
oCCollisionMesh                                       11  1032  31950
oCDtRewardDefinition                                   6    26     30
oCDtIngredientDefinition                               6    43     75
oCTexture                                              5  1062 4194371
ChallengeDefinition                                    5   331    430
oCDtEnemyCampTierDefinition                            4    22     26
oCDtMapDefinition                                      4   141   6288
oCDtDreamShardDefinition                               4    79     80
```

Narrow-spread classes are prime first targets for empirical schema
extraction: `oCMaterial` (~2x spread, almost certainly string-content
variation around a fixed framework), `oCScheduledVfxSettings`,
`oCGlobalEntityValueSettings`, `AchievementDefinition`, `GameModifierDefinition`.

### Decoded schemas (`tools/class_diff.py`)

`tools/class_diff.py <ClassName>` walks all cooked files of that class
and reports which byte offsets vary across instances. Constant offsets =
struct framework; varying offsets = data fields. Schemas decoded:

#### `oCDtEnemyCampDifficultyDefinition` (18 bytes, 6 samples)

```
0x00  u32     reserved = 0
0x04  u8      flag1 = 1
0x05  u8      flag2 = 1
0x06  u8      difficulty_index   (varies 1..5)
0x07  3-byte  padding
0x0a  float   min_value          (e.g. 40.0)
0x0e  float   max_value          (e.g. 45.0)
```

Reveals camp difficulty bands. Modders can change spawn intensity per
band by patching the two floats.

#### `oCGlobalEntityValueSettings` size=23 (143 instances)

```
0x00  u32     reserved = 0x00000003
0x04  u32     flags
0x08  u32     reserved = 0
0x0c  float   VALUE                  <-- the single payload float
0x10  u32     reserved = 0
0x14  u8      end_flag = 0
0x15  u8/u16  reserved = 0
0x12  u8      reserved = 0
0x14  u32     reserved (END marker at body end)
```

143 game-balance constants. Sample decoded names + current values:

```
   -100.0000   Hero_Is_Vulnerable_Value
     25.0000   Shield_On_Combat_Modifier
      5.5000   Ignite_Duration_Value
      5.0000   Bleed_Duration_Value
      5.0000   Chilled_Duration_Value
      5.0000   Regeneration_Duration_Value
      1.0000   Chapter_Scaling_Enemies_Damage_Factor
      1.0000   Chapter_Scaling_Enemies_Max_Health_Factor
      1.0000   Resistant_III_Value
      0.7500   Resistant_II_Value
      0.5000   Resistant_I_Value
      0.2500   ActivityScore_StoryQuestValue
      0.2000   Card_Attack_Damage
      0.1000   ActivityScore_MiniBossValue
      0.0100   Card_Heal_Ratio
   ...
```

Tooling: `tools/make_global_value_mod.py` generates a complete mod
directory that patches any subset of these floats. Example:

```sh
tools/make_global_value_mod.py --mod-id LongerStatusEffects \\
    Bleed_Duration_Value=10 Ignite_Duration_Value=11
tools/make_global_value_mod.py --list-values    # see all 143
```

The other 60 size=20 / size=31 instances have a different framework
(no float payload, mostly enum/flag-like), not handled yet.

#### `oCDtRewardDefinition` (26 or 30 bytes, 6 samples)

Zero varying offsets across the 6 instances in each size bucket. The
reward identity comes from the filename / encoded path; the file body
is template-fixed. No useful mod surface here without the re-encoder.

#### `AchievementDefinition` (32 or 36 bytes, 42 samples)

Almost entirely constant; only 2 bytes vary (achievement flags) at the
tail of the size=36 bucket.

#### `GameModifierDefinition` size=29 (19 samples)

```
0x00  u32     reserved = 0x05
0x04  u32     reserved = 0x02
0x08  u32     reserved = 0
0x0c  u8      flag = 1
0x0d  END marker (inner section)
0x15  float   modifier_value   (e.g. -0.15, +0.10)
0x19  u16     reserved
0x1b  u16     reserved
```

Modifier-system values (damage/speed/etc deltas applied as game
modifiers). 4-byte float at body-offset 0x15.

### Translation text banks (`_Cooking/Qqpi/`)

`Qqpi/` decodes to `Text/`. Each translatable subject is two files:

```
<Name>~GAM.xls.LocalText.gen           # base: ordered list of keys
<Name>~GAM.xls.LocalText.gen.Lang<XX>  # one per language: ordered values
```

Format of both base and per-language files:

```
0x00  u32   header_size = 0x10
0x04  u32   reserved    = 0
0x08  u32   reserved    = 0
0x0c  u32   entry_count
0x10  u32   entry_count          (same; possibly capacity)
0x14  ---- entries ----
        u32 byte_len_n
        n bytes of UTF-8
```

Key[i] in the base maps to Value[i] in each language file. No internal
section markers. No checksum. Trivial to edit.

Language-code mapping (encoded suffix on disk -> decoded ISO code):

```
GgzyMU = LangEN   GgzyEW = LangJA   GgzyIO = LangKO
GgzyLJ = LangRU   GgzyMF = LangES   GgzyNM = LangDE
GgzyTG = LangPL   GgzyVL = LangFR   GgzyXQ = LangIT
GgzyTQ-BL = LangPT-BR  GgzyYA-F = LangZH-S  GgzyYA-Q = LangZH-T
GgzyLWR = LangRO
```

Tool: `tools/make_text_mod.py` lists keys/values and generates a mod
that overrides them. Confirmed in-game 2026-05-14 by renaming
`Common_EN:Menu_Discord` from "Discord" to "Mods (RSMM)" — visible on
the main menu.

`tools/apply_mods.py` resolves the `.Lang<XX>` suffix without needing
asset_map entries for every sibling.

### oCEntitySettingsResource — empirical structure (body <= 80)

Of the 4384 `oCEntitySettingsResource` cooked files, 1522 have a body
section <= 80 bytes (i.e. an entity with no/few extra components). Diff
of the smallest few shows an identical framework — they vary only in a
single 16-byte field that's clearly per-entity unique:

```
0x00  03 00 00 00          u32 = 3                (object count?)
0x04  [01 00 00 00]         u32 = 1   (optional; absent in body=45 sample)
0x08  00 00 00 00           u32 = 0
0x0c  00                    u8  = 0   (padding/alignment)
0x0d  10 00 00 00           u32 = 0x10 (length-of-GUID?)
0x11  <16 bytes>            GUID (entity ID — unique per file)
0x21  00 00 00 00           u32 = 0
0x25  ff ff ff ff           u32 = -1  (no parent / null reference)
0x29  00 00 00 00           u32 = 0
0x2d  22 22 bb aa           inner END marker
```

So every entity carries a 128-bit GUID. That's what the engine uses to
refer to entity instances across files. Implications:

- Adding a new entity to a level (e.g. a "Mods" button to MainMenu)
  needs a freshly-minted 128-bit ID. UUIDv4 is the obvious choice; needs
  validation that the engine accepts any unused value.
- Editing existing entities is safe; we don't need to change the GUID.

This is the most concrete piece of `oCEntitySettingsResource` schema we
have so far. With ~80 small-body samples, more byte-level diffing should
recover the rest of the framework.

### Title menu entity layout (`Title_Menu_Ui.entity.ot.EntitySettingsResource.gen`)

<details>
<summary>Full byte-level breakdown of the title-menu cooked file (section map + clone walkthrough)</summary>

Decoded enough of the title-menu cooked file to *add* a real new button
to the menu without writing a full re-encoder.

`Title_Menu_Ui` registers 55 component classes (oCEntity*, oCUI*,
oC2dElement*, oCFMod*, etc.) and contains 66 sections in the cooked
file. Sections are not flat — many are bracketed BEGIN/END blocks
containing one entity component each.

Top-level section payload starts with a u32 *class index* (selecting the
component class from the file's class table), followed by an inner
parent-ref block, then a self-GUID + length-prefixed internal name, then
class-specific payload bytes. So the layout of *every* top-level
component section is:

```
[ 0] MARK_BEGIN (outer)
[ 4] u32   class_index           # into local class table
[ 8] MARK_BEGIN (inner parent-ref block)
[12] u32   = 0x18                # block size marker
[16] 16B   parent GUID           # often all-zero (no parent ref)
[32] u32   parent path strlen    # often 0
[..] N bytes UTF-8 parent path
[..] MARK_END
[..] 16B   self GUID
[..] u32   strlen
[..] N bytes UTF-8 internal name
[..] class-specific payload
[..] MARK_END (outer)
```

For `oCEntityCpntStateSettings` (class index 7 in this file), the
class-specific payload includes a *picker array* — an ordered list of
references to other entity components in the same file. Format:

```
[ ..] u32   picker_count
[ ..] picker_count * { MARK_BEGIN; u32(0x18); 16B target GUID;
                       u32 path strlen; path UTF-8; MARK_END }
```

Each picker path is `[ClassTag] <Hierarchy\Path\To\Component>` where
ClassTag identifies the referenced component class:

| ClassTag          | Component class                            |
|-------------------|--------------------------------------------|
| Spawner Value     | oCEntityCpntSpawnerValueSettings           |
| Entity Spawner    | oCEntityCpntEntitySpawnerSettings          |
| Window Ui         | oCEntityCpntWindowUiSettings               |
| State             | oCEntityCpntStateSettings                  |
| Timer             | oCEntityCpntTimerSettings                  |
| FMod Event        | oCEntityCpntFModEventSettings              |
| Game Ui           | oCEntityCpntGameUiSettings                 |
| Picture Ui        | oCEntityCpntPictureUiSettings              |
| Cpnt Value Tester | (one of the *TestSettings classes)         |
| String Format     | oCEntityCpntStringFormatValueSettings      |

The title menu's `State Init` state has a 10-entry picker array — five
buttons × two component refs each (Spawner + Text):

```
[Spawner Value] Title_Menu_Ui\Old Menu\Play Button Text
[Entity Spawner] Title_Menu_Ui\Old Menu\Play Button Spawner
[Spawner Value] Title_Menu_Ui\Old Menu\Discord Button Text
[Entity Spawner] Title_Menu_Ui\Old Menu\Discord Button Spawner
[Spawner Value] Title_Menu_Ui\Old Menu\Patch Button Text
[Entity Spawner] Title_Menu_Ui\Old Menu\Patch Button Spawner
[Spawner Value] Title_Menu_Ui\Old Menu\Bug Button Text
[Entity Spawner] Title_Menu_Ui\Old Menu\Bug Button Spawner
[Spawner Value] Title_Menu_Ui\Old Menu\Exit Button Text
[Entity Spawner] Title_Menu_Ui\Old Menu\Exit Button Spawner
```

Each button spawner section (`oCEntityCpntEntitySpawnerSettings`)
references the template `EntitySettings/GameUis/Common_Ui/Title_Menu_Button.entity.ot`,
so each button is an instance of the same template. Each button text
section (`oCEntityCpntSpawnerValueSettings`) back-references its
spawner by full picker path AND by raw 16-byte target-GUID.

**Add-button strategy** (implemented in `tools/make_real_menu_button_mod.py`):

1. Clone the Discord Button Spawner section bytes; rewrite self-GUID to
   a fresh UUID; substring-rename "Discord Button" -> "Mods Button" in
   every length-prefixed string (recomputing strlen prefixes).
2. Clone the Discord Button Text section bytes; rewrite self-GUID; swap
   the back-reference target-GUID from the Discord Spawner's GUID to
   the new Mods Spawner's GUID; substring-rename "Discord Button" ->
   "Mods Button".
3. In the State Init section, increment picker_count 10 -> 12 and
   append two new picker entries pointing at the new Spawner + Text
   clones by GUID + path.
4. Splice the patched State Init back into the cooked file; append the
   two cloned sections at the end of the file. Marker-balance is
   preserved end-to-end; no section sizes are stored anywhere so
   variable-length splices are safe.

Successful tests confirm:
- Patched file parses cleanly through `tools/ot_decoder.py` (68 top-
  level sections, picker array now has 12 entries).
- Engine accepts the file at runtime (TBD — needs in-game verification).

Known open question after applying the patch:
- The clone shares button position with Discord; if positions are
  explicit floats inside the spawner payload (likely), both buttons
  render on top of each other. If the NavigableZone auto-stacks, the
  new button appears below Exit. Either way the fix is to identify the
  position field in `oCEntityCpntEntitySpawnerSettings` and offset it
  in the clone — left to a follow-up.

</details>

## In-game Mod page (Social tab 7th page)

Implemented by `tools/make_social_mods_page_mod.py` (mod `SocialModsPage`).
Adds a 7th selectable page entry to the in-game Social tab without
touching the original News page.

### Approach

The Social tab's child pages are listed in section `Dt Social Book Page`
inside `Social_Book_Page.entity.ot.EntitySettingsResource.gen`. That
section's payload contains a slot array:

```
[u32 count]
[count * page slot]
```

Each page slot is a variable-length blob with this rough layout:

```
BEGIN 0x1d
  lpstr "EntitySettings"
  lpstr "<entity .ot path>"
  BEGIN 0x13 <16B GUID> lpstr "[Game Ui] ..."  END
  BEGIN 0x13 <16B GUID> lpstr "[State] ..."    END
  BEGIN 0x14 0x00
    BEGIN 0x15 ... END
    lpstr "Text"
    lpstr "<bank>.xls"
    u32 <text-key index>
    lpstr "<text key name>"
  END
  BEGIN 0x14 0x01 0x00
    BEGIN 0x13 <16B tester GUID> lpstr "" END
    <4-byte tester hash>
    BEGIN 0x15 ... END
  END
END END END
```

Slot 0 is the News page. The walker locates the 6 slot starts by
scanning for `MARK_BEGIN + 0x1d 00 00 00`, then identifies the count
u32 at `slots[0] - 4`.

### Phase 1 — page bump verified

Byte-for-byte duplicate of slot 0 inserted after slot 5; count bumped
6 → 7. Engine produced two functional "News" entries (slot 0 and slot
6) sharing the same `SocialNewsPage` entity instance. Confirms the
engine resolves picker target-GUIDs per-instance (scoped to the spawn
parent), so two slots pointing at the same entity coexist cleanly.

### Phase 2 — separate Mods entity

1. Cloned cooked file `SocialNewsPage.entity.ot.....gen` byte-for-byte
   under a new encoded filename:
     `Wll_Brrm_Tgyqv!Frbdgl!FrbdglHrtvTgyq.qzidis.ri.MzidisFqiidzyvLqvrwubq.yqz`
   (decodes to `EntitySettings\GameUis\All_Book_Pages\Social\SocialModsPage.entity.ot.EntitySettingsResource.gen`).
   GUIDs were **not** regenerated; per-instance scope handles collisions.
2. Slot 7 in `Social_Book_Page`'s `Dt Social Book Page` patched:
   - entity path lpstr `SocialNewsPage` → `SocialModsPage`
     (same byte length, in-place swap)
   - text-key u32 `0x148` (= 328, `Book_Page_News`) → `0x1e3` (= 483,
     `Book_Page_DLC`)
   - text-key lpstr `Book_Page_News` (14B) → `Book_Page_DLC` (13B);
     length change is **safe in this section** (Dt Social Book Page
     tolerated the 1-byte shrink + 387-byte insertion without audio
     break).
3. `MainMenuMods` adds `Book_Page_DLC=Mods` so the tab label reads
   "Mods" in-game.
4. `UsedRscList.ot` gets a 3-line triplet appended for the new entity:
   ```
   MzidisFqiidzyv
   KgxqJdv\Wll_Brrm_Tgyqv\Frbdgl\FrbdglHrtvTgyq.qzidis.ri
   MzidisFqiidzyv\KgxqJdv\Wll_Brrm_Tgyqv!Frbdgl!FrbdglHrtvTgyq.qzidis.ri.MzidisFqiidzyvLqvrwubq.yqz
   ```

### Phase 3 — header text inside cloned entity

The page-header label is referenced from a `Title_Label` section
(Section 91 in the cloned entity) as:

```
lpstr "Text"
lpstr "Common~GAM.xls"
u32 <text-key index>
lpstr "<text key name>"
```

Patching `Book_Page_News` → `Book_Page_DLC` here (14B → 13B) **broke
audio**: with the 1-byte shrink, FMod/state-machine bindings stopped
firing across the scene. Whether the audio break was due to a cached
class-payload offset or some other length-encoded internal field is
unconfirmed; what is confirmed is that **length-stable lpstr edits
inside cloned entities are audio-safe and length-changing edits are
not**.

Fix: replace with a 14-byte text key. The mod uses `Book_Page_Shop`
(also 14B, index 454/`0x1c6`) as the swap target. `MainMenuMods` then
renames `Book_Page_Shop=Mods` so the header reads "Mods" while
preserving byte length.

### Phase 4 — hide inherited tile artwork

The cloned entity inherits 3 tiles (DLC / Discord / PatchNote) from
SocialNewsPage. Removing the tile sections would shift bytes and risk
the audio break. Instead, the mod blanks them visually by rewriting
every per-tile texture lpstr's directory component from `News` to
`Void` (same 4-character substring, so byte length unchanged):

```
BookMenu\News\Newsbg_Mask.png      -> BookMenu\Void\Newsbg_Mask.png
BookMenu\News\Newsbg_Border.png    -> BookMenu\Void\Newsbg_Border.png
BookMenu\News\Newsbg_DLC4.png      -> BookMenu\Void\Newsbg_DLC4.png
BookMenu\News\Newsbg_DIscord.png   -> BookMenu\Void\Newsbg_DIscord.png
BookMenu\News\Newsbg_Update4.png   -> BookMenu\Void\Newsbg_Update4.png
BookMenu\News\QRCode_Discord.png   -> BookMenu\Void\QRCode_Discord.png
BookMenu\News\QRCode_PatchNote.png -> BookMenu\Void\QRCode_PatchNote.png
```

`BookMenu\Void\` is not a real directory, so the engine's texture
load silently fails for each tile, leaving the tile region blank.

### Hard limits

- **No new text keys.** `make_text_mod.py` only updates existing keys
  in the cooked `Common~GAM.xls` bank. Distinct in-page labels per
  Mods tile require finding existing keys with matching byte lengths
  and renaming them — and only the renamed copies are available, so
  the original meaning is lost.
- **No new click behaviour.** Each tile's click resolves to a
  compiled engine method (e.g. `Modal Methods`, `Discord Link
  Methods`). Adding a new mod-manager action would require either
  hooking into one of those compiled methods or substituting a
  different method picker target — but the available methods are
  fixed by the engine binary.
- **No dynamic mod listing.** The engine has no awareness of the
  `mods/` directory at runtime; everything in the in-game UI is
  serialized from cooked assets at build time.

### Audio-safety rule

When editing a **cloned entity's** cooked payload, every lpstr swap
must preserve byte length. When editing a **parent picker array** in
a different file (e.g. `Dt Social Book Page` inside
`Social_Book_Page....gen`), length changes are tolerated as long as
the section's outer BEGIN/END markers stay balanced.

## Conclusion

The game appears to use a layered compiled asset ontology:

- Engine layer as noise
- Namespace generation system
- Gameplay and content subsystems
- Containerized file formats

This structure can likely be reconstructed via graph clustering.

## Phase 3 — Live engine instrumentation via MinHook (2026-05-15)

### Loader architecture

- `winhttp.dll` proxy (MinGW cross-build). Each WinHTTP export is an assembly thunk (`src/loader/src/winhttp_thunks.S`, generated from `exports/winhttp.def` by `scripts/gen_winhttp_thunks.py`) that jumps into the real WinHTTP: the genuine `System32\winhttp.dll` on Windows, `winhttp_real.dll` (Wine's builtin) under Proton. The `.def` gives every export the ordinal it has in Windows' own `winhttp.dll`: the proxy is the `winhttp.dll` every module in the game process binds to, and while it lacked five of the real DLL's exports a Windows player had no online at all (every Stormancer request "Open failed", no party code).
- Wine loads it because Steam launch options set `WINEDLLOVERRIDES="winhttp=n,b" %command%`
- `DllMain` spawns a worker thread which calls `rsmm::install_engine_hooks()`
- Process filter: `GetModuleFileNameW` → skip if leaf != `Ravenswatch.exe`. Required
  because `crashpad_handler.exe` is spawned with the same winhttp override and
  resolves the link-time VA to a non-executable page (`MH_ERROR_NOT_EXECUTABLE`).

### PE relocation

Ghidra link-time ImageBase: `0x140000000`. Wine ASLR puts the .exe somewhere
else per launch (observed `0x6ffffc6a0000`). Resolve runtime VAs as:

```text
runtime = GetModuleHandleW(nullptr) + (link_va - 0x140000000)
```

A retry loop on `VirtualQuery` (up to 5 s) covers a race where the loader
thread fires before the exe's `.text` mapping is fully committed.

### Hooked functions

| Link VA       | Symbol (Ghidra)                       | Purpose                                |
|---------------|---------------------------------------|----------------------------------------|
| `0x1401145b0` | `FUN_1401145b0` (oCString init/copy)  | Captures any path string the engine constructs at runtime. Filter: substring match on `Social`/`Friend`/`Book_Page`/`News`/`Mods`. |
| `0x140487040` | `FUN_140487040` (resource hashmap)    | The canonical resource-by-path lookup. Returns a handle the engine treats as the loaded entity. |

`FUN_140487040` is an FNV-1a + SwissTable-style probe (lowercased path,
16-byte vectorized bucket scan). One entry per *path*, not per call-site —
the engine caches resources by path hash.

### Captured handles (one run)

```text
Friend_List_Recent.entity.ot       -> 0x671db80
Friend_List_Model.entity.ot        -> 0x671db38
Friend_List_Manage.entity.ot       -> 0x671daf0
Friend_List_Invite.entity.ot       -> 0x671daa8
Friend_List_Request.entity.ot      -> 0x671dbc8
Friend_List_Blacklist.entity.ot    -> 0x671da60
SocialNewsPage.entity.ot           -> 0x671de50   (News tile, slot 0)
Social_Book_Page.entity.ot         -> 0x671df28
End_Credits_Book_Page.entity.ot    -> 0x671d280
```

Handles vary per launch (allocator). The mapping path → handle stays 1:1
within a launch.

### The architectural breakthrough

`tools/make_social_mods_page_mod.py` clones slot 3 (Friend_List_Recent) and
appends it as slot 7 (Mods). Both slots reference the **same path** string
`GameUis\All_Book_Pages\Social\Friend_List_Recent.entity.ot`.

`FUN_140487040` resolves that path **once**, caches by hash, and returns the
**same handle** (`0x671db80`) for every subsequent lookup. Result: slot 7
and slot 4 are literally the same entity. The engine has no way to
distinguish them.

This is why none of the previous attempts to make slot 7 behave
differently (button rebinding, text rename, etc.) survived — the engine
short-circuits to the cached entity before any slot-local context exists.

### Implication

Per-slot divergence requires per-slot **path** divergence. Two options:

1. Point slot 7 at a *real* alternate cooked entity (audio-fragile,
   needs a clone with regenerated GUIDs).
2. Point slot 7 at a *fake* path the engine will look up but won't find,
   then intercept in `hook_resource_lookup` and return a substitute
   handle (existing entity or one we pre-load).

Option 2 is the live-loader path forward.

### Phase 3 — Redirect outcome (empirical)

Implemented option 2: cooked file now references `Mods_List.entity.ot`
(does not exist on disk); `hook_resource_lookup` returns a cached
substitute handle. Trace confirms mechanism:

```text
redirect cache: substitute='SocialNewsPage.entity.ot' handle=0x6721cd0
redirect path='GameUis\All_Book_Pages\Social\Mods_List.entity.ot'
              real=0x0 sub=0x6721cd0 out=0x6721cd0
```

`real_resource_lookup` returns 0 (path miss); we return the substitute
handle the engine had cached for a different real path. Engine accepts
the handle and renders the substitute's entity tree.

**Substitute experiments:**

| Substitute path                       | Visual outcome |
|--------------------------------------|-----------------|
| `SocialNewsPage.entity.ot`            | Renders, but News-page tile textures sized for slot 0 geometry → blown-up sprites in slot 7's friend-list container. |
| `Friend_List_Invite.entity.ot`        | Renders full invite list, functional (invite buttons work). Layout offset to centre of book panel because the entity's internal layout is tuned for a different render context. |
| `Friend_List_Model.entity.ot`         | Renders at correct slot position with placeholder/random-username rows from the model template. No offset. Row contents fetched at runtime via Steam Friends API (not via `FUN_1401145b0`), so cannot be intercepted from oCString hook. |
| `MagicalObjects_Compendium_Page.entity.ot` | Renders inside slot. Item names *are visible* but come from a runtime controller (`MagicalObjectsCompendiumPageUiControllerEntityCpntSettings`), not embedded bytes. Decoder shows only UI element internal names + texture paths + 1 text-bank key. No item-name lpstrs to patch. |
| `System_Book_Page.entity.ot`          | Decoded: 45 classes, controller-driven via `BookOptionsUiControllerEntityCpntSettings`. Static lpstrs: only a handful of text-bank keys (`Common_Back`, `Common_Enter`, `Menu_Settings`, etc.). Rows spawned dynamically. Not suitable. |
| `Modal_Social_Options_Menu.entity.ot` | Renders 6 static button rows (`Book_Page_Blacklist`, `Social_Page_Mute`, `Social_Page_Report`, `Social_Page_Send_Friend_Request`, `Social_Page_Show_Gamercards`, `Social_Page_Unmute`) — exactly the kind of static text-bank-keyed button list we want. **But** the modal is sized for a fullscreen overlay; rendered into a book-page slot the buttons cover the entire book panel. Unfixable without entity-level layout patching. |
| `Friend_List_Model.entity.ot` *(chosen substitute)* | **Confirmed clean.** Renders at correct slot position. Placeholder rows from the model template. No baked-in static labels — row text comes from Steam Friends API (does not pass through `FUN_1401145b0`, so cannot be intercepted from the oCString hook). Aesthetic only; no path to inject mod names from here. |

### Where this leaves us

Two dead ends and one cosmetic fit:

1. **Slot-friendly book pages are all controller-driven.** None of the
   simple book-page entities have a static N-button-list shape with
   per-button text-bank keys. Their layouts come from a controller
   that populates rows at runtime from game data (heroes, items,
   memories, friends, etc.).
2. **Static-button-list modals are fullscreen.** `Modal_Social_Options_Menu`
   has the exact button structure we want, but its layout assumes a
   fullscreen overlay context. Rendered into a slot the buttons cover
   the entire book panel.
3. **Friend_List_Model fits the slot cleanly** but offers no string
   surface we control (row content is Steam-fed).

Therefore: to actually display mod names + toggle state, we have to
either (a) build a custom Mods entity from scratch with the right
layout, or (b) entity-patch an existing fullscreen modal's layout
fields to slot dimensions. Both are significant binary-format work
that has been deferred since Phase 1.

### Live-trace insight worth keeping

Visible UI text comes from a `Common~GAM.xls` lookup keyed by an
lpstr in the entity. We already proved at the build level (Phase 1)
that `Book_Page_DLC=Mods` overrides reliably via
`tools/make_text_mod.py`. So if any future substitute exposes N
static text-bank keys we can rename, the path from key to visible
text is trivial — the gap is finding/building the substitute itself.

**Conclusions:**

1. The redirect mechanism is fully working. Engine treats the substitute
   handle as authoritative; renders its entity tree at slot 7.
2. The substitute is also fully **interactive** — Friend_List_Invite's
   invite buttons function in slot 7 the same as in their original
   context. The engine has no slot-aware UI scoping for our purposes;
   if we wire a substitute entity whose buttons fire useful events,
   those events will fire.
3. Visual fit depends on the substitute's baked layout. Per-slot
   geometry lives inside the substitute entity, not the slot picker.
   To get a clean Mods panel we either pick the cleanest existing
   layout or build a custom cooked entity.

### Audio safety still holds

The cooked-file patch still only touches `Dt Social Book Page` (a
picker array, length deltas tolerated). No cloned-entity payloads
need byte-exact lpstr swaps. Crash-free across all runs.

## Phase 5 Stage B — own the Mods_List cooked file (2026-05-16)

Previously slot 7's picker pointed at the fake decoded path
`GameUis\All_Book_Pages\Social\Mods_List.entity.ot`, which did not
exist on disk; the loader's `hook_resource_lookup` returned a
cached substitute handle (Friend_List_Invite) so the slot rendered
*something*. Stage B ships a real cooked file at that path.

### Approach

`tools/make_mods_list_entity.py` now:

1. Source-clones the bytes of `Friend_List_Recent.entity.ot.
   EntitySettingsResource.gen` (13314 bytes — chosen because the
   friend-list family already renders cleanly at the slot 7
   position; static button section with text-bank keys at
   `Social_Page_Report` / `Social_Page_Block` / `Social_Page_Add`
   etc. is exactly the shape we want long-term).
2. Writes the clone to
   `mods/SocialModsPage/assets/EntitySettings/GameUis/All_Book_Pages/Social/Mods_List.entity.ot.EntitySettingsResource.gen`.
3. Appends an asset-map row mapping the new encoded path
   `MzidisFqiidzyv\KgxqJdv\Wll_Brrm_Tgyqv!Frbdgl!Hrtv_Gdvi.qzidis.ri.MzidisFqiidzyvLqvrwubq.yqz`
   to its decoded counterpart (cipher.py round-trip verified).
4. `apply_mods.py` then drops the cooked file at the encoded path
   with the normal backup pipeline. Since the path didn't exist
   in vanilla there is no backup file — `--restore-all` deletes
   the dropped file (clean rollback).

### Why no GUID regeneration

Phase 1 already proved (page bump verified) that the engine
resolves picker target-GUIDs scoped to the spawn parent. Two
slots pointing at the same internal GUIDs coexist cleanly — the
resource cache keys by *path*, and our path is distinct. Byte-
clone is safe.

### Verified

- `tools/ot_decoder.py` parses the new file cleanly (31 classes,
  16 sections, matches source).
- `apply_mods.py --list` lists both SocialModsPage files; the new
  one resolves to its encoded destination without an
  `[no asset_map match]` warning.
- `apply_mods.py` installs the file at the encoded path; state
  file records it as added (no backup since vanilla had nothing
  there).

### Required follow-up — UsedRscList.ot triplet (2026-05-16)

First in-game test after Stage B showed the loader trace line:

```
redirect path='GameUis\All_Book_Pages\Social\Mods_List.entity.ot' real=0x0 sub=...
```

`real=0x0` means `real_resource_lookup` still returns 0 even though
the cooked file is on disk at the encoded path. Cause: the engine's
resource-hashmap (FUN_140487040) only resolves paths that exist in
the startup manifest `DarkTalesResources/UsedRscList.ot`. The
shipped manifest has no entry for our new path.

Format of a UsedRscList entry (3-line triplet, plain UTF-8 text):

```
MzidisFqiidzyv
KgxqJdv\Wll_Brrm_Tgyqv\Frbdgl\<Name>.qzidis.ri
MzidisFqiidzyv\KgxqJdv\Wll_Brrm_Tgyqv!Frbdgl!<Name>.qzidis.ri.MzidisFqiidzyvLqvrwubq.yqz
```

Top-level dir, short encoded path (`\` separators preserved), full
encoded path (sub-dirs collapsed with `!`). All three lines use
cipher-encoded letters per `tools/cipher.py`.

`tools/make_mods_list_entity.py` now also appends the triplet for
`Mods_List` and writes the patched manifest to
`mods/SocialModsPage/assets/_root/DarkTalesResources/UsedRscList.ot`.
`apply_mods.py` installs it via the `_root/` channel with the
normal backup pipeline (`UsedRscList.ot.rsmm.bak`). On next game
launch the engine indexes our encoded path → `real_resource_lookup`
returns a real handle → loader's redirect block selects `real` over
`sub` → slot 7 renders our owned file (Friend_List_Recent layout in
its own distinct cache slot).

`tools/make_social_mods_page_mod.py` previously cleaned up the
`_root/.../UsedRscList.ot` artifact as Phase 2 legacy. That cleanup
is now scoped to remove only `_root/.../_Cooking` (the Phase 2
cloned-entity artifact); the UsedRscList path is preserved.

### What this unblocks

- The redirect block in `loader/src/hook_engine.cpp` selects
  `real` over `sub` automatically — once the file is installed,
  the live substitute is no longer needed. Substitute remains as
  a fallback for users running the loader without
  `apply_mods.py`.
- All future entity-level edits (layout, text-bank rebind, button
  count) land on a file we *own*. They no longer risk affecting
  the real Friend_List_Recent.

### What this still does NOT give us

Same three defects called out in NEXT_STEPS.md #1, now scoped to
our owned file rather than the substitute:

1. **Layout** is inherited from Friend_List_Recent, which is
   slot-friendly but assumes friend-list internal context.
2. **Row text** still comes from the
   `FriendsListUiControllerEntityCpntSettings` component via the
   Steam Friends API, not from cooked-bytes lpstrs the
   `oCString` hook can rewrite.
3. **Back/click event sinks** still target the parent friend-list
   flow, so clicks fire but their listeners are no-ops in our
   slot's parent tree (Phase 4 click-toggle still works because
   it taps the modal-title `oCString` construction, not the
   click destination).

Concrete next-session work (in order of payoff):

a. **Layout-bounds RE.** Diff `oC2dElementDesc` instances across
   sized cohorts (`tools/class_diff.py oC2dElementDesc`) to find
   the width/height/position floats. With those identified, a
   single patch shrinks the inherited bounds to actual slot
   dimensions.
b. **Strip the FriendsListUiController section.** Now that we
   own the file, find the section index (by class — index
   `FriendsListUiControllerEntityCpntSettings` in the local
   class table) and elide it. Marker-balanced removal of one
   top-level section is the same operation we already do in
   `tools/make_social_mods_page_mod.py` for slot insertion,
   just inverted.
c. **Replace static button labels.** The cooked file has lpstr
   `Common~GAM.xls` followed by length-prefixed text-bank keys
   (`Social_Page_Report` etc.). Audio-safety rule says the
   lpstr swap must preserve byte length, but `make_text_mod.py`
   can rebind the *values* of any existing key — so renaming
   `Social_Page_Report=Toggle Mod 1` is enough to produce visible
   "Toggle Mod 1" without touching the cooked entity.
d. **Per-row click identity.** Once buttons render mod names, the
   existing click-signal hook (`Invite friend to party` modal
   title) becomes per-row identifiable: capture the last Steam
   ID seen on the `oCString` hook just before the modal title
   fires (the loader already tracks `g_last_steam_id`), map to
   the row index that was selected, derive the mod from a fixed
   row-to-mod-id table.

## Phase 4 — Click-toggle pipeline (working end-to-end)

Goal achieved: clicking a row in the in-game Mods tab toggles a
mod's `enabled` flag on disk. Pipeline:

1. **Loader DLL detects click.** The substitute entity is
   `Friend_List_Invite.entity.ot`. Each row click spawns an
   invite-confirmation modal whose title localizes to the string
   `"Invite friend to party"`. We hook `FUN_1401145b0`
   (oCString init/copy) and watch for that exact 22-byte string.
   When it fires AND `g_substitute_handle != 0` (Mods tab visited
   this session), we record an event to
   `mods/_clicks.log` with a timestamp and a monotonic counter.

   Hook target: `0x1401145b0` (already installed for path
   capture). Identifying the click string was a single broad-burst
   trace; the localizer call site is `link va = 0x14055d95c`
   inside `FUN_14055d850`. No new MinHook target required.

2. **Python tool drains the click log.** `tools/process_clicks.py`
   reads `_clicks.log`, compares the event count against a stored
   counter (`mods/_clicks.state`), and applies one toggle per
   unprocessed click. Toggles cycle through `mods/*/manifest.toml`
   in alphabetical order (ExampleMod, LongerStatusEffects,
   MainMenuMods, SocialModsPage). State is durable, so re-running
   the tool without new clicks is a no-op.

3. **Apply mods normally.** `tools/apply_mods.py` reads the
   updated manifests and applies/restores cooked files according
   to the new enabled state.

### Workflow

```text
WINEDLLOVERRIDES="winhttp=n,b" RSMM_ENGINE_TRACE=1 %command%
  # in-game: Social → Mods sub-tab → click rows
  # exit game

python3 tools/process_clicks.py
  # cycles N toggles for N unprocessed clicks

python3 tools/apply_mods.py
  # applies new enabled state to cooked dir
```

### Limitations

- **No per-row identity.** The current signal only tells us "a
  click happened in the Mods slot." We cycle through mods in
  order; clicking does not select a specific mod. Mapping click
  to mod requires capturing the row's Steam ID (visible in the
  trace at `ra=0xf9692e/0xf969f6/...`) or the in-engine
  selection index.
- **Inviting still fires.** Friend_List_Invite's native click
  action is still Steam invite. The mod toggle is a side effect
  of detecting the localized modal title. The modal also pops up
  in-game.
- **No live UI feedback.** Toggle takes effect only after
  `process_clicks.py` + `apply_mods.py` + relaunch. The Mods tab
  still shows friends, not mod names.

### What this proves

The redirect mechanism is sufficient to turn an in-game UI click
into a persistent disk write under our control. The remaining
work is cosmetic + semantic: getting the Mods tab to show mod
names instead of friends, and getting per-row identity so each
mod has a dedicated button. Both are deferred to a custom-entity
build pass.

## Phase 4b — Per-row click identity via Steam ID (2026-05-16)

Each row in the Friend_List_Invite substitute carries the Steam
friend's 64-bit ID, which the engine stringifies as a 17-digit
decimal through `FUN_1401145b0` just before constructing the
invite modal's title. Capturing that string between the row click
and the click-signal fire gives a stable per-row handle.

### Loader changes

`loader/src/hook_engine.cpp`:

- `g_last_steam_id` (previously declared but unused) is now
  populated inside `hook_string_init` whenever a 17-digit
  all-numeric oCString passes through, gated on the redirect
  being armed (`g_substitute_handle != 0`) to keep
  pre-Mods-tab noise out.
- `clicks_record` appends `steam_id=<17-digit>` to the event
  line when the captured ID is non-empty.

### Python changes

`tools/process_clicks.py` now parses the new `steam_id=` field.
A persistent map at `mods/_clicks_id_map.json` binds each Steam
ID to a specific mod (first sighting auto-assigns the next mod
in alphabetical order, subsequent sightings are stable).
Clicks without a `steam_id=` (e.g. from a loader build that
predates this change) fall back to the legacy alphabetical
cycle, so old click logs still process cleanly.

The mapping file is hand-editable — users who want a specific
row → mod binding can pre-seed it.

### Workflow

```text
# 1. Build + deploy rebuilt loader (dist/winhttp.dll)
loader/build.sh
tools/install_loader.sh

# 2. Reset stale click counter (optional)
tools/process_clicks.py --reset

# 3. Launch game with engine trace
WINEDLLOVERRIDES="winhttp=n,b" RSMM_ENGINE_TRACE=1 %command%
#   Social -> Mods -> click rows -> exit

# 4. Process clicks
tools/process_clicks.py
#   First click on Steam ID A: binds A -> ExampleMod, toggles ExampleMod
#   First click on Steam ID B: binds B -> LongerStatusEffects, toggles it
#   Second click on A: re-toggles ExampleMod (binding stable)

# 5. Apply toggles to cooked state
tools/apply_mods.py
```

### Limits

- Steam friends list ordering is not stable across launches (Steam
  re-orders by online status). The Steam ID is stable; the
  visible row position is not. Users editing `_clicks_id_map.json`
  by hand will need to know which Steam ID corresponds to which
  visible row.
- An empty friends list shows no rows to click, so the binding
  table can't bootstrap on accounts without Steam friends.
  Acceptable trade-off because (a) most Ravenswatch players have
  Steam friends and (b) the underlying friend-list substitute is
  Stage B's transitional layout — the long-term plan is a
  custom Mods row source so this constraint goes away.

---

# 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.

---

# Contributing

> How to contribute to RSMM.

Source: https://docs.rsmm.me/contributing/contributing/

Contributing to Ravenswatch Mod Manager
=====================================

Thank you for contributing! This guide explains how to report issues and submit pull requests.

Report issues
- Search existing issues first.
- Provide reproduction steps, OS, game version, and relevant logs.

Code style
- Follow existing formatting in `src/` and `rsmm/`.
- Use `clang-format` for C++ and `black` for Python where applicable.

Pull requests
- Fork the repo and create a focused topic branch.
- Include a clear description, related issue, and testing steps.

Tests and CI
- Add tests for new logic where practical.
- Ensure CI passes before requesting review.

Communication
- Be responsive to review comments and keep PRs small.

Support the project
- RSMM is free and MIT-licensed; there is no paid tier and nothing is held back for donors.
- If you would rather chip in than file a PR: [ko-fi.com/ovilli](https://ko-fi.com/W7W41FW3YE).

---

# Deployment

> Provision every external service to host RSMM, step by step.

Source: https://docs.rsmm.me/contributing/deploy/

This guide covers every external service you sign up for to take the
project from "running locally on my laptop" to "publicly hosted with
real users". Everything is free-tier where possible.

Order matters — later steps need values from earlier ones. Do them
top-to-bottom.

## What you'll provision

| Service | Why | Free? |
|---------|-----|-------|
| GitHub | Source repo, CI, Releases | yes |
| Neon | Serverless Postgres for prod registry + telemetry | yes (0.5 GB) |
| Cloudflare R2 | Object storage for uploaded mod `.zip` files | yes (10 GB/mo egress free) |
| Vercel | Hosting for `apps/www` (Next.js), `apps/api` (Hono/Node), **and** `apps/docs` (Astro/Starlight) — three projects, same repo | yes |
| Domain (rsmm.me or similar) | Friendly URL + email | ~$10/yr |

If money is the issue, everything runs on Vercel's Hobby tier. Skip the
domain for v1 and use the `*.vercel.app` URLs.

---

## Step 1: GitHub repo + Actions secrets

1. Push the monorepo to GitHub if you haven't already:
   ```sh
   git remote -v
   # if no origin: gh repo create Ovilli/RavenswatchModManager --source=. --public --push
   git push -u origin main
   ```
2. Open **github.com/Ovilli/RavenswatchModManager → Settings → Secrets and variables → Actions**.
3. You'll come back to add secrets here in later steps. Leave this tab open.

The release workflow (`.github/workflows/release.yml`) already runs on
`git push --tags v*` — no secrets needed for basic Tauri builds; the
default `GITHUB_TOKEN` is enough for creating the draft release.

6. (Optional) **Discord release notifications**:
   - Create a webhook in your Discord server (Server Settings → Integrations → Webhooks).
   - Copy the webhook URL and add it as a repository secret:
     **Settings → Secrets and variables → Actions → New repository secret**
     - Name: `DISCORD_WEBHOOK_URL`
     - Value: `https://discord.com/api/webhooks/...`
   - Tag-driven releases notify Discord from the `finalize-release` job in
     `release.yml` (GitHub does not fire `release: published` for publishes
     done via `GITHUB_TOKEN`). Manual/UI publishes still trigger
     `discord-notify.yml`.

---

## Step 2: Neon (serverless Postgres)

1. Sign up at **<https://neon.tech>** (GitHub login is fastest).
2. Click **"New Project"**:
   - Name: `rsmm-prod`
   - Postgres version: 16
   - Region: pick whatever's closest to where your API will run (see Step 5)
3. After creation, Neon shows a **Connection string**. It looks like:
   ```
   postgresql://rsmm_owner:abc123@ep-cool-snow-12345.us-east-2.aws.neon.tech/rsmm?sslmode=require
   ```
   Copy it. This is `DATABASE_URL`.
4. In your Neon project, go to **Branches → main → Database**. The default
   `neondb` may be the DB name; create one called `rsmm` via **Tables → New database** if you prefer a cleaner name. Update the connection string accordingly.
5. Apply the schema once from your laptop, against the Neon URL:
   ```sh
   DATABASE_URL='paste-neon-url' DB_DRIVER=neon pnpm db:push
   ```

You now have a production DB. Save the connection string somewhere
secure (1Password, Bitwarden) — you'll paste it into the Vercel env
vars in later steps.

---

## Step 3: Cloudflare R2 (object storage for uploads)

R2 is S3-compatible. The API code already supports it via the same
`S3_*` env vars.

1. Sign up at **<https://dash.cloudflare.com>**.
2. Left sidebar → **R2 Object Storage**. Click **Purchase R2** — the free tier costs nothing but Cloudflare wants a card on file. Free tier: 10 GB storage + 10M Class A ops + unlimited egress.
3. Click **Create bucket**:
   - Name: `rsmm-mods`
   - Location: Automatic
4. After creation, open the bucket → **Settings**. Note the bucket name + the **Account ID** (top of the page or right sidebar).
5. Left sidebar → **R2 → Manage R2 API Tokens → Create API token**:
   - Token name: `rsmm-api-write`
   - Permissions: **Object Read & Write**
   - Specify bucket: `rsmm-mods`
   - TTL: leave blank (or set to 1 year)
   - Click **Create API Token**
6. R2 shows the credentials **once** — copy these now:
   - Access Key ID
   - Secret Access Key
   - **Endpoint** for S3-compatible clients: `https://<account-id>.r2.cloudflarestorage.com`
7. (Optional) Enable a **public r2.dev URL** for the bucket so clients can download mods without signed URLs:
   - Bucket → **Settings → Public access → Allow Access** → opt into `r2.dev`
   - Note the public URL: `https://pub-<hash>.r2.dev`
   - This is `S3_PUBLIC_BASE_URL`. Skip if you want all downloads gated by signed URLs.

You'll paste these into the API env in Step 5:

```
S3_BUCKET=rsmm-mods
S3_REGION=auto
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=<from step 6>
S3_SECRET_ACCESS_KEY=<from step 6>
S3_PUBLIC_BASE_URL=https://pub-<hash>.r2.dev   # only if Step 7 done
```

---

## Step 4: Generate the Better Auth secret

You already have one in your local `.env`. For prod, generate a fresh one:

```sh
openssl rand -hex 32
```

Copy the 64-char hex string. This is `BETTER_AUTH_SECRET` for the API
host (Step 5). Never commit it.

---

## Step 5: Vercel (host for apps/api)

The API is a Node Hono server, deployed as its own Vercel project.
`apps/api/vercel.json` already pins the install and build commands
(`pnpm --filter api vercel-build`), so the dashboard setup is minimal.

1. Sign up at **<https://vercel.com>**, GitHub login.
2. Go to **<https://vercel.com/new>** and **Import** the
   `RavenswatchModManager` repo as a **new project** (separate from the
   `apps/www` and `apps/docs` projects).
3. In **Configure Project**:
   - **Root Directory**: `apps/api` (click *Edit* → select the folder).
     Vercel still installs the whole pnpm workspace from the repo root.
   - Build Command / Install Command: leave as-is — `vercel.json`
     provides them.
4. **Environment Variables** (Production + Preview):
   ```
   DATABASE_URL=postgresql://...neon.tech/rsmm?sslmode=require
   DB_DRIVER=neon
   BETTER_AUTH_SECRET=<from step 4>
   BETTER_AUTH_URL=https://<your-api-project>.vercel.app
   TRUSTED_ORIGINS=https://www.rsmm.me,https://rsmm.vercel.app,tauri://localhost
   S3_BUCKET=rsmm-mods
   S3_REGION=auto
   S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
   S3_ACCESS_KEY_ID=<from step 3>
   S3_SECRET_ACCESS_KEY=<from step 3>
   S3_PUBLIC_BASE_URL=https://pub-<hash>.r2.dev
   UPSTASH_REDIS_REST_URL=https://<db>.upstash.io
   UPSTASH_REDIS_REST_TOKEN=<from the Upstash console>
   ```

   The Upstash pair is easiest to get by provisioning the Marketplace
   integration rather than by hand:

   ```sh
   vercel integration add upstash/upstash-kv --no-claim
   ```

   It provisions a free-tier Redis and injects the credentials into the
   project. Note it injects them as `KV_REST_API_URL` / `KV_REST_API_TOKEN`,
   not under the `UPSTASH_REDIS_REST_*` names Upstash's own docs use — the
   limiter reads both spellings for exactly that reason. Afterwards, delete any
   `apps/api/.env.local` the CLI wrote: Vite bakes those values into the test
   transform, and the suite then talks to production.

   :::caution[Set the Upstash pair before going public]
   Without it, rate limiting falls back to an in-memory window that is
   **per process**. On Vercel that means every concurrently warm instance
   keeps its own counter, so the real limit is `maxHits x instances` — not an
   approximation of the configured limit but an independent copy of it.

   That is survivable for read endpoints. It is not for `/api/logs`, which
   stores up to 150 KB of user-supplied text per accepted call and relies on
   its hourly cap to stay a support tool rather than free file hosting. The
   API logs a warning at boot in production when the pair is missing.
   :::
5. Click **Deploy**.
6. Verify:
   ```sh
   curl https://<your-api-project>.vercel.app/health
   # → {"ok":true,"ts":...}
   ```

The API is now live. Save that URL — the www project and the desktop app
need it. Remember: Vercel does **not** apply env-var changes to a running
deployment — redeploy after every env edit.

---

## Step 5b: Social sign-in (optional — Google / GitHub)

The "Continue with Google" / "Continue with GitHub" buttons are **already
built** into the sign-in and sign-up pages. They stay hidden until the
matching OAuth credentials exist in the API env — `/api/auth-config`
reports which providers are configured and the UI renders only those. No
code change is needed to enable them.

> The callback URL **must** be `<BETTER_AUTH_URL>/api/auth/callback/<provider>`
> where `BETTER_AUTH_URL` is whatever the deployed API actually serves under.
> If the API runs on Vercel (the current setup) at `https://api.rsmm.me`, the
> callback is `https://api.rsmm.me/api/auth/callback/google`. A mismatch here
> is the #1 cause of `Error 400: redirect_uri_mismatch`. Changing
> `BETTER_AUTH_URL` later means updating BOTH the env var *and* the console.

To turn on **Google**:

1. **Google Cloud Console** → *APIs & Services* → *Credentials* →
   *Create Credentials* → *OAuth client ID*. Application type:
   **Web application**.
2. Under **Authorized redirect URIs**, add (must match `BETTER_AUTH_URL`
   exactly — no trailing slash):
   ```
   https://api.rsmm.me/api/auth/callback/google
   ```
   Add a second entry `http://localhost:3001/api/auth/callback/google` if you
   want Google sign-in to work in local dev too — and run the API locally with
   `BETTER_AUTH_URL=http://localhost:3001` so the generated callback matches
   (you can't test locally while `BETTER_AUTH_URL` points at prod).
3. Set the generated client ID + secret on the API host. On **Vercel**:
   Project → Settings → Environment Variables → add `GOOGLE_CLIENT_ID` and
   `GOOGLE_CLIENT_SECRET` (Production + Preview), then **redeploy** — Vercel
   does not apply env changes to the running deployment until you redeploy.
4. After the redeploy, reload `/auth/signin` — the Google button appears once
   `/api/auth-config` reports `google: true`.

**GitHub** is identical: register an OAuth App at
*GitHub → Settings → Developer settings → OAuth Apps*, set the callback to
`https://api.rsmm.me/api/auth/callback/github`, then set
`GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` the same way and redeploy.

Both providers are off by default and safe to skip — email/password
sign-in works without them.

---

## Step 6: Vercel (host for apps/www)

1. Sign up at **<https://vercel.com>**, GitHub login.
2. Click **Add New → Project**. Pick the `RavenswatchModManager` repo.
3. Vercel detects Next.js. Override these settings:
   - **Root Directory**: `apps/www`
   - **Build Command**: `cd ../.. && pnpm install --frozen-lockfile && pnpm --filter www build`
   - **Install Command**: `pnpm install --filter www...`
   - **Framework Preset**: Next.js
4. **Environment Variables**:
   - `NEXT_PUBLIC_API_URL` = `https://<your-api-project>.vercel.app` (from Step 5)
5. Click **Deploy**. First build takes ~2 min.
6. Vercel gives you a URL like `rsmm.vercel.app`. Open it. The landing
   page should load; `/auth/signin` should work because it talks to your
   API project.

If sign-in fails with CORS errors: go back to Step 5 and make sure your
Vercel www URL is in the API project's `TRUSTED_ORIGINS`, then redeploy
the API to pick up the env change.

---

## Step 7: Vercel (host for apps/docs)

The docs are a static Astro/Starlight site. `apps/docs/vercel.json` already
pins the framework, install, build, and output — so the only thing you set in
the dashboard is the **Root Directory**.

1. Go to **<https://vercel.com/new>** and **Import** the `RavenswatchModManager` repo as a **new project** (separate from the `apps/www` project).
2. In **Configure Project**:
   - **Root Directory**: `apps/docs` (click *Edit* → select the folder). Vercel still installs the whole pnpm workspace from the repo root.
   - **Framework Preset**: Astro (auto-detected; `vercel.json` also sets it).
   - Build Command / Output Directory / Install Command: leave as-is — `vercel.json` provides them (`pnpm --filter docs build` → `dist`).
3. Click **Deploy**.

You'll get a URL like `rsmm-docs.vercel.app`.

> The build runs `starlight-links-validator`; a broken internal link **fails the
> deploy**, same as CI. Fix links locally with `pnpm --filter docs build` before
> pushing.

---

## Step 8: Custom domain (optional but recommended)

Buy `rsmm.me` (or whatever) from **Cloudflare Registrar** (cheapest,
no upsells) or Namecheap.

After registering at Cloudflare:

| Subdomain | Points to | How |
|-----------|-----------|-----|
| `rsmm.me` (apex) | Vercel (www) | Vercel project → Settings → Domains → add `rsmm.me` → Cloudflare DNS: `A @ 76.76.21.21` |
| `www.rsmm.me` | Vercel (www) | Vercel adds this automatically with the apex |
| `api.rsmm.me` | Vercel (api) | Vercel api project → Settings → Domains → add `api.rsmm.me` → add the CNAME it shows in your DNS |
| `docs.rsmm.me` | Vercel (docs) | Vercel docs project → Settings → Domains → add `docs.rsmm.me` → add the CNAME it shows in your DNS |
| `cdn.rsmm.me` | R2 public bucket | R2 bucket → Settings → Custom Domains → `cdn.rsmm.me` |

After domain is live, update (api project env, then redeploy the api):
- `BETTER_AUTH_URL` → `https://api.rsmm.me`
- `TRUSTED_ORIGINS` → `https://rsmm.me,https://www.rsmm.me,tauri://localhost`
- `S3_PUBLIC_BASE_URL` → `https://cdn.rsmm.me`
- www project env `NEXT_PUBLIC_API_URL` → `https://api.rsmm.me` + redeploy www

---

## Step 9: Desktop app distribution

Tag a release to trigger the `tauri-action` workflow:

```sh
git tag v0.1.0
git push origin v0.1.0
```

GitHub Actions builds installers for Windows / Linux and posts them as
a **draft** GitHub Release. Visit the release page, edit the notes,
click **Publish**.

Users download from `github.com/Ovilli/RavenswatchModManager/releases`.

For code signing (Windows SmartScreen), you'll need a paid cert
(~$200/yr). Skip it until the project has users.

---

## Step 10: Production env summary

When everything is live, this is what each host runs:

**Vercel (api — api.rsmm.me)**
```
DATABASE_URL=postgresql://...neon.tech/rsmm?sslmode=require
DB_DRIVER=neon
BETTER_AUTH_SECRET=<random 64 hex>
BETTER_AUTH_URL=https://api.rsmm.me
TRUSTED_ORIGINS=https://rsmm.me,https://www.rsmm.me,tauri://localhost
S3_BUCKET=rsmm-mods
S3_REGION=auto
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_PUBLIC_BASE_URL=https://cdn.rsmm.me
```

**Vercel (rsmm.me)**
```
NEXT_PUBLIC_API_URL=https://api.rsmm.me
```

**Vercel (docs — docs.rsmm.me)**

No environment variables required — the docs site is fully static. Vercel
auto-selects a recent Node version; pin it under Settings → General → Node.js
Version if you want to match CI (22).

**Desktop installer (built by tauri-action)** — talks to whatever
`VITE_API_URL` is baked in at build time. For a release pointing at
prod, add to `.github/workflows/release.yml`:

```yaml
- name: Build desktop
  uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    VITE_API_URL: https://api.rsmm.me
```

---

## Smoke test checklist

After every step:

- [ ] Step 2: `psql 'postgresql://...neon.tech/...?sslmode=require' -c '\dt'` lists tables
- [ ] Step 3: `curl -X PUT 'https://<endpoint>/rsmm-mods/test.txt' -H 'x-amz-content-sha256: UNSIGNED-PAYLOAD' -H 'authorization: ...'` returns 200 (or use a tool like rclone)
- [ ] Step 5: `curl https://<your-api-project>.vercel.app/health` → `{"ok":true}`
- [ ] Step 5: `curl https://<your-api-project>.vercel.app/mods` → `{"items":[],"total":0}`
- [ ] Step 6: `curl https://rsmm.vercel.app/` returns HTML
- [ ] Step 6: open `https://rsmm.vercel.app/auth/signup`, create account, check Neon `user` table has row
- [ ] Step 7: open `docs.rsmm.me` → Starlight site loads

If any step fails, the rest will fail too. Don't skip ahead.

---

## Cost reality check

| Item | Free tier holds up to | Paid trigger |
|------|----------------------|--------------|
| Neon | ~100 active users, 0.5 GB | $19/mo Pro |
| R2 | 10 GB, 10M Class A ops/mo | $0.015/GB after |
| Vercel (www + api) | 100 GB egress, no commercial use on free | $20/mo Pro |
| Vercel (docs) | static, shares the Vercel Hobby free tier | $20/mo Pro |
| GitHub Actions | 2000 min/mo private (unlimited public) | $0 for public repos |
| Domain | n/a | $10/yr |

Total for a small launch: **~$0–15/mo + $10/yr domain**.

---

# Development setup

> Set up a local development environment for working on RSMM itself.

Source: https://docs.rsmm.me/contributing/setup/

This guide covers setting up a development environment for hacking on RSMM itself. If you just want to *use* the mod manager, see [Installation](/getting-started/install/).

> **Note about paths:** throughout this document, `./rsmm <name>` refers to the repo-root entry point. The equivalent Python module lives at `src/rsmm/cli/<name>.py` or `src/rsmm/engine/<name>.py`.

---

## Prerequisites

| Tool | Version | Notes |
|---|---|---|
| Node | >= 20.11 | `nvm install 22` recommended |
| pnpm | 9.x | `corepack enable && corepack prepare pnpm@9.12.0 --activate` |
| Docker | any modern | For local Postgres via `docker compose` |
| Rust | stable | Only for desktop (Tauri) builds. Install via `rustup` |
| Python | >= 3.11 | The desktop app shells out to the Python CLI |
| CMake | >= 3.20 | For building the native loader DLL |
| Git | any | |

Platform extras for Tauri 2 desktop builds: see [tauri.app/start/prerequisites](https://tauri.app/start/prerequisites/).

---

## First-time bootstrap

```sh
# 1. Clone
git clone https://github.com/Ovilli/RavenswatchModManager.git
cd RavenswatchModManager

# 2. Python virtual env (for the rsmm CLI)
python3 -m venv .venv
source .venv/bin/activate       # Linux
# .venv\Scripts\activate        # Windows
pip install -e .

# 3. Workspace deps (TypeScript monorepo)
corepack enable
pnpm install

# 4. Local Postgres
cp .env.example .env
sed -i "s/replace-me-32-bytes-hex/$(openssl rand -hex 32)/" .env
pnpm db:up        # docker compose up -d postgres
pnpm db:push      # Create tables via Drizzle
pnpm db:seed      # Optional sample data
```

## Daily commands

| Command | Description |
|---|---|
| `pnpm dev` | Desktop app (Tauri + Vite) |
| `pnpm dev:with-cli` | Desktop app (uses system `rsmm` Python CLI from repo root) |
| `pnpm api:dev` | Hono API on `:3001` |
| `pnpm www:dev` | Next.js website + registry on `:3000` |
| `pnpm docs:dev` | Astro Starlight docs on `:4321` |
| `pnpm lint` / `pnpm lint:fix` | Biome lint |
| `pnpm format` | Biome format |
| `pnpm check-types` | TypeScript across all packages |
| `pnpm db:push` | Push schema to local DB |
| `pnpm db:migrate` | Apply migrations |
| `pnpm build` | Build every package + app |

### Platform-specific desktop dev

| Command | Platform | Use case |
|---|---|---|
| `pnpm --filter desktop dev` | All | Standard development |
| `pnpm --filter desktop dev:linux` | Linux | If WebKit DMA-BUF errors occur |
| `pnpm --filter desktop dev:linux-soft` | Linux | Software GL fallback (last resort) |

### Production builds

| Command | Output |
|---|---|
| `pnpm --filter desktop build` | Native platform installer (MSI/AppImage) |
| `pnpm --filter desktop build:linux` | Linux x86_64 build |
| `pnpm --filter desktop build:windows` | Windows x64 build |

### Sidecar (Python CLI binary)

For production builds, the Python CLI must be bundled as a standalone executable:

```sh
python3 scripts/build-sidecar.py              # Build for current platform
python3 scripts/build-sidecar.py --target linux
python3 scripts/build-sidecar.py --target windows
python3 scripts/build-sidecar.py --all         # Build for all platforms
```

Requires PyInstaller (`pip install pyinstaller`). The output binary is placed at
`apps/desktop/src-tauri/binaries/rsmm-<target-triple>` where Tauri's sidecar resolver expects it.

For development, you can use the system Python CLI instead (`rsmm` on PATH from `pip install -e .`).
The desktop app falls back to the system command if the sidecar binary is not found.

## Building the native loader

```sh
# Linux (cross-compile for Windows via MinGW)
cd src/loader
./build.sh

# Windows (auto-detects Visual Studio or MinGW)
cd src\loader
fetch_deps.bat
build.bat
```

The compiled `winhttp.dll` appears in `dist/`.

## Testing

```sh
# Python tests
pytest -q                                    # From repo root

# Regenerate dev artifacts (optional, not committed)
pip install --user texture2ddecoder Pillow capstone
python3 scripts/extract_uncooked.py           # Uncooked asset mirror
python3 scripts/decode_gen_sidecars.py        # .gen sidecars
bash docs/_re/run_dump_symbols.sh             # Ghidra symbol dump
python3 scripts/gen_function_patterns.py      # Pattern DB
python3 scripts/test_pattern_resolve.py --all # Validate patterns
```

## IDE setup

Open the workspace in VS Code. Install the CMake Tools and Python extensions. Point the Python interpreter to `.venv`.

## Architecture

```
apps/desktop    Tauri 2 shell. Vite + React. Spawns `rsmm` CLI as sidecar.
apps/www        Next.js 15 marketing site + registry browser.
apps/api        Hono on Node. Better Auth + /mods + /telemetry endpoints.
apps/docs       Astro Starlight documentation site.
packages/db     Drizzle schema + migrations (Neon / pg dual driver).
packages/ui     Shared React components + Tailwind preset.
packages/api-client  Typed fetch client for apps/api.
packages/schemas     Zod schemas shared by client + server.
src/rsmm/       Python CLI + SDK. Untouched by the TypeScript monorepo.
src/loader/     Native DLL source (winhttp proxy + Lua VM).
```

## Python bridge

The desktop app calls the Python CLI via the Tauri shell plugin:

```ts
import { rsmm } from './lib/rsmm';
const mods = await rsmm<LocalMod[]>(['list', '--json']);
```

The `rsmm` executable must be on `PATH`. For devs, the repo-root `./rsmm` wrapper works.

## Local vs production database

Local: Docker Postgres via `docker compose up -d postgres`. Connection string in `.env`.

Production: [Neon](https://neon.tech) serverless Postgres. Set `DATABASE_URL` and `DB_DRIVER=neon` in your deployment environment. Run `pnpm db:migrate` once after deploy.

Drizzle is configured for both drivers — the switch is the `DB_DRIVER` env var.

## Tauri icons

The committed `apps/desktop/src-tauri/icons/icon.png` is a placeholder. Replace with a real 1024×1024 PNG, then:

```sh
cd apps/desktop
pnpm tauri icon icons/icon.png
```

This regenerates every required size + `.ico` + `.icns` + mobile variants.

## Linux + NVIDIA

If `pnpm desktop:dev` prints GBM/DRM errors and the window never appears:

```sh
pnpm --filter desktop dev:linux          # Disable DMA-BUF + compositing
pnpm --filter desktop dev:linux-soft     # Last resort: software GL
```

---

## Contributing

### Reporting issues

- Search existing issues first.
- Provide reproduction steps, OS, game version, and relevant logs.

### Code style

- Follow existing formatting in `src/` and `apps/`.
- Use `clang-format` for C++ and `black` for Python where applicable.

### Pull requests

- Fork the repo and create a focused topic branch.
- Include a clear description, related issue, and testing steps.
- Ensure CI passes before requesting review.

### Communication

- Be responsive to review comments and keep PRs small.

---

# 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).

---

# Roadmap

> What's shipped, what's in progress, and what's blocked — at a glance.

Source: https://docs.rsmm.me/project/roadmap/

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

This is the project's working roadmap. It tracks the big reverse-engineering and
tooling milestones — not every commit.

**Status key:** <Badge text="Shipped" variant="success" /> done and verified ·
<Badge text="In progress" variant="caution" /> partially working ·
<Badge text="Blocked" variant="danger" /> waiting on a hard dependency ·
<Badge text="Planned" variant="note" /> designed, not started.

<Aside type="note">
Historical entries mention `tools/<script>.py`; those scripts now live under
`src/rsmm/cli/` or `src/rsmm/engine/` and are reached as `./rsmm <name>`.
</Aside>

## Shipped <Badge text="Shipped" variant="success" />

| Milestone | What landed |
|---|---|
| **Uncooked asset mirror** | `data/uncooked/` extract pipeline — textures decoded (BC1/BC3/BC5/RGBA8 → PNG, 4,776 PNGs) plus 15,431 raw `.gen` + 15,362 structural sidecars. See [Uncooked assets](/guides/uncooked-assets/). |
| **Pack guard** | `rsmm pack` refuses files byte-identical to the original (`--allow-vanilla` for personal backups), preventing accidental redistribution of copyrighted assets. |
| **Mass decompile** | 46,963 functions decompiled; symbols + strings exported to JSON. See [RE pipeline](/reverse-engineering/pipeline/). |
| **Pattern resolver + `rsmm.call`** | ~50k byte-pattern signatures in `data/function_patterns.json`, every one resolving to its recorded address by the loader's own scan (see [the pipeline](/reverse-engineering/pipeline/); the DB published before 2026-10-03 needs a republish to get there). Lua mods can call any of ~53k game functions by name, plus memory read/write. See [Calling game functions](/reverse-engineering/calling-game-functions/). |
| **Seed surface mapped** | The built-in *Forced seed* option (`oe::UIntGameOption`, id `0x1949b098`) located with its enable bool. `ExampleSeedPin` pins a run's RNG for speedruns. See [Seed + mapgen](/reverse-engineering/seed-mapgen/). |

## In-game "Mods" UI <Badge text="Abandoned" variant="danger" />

Giving the mod manager a presence inside Ravenswatch's own menus (a Social-book
tab, a title-menu button, a book-page mod list) was dropped. Mods are managed
from the desktop app and the CLI. The tooling (`rsmm menu`, `rsmm intents`,
`rsmm url`, `rsmm social-tab`, `rsmm menu-button`, `rsmm mods-list`) has been
removed; what was learned about the game's UI is kept in
[UI & the book menu](/reverse-engineering/ui-menus/).

## Hook API (`rsmm.hook`) <Badge text="Shipped" variant="success" />

The loader intercepts game functions: `rsmm.hook` for mods, and the loader's own
detours (damage meter, lobby parser, event bus, skins, talents) go through
`hook_util.h`, which checks every target is a real function entry before it
installs. The earlier belief that an anti-tamper integrity check crashed every
hookpoint was wrong: the two hooks that failed had unrelated causes. See
[Anti-tamper protector](/reverse-engineering/protector/).

Hooks are observation-first and gated by symbol status in `data/symbols.json`; a
hook on an address that is not a function entry is refused or warned, not
installed silently.

## Pattern-DB rebuild on game update <Badge text="Shipped" variant="success" />

When Steam updates Ravenswatch, the signatures in `function_patterns.json` must
be regenerated against the new exe.

- `./rsmm doctor` hashes the installed exe and warns when the pattern DB is stale.
- `./rsmm rebuild-fn-patterns` regenerates the DB in about 2–3 minutes, adds the
  stable named entries, and checks that every mapped symbol lands on a function
  boundary and every entry resolves to its address. The old DB is put back if a
  step fails. `--ghidra` re-runs the symbol dump first.
- `rsmm symbols` remaps `data/symbols.json` after a patch. That step, rebuilding the
  loader and publishing are still run by hand (see the
  [pipeline](/reverse-engineering/pipeline/)).

---

# Strategy

> The 8-area architectural plan behind RSMM.

Source: https://docs.rsmm.me/project/strategy/

Strategic blueprint for evolving the Ravenswatch Mod Manager from
"functional foundation" to "community-grade modding framework".
Strategy only — implementation details live in code, see `MODDING.md`
+ `SDK.md` (TBD) for usage and `INTERNALS.md` for engine RE.

## Current state (honest)

- **Build-time**: Python CLI rewrites cooked asset bytes under
  `_Cooking/` with per-file backup + restore.
- **Runtime**: Optional `winhttp.dll` proxy hosts per-mod Lua VMs.
  MinHook intercepts on engine functions were prototyped, currently
  pruned to no-op stubs.
- **Multiplayer**: Not addressed. Engine uses Steam P2P. Cooked
  overrides on one peer = silent desync.

What works today informs every section below; gaps are called out
explicitly so the plan stays grounded.

---

## 1. API Scalability & Ergonomics

**Three-layer separation. Modder never crosses layer.**

- **Surface layer** (`rsmm.sdk`): semantic verbs — `m.stat`, `m.texture`,
  `m.register_skin`. Stable across engine RE drift. Versioned:
  `sdk.v1`, `sdk.v2`. Old versions deprecated with one-release grace.
- **Capability layer** (`rsmm.core`): mod-kind primitives — Registry,
  EventBus, OverrideTable, ConflictResolver. Surface composes these.
- **Adapter layer** (`rsmm.engine`): cooked-byte writers, cipher,
  MinHook bindings. Brittle. Replaced on every game patch. Hidden.

**Event dispatch shape.**
- Pub/sub on named topics (strings), never raw offsets. Engine
  resolves topic→callsite once at boot.
- Two callback flavors: **observer** (cannot mutate) vs **mutator**
  (returns new context, framework merges chain).
- Priority field per subscription. Stable sort. Deterministic.
- Cancelable propagation only for observer kind; mutator chain
  always runs full.

**Capability negotiation.**
- Manifest declares `requires.api = ">=1.4"` +
  `requires.features = ["stat", "co-op-event-bus"]`.
- Loader refuses mod whose declared needs exceed runtime offerings.
  Better than load-then-crash.

**Naming.**
- Every modder-created entity carries `<mod_id>:<local_name>`.
  Globally unique by construction. Save files reference these
  strings, not numeric IDs.

---

## 2. Sandboxing & Fault Tolerance

**Lua per-mod isolation (partial today). Harden:**

- One `lua_State` per mod (have it). Add per-state **memory cap** via
  custom allocator. Reject allocation past limit → mod auto-disabled
  before OOM.
- **Instruction count limit** via Lua debug hook on every callback
  entry. Long-running script → terminate callback, mark mod degraded.
- All Lua entries from native side wrapped in `pcall`. Errors →
  structured log line (mod id + topic + Lua traceback). Never
  propagated back to engine stack.
- **Health budget**: N errors in M minutes → auto-disable mod,
  surface red in `rsmm doctor`. User decides re-enable.
- **Capability scoping**: file IO restricted to mod's own dir.
  Network IO denied unless manifest declares `requires.network = true`
  with whitelist.

**For native code mods (future):** in-process C++ mods can't be
sandboxed against segfault. Either don't allow native, or run in
separate process behind RPC. Recommend: modder-facing layer Lua-only.
Native = framework-author territory.

**Hook unwinder.**
- Every `MH_CreateHook` registers a paired `cleanup` callback in a
  global stack. Mod disable / shutdown → unwind LIFO. Failed remove
  → log + carry on, never leak.

**Quarantine on repeat failure.**
- Disk-resident mod-health journal (`mods/_health.json`). Loader
  reads on boot, refuses to start a mod that crashed N times in a
  row without a manifest version change. Forces modder to bump
  version on fix.

---

## 3. Patch Resilience (game updates)

**Three layers of binding, ordered most→least durable:**

1. **String / path anchors.** Engine reads cooked assets by path
   hash; path strings stable across patches. Today's foundation.
2. **Pattern signatures** for native hooks. Each MinHook target by
   byte-pattern with wildcards for register encoding + relocation.
   Resolve VA at boot via memory scan. Survives recompile VA shifts.
3. **Version-pinned offsets** as last resort. Disabled unless exe
   hash matches.

**Exe-hash gate.**
- On loader init, hash `Ravenswatch.exe`. Compare against known-good
  catalog (`data/exe_catalog.json`).
- Match → enable native hooks.
- Drift → run runtime "schema drift detector": re-resolve path
  anchors, open known cooked file, sanity-check class table. Pass
  → degraded mode (asset-only, native hooks off). Fail → refuse
  loader; asset-only mods still work.

**CI watchdog.**
- Weekly: pull public game depot, rebuild asset map, diff. Diff size
  over threshold → opens issue. Catches breakage upstream before
  users notice.

**Never persist absolute offsets.** Resolve fresh per boot.

---

## 4. Multiplayer State Synchronization

**Most critical gap. Today: undefined behavior under any non-cosmetic mod.**

**Scope taxonomy.** Manifest field `multiplayer_scope`: the author's declaration. Online matching does not trust it: `rsmm.engine.mod_scope` derives *client-only* vs *gameplay* from the mod's contents (see the modding guide's [Online play](/guides/modding/#online-play-client-only-and-gameplay-mods)).

- **cosmetic** — textures, audio, UI strings. Local-only.
- **deterministic-shared** — stat tweaks. MUST be identical on every
  peer. Framework enforces via mod-set hash exchange at lobby join.
- **host-authoritative** — difficulty mods, custom enemies, new items.
  Host enforces; clients receive results.
- **local-only** — HUD overlays, personal trackers. Per-peer; no
  engine state touched.

**Lobby handshake.**
- On lobby join, peers exchange a manifest digest (sorted hash of
  enabled `deterministic-shared` + `host-authoritative` mod IDs +
  versions + content hashes).
- Mismatch → host kicks or joiner refuses. Friendly "mod mismatch"
  dialog, not crash.
- Steam matchmaking lobby metadata is the cheap transport (string KV,
  already in-use).

**Determinism rules for shared mods.**
- No `math.random` in gameplay paths unless from host-seeded RNG the
  framework exposes.
- No system clock, no per-peer file IO, no network IO mid-frame.
- SDK provides `rsmm.rng(seed_topic)` returning deterministic stream.
- Lint check static-analyzes Lua AST for forbidden globals.

**Host-authoritative bridge.**
- Framework owns one synthetic network channel (piggyback on existing P2P).
- Mutator events on `host-authoritative` topics: client emits proposal,
  host computes authoritative result, broadcasts back, every peer
  applies. Single round-trip latency.
- High-frequency events (OnDamage): batch per game-tick. One packet
  per tick max.

**Reality check.** Engine network hook points unknown today. Phase:
identify Steam Networking call sites in `Ravenswatch.exe`, add
MinHook intercepts. Until then: framework refuses non-cosmetic mod
in a lobby. Surface clearly in UI.

---

## 5. Simplified Content Injection (Manager pattern)

**One registry per content kind. Modder hands data; manager owns IDs + injection.**

Registries:
- `Items` — ingredients, dream shards, rewards
- `Heroes` — skins, alt-abilities, stat profiles (not whole new heroes
  until re-encoder lands)
- `Enemies` — skin + stat variants of existing enemies
- `Modifiers` — custom difficulty modifiers
- `Localization` — text-bank additions
- `Sounds` — FMOD bank swaps

**Modder contract:**
- Modder declares content via SDK call:
  `m.register_item("RavenFeather", category="ingredient", stats={...})`.
- Manager allocates mod-prefixed namespaced ID
  (`MyMod:RavenFeather`).
- Manager translates to engine-format insertion (cooked-byte
  mutation OR runtime engine table augmentation).
- Modder never sees encoded path, never touches cooked binary.

**Save-file stability.**
- All registered content keyed by namespaced ID, never numeric slot.
- Mod uninstall → save loads with placeholder (item missing, not
  crash).
- Migration hook: modder registers `on_save_load(old_id) -> new_id`.

**Today's constraint.** True new content needs text-`.ot` →
binary-`.gen` re-encoder (deferred). Pragmatic interim:
- Registry layer DESIGNED + SDK API SHIPPED today, returns "not yet
  supported on this engine version" until re-encoder lands.
- Modders write against the stable API. When re-encoder ships,
  their mods work without rewrite.

This preserves authoring effort across the re-encoder gap.

---

## 6. Co-op Safe Hooks

**Event taxonomy per topic.** Each framework event carries metadata:

- `scope`: cosmetic / shared / host-only
- `cadence`: tick / event / one-shot
- `mutability`: observer / mutator
- `latency_budget_us`: per-callback wall time cap

**Dispatcher behavior:**
- Observer + cosmetic: fire local; no network, no host coordination.
- Observer + shared: fire on every peer; each peer's mod observes
  identical context (framework computes centrally, broadcasts).
- Mutator + host-only: fire on host; broadcast result; clients apply
  read-only.
- Mutator + shared: forbidden unless mod proves determinism via a
  static signature in manifest (`pure = true`).

**Latency control.**
- Per-tick aggregate Lua budget (e.g. 1 ms / frame across all mods).
  Exceed → frame drops the lowest-priority mod's callbacks for that
  frame, logs warning.
- Long-running computation goes to background coroutine; SDK exposes
  `rsmm.defer(fn)`.
- High-frequency events auto-coalesced: framework batches and
  delivers one summary per tick, not one call per instance.

**Concrete event surface (proposed, not all wired today):**
- `on_ready`, `on_exit` (live)
- `on_frame`, `on_menu_enter`, `on_menu_exit`
- `on_run_start`, `on_run_end`
- `on_hero_spawn`, `on_hero_death`
- `on_enemy_damaged` (mutator, host-only)
- `on_item_picked_up`, `on_skill_used`
- `on_chapter_complete`

Each needs an identified engine entry point. Roadmap entry, not
deliverable today.

---

## 7. Modder Onboarding Flow

**Goal: first-success in < 5 minutes.**

**Scaffolder with templates.**
- `rsmm new <id> --template <name>` writes a working starter:
  - `texture-swap` — donor-swap one cooked texture.
  - `stat-tweak` — change one balance number via SDK `[[patch]]`.
  - `lua-behavior` — `init.lua` skeleton with one event handler.
  - `composite` — multi-patch starter.
- Each template includes inline comments pointing at SDK docs.

**Canonical folder.**
- One layout, never two. `manifest.toml` + `assets/` + optional
  (`init.lua`, `build.py`, `README.md`, `LICENSE`).
- `rsmm lint <id>` validates structure, surfaces missing fields.

**Discoverability.**
- `rsmm sdk list` enumerates every SDK verb with one-line doc.
- `rsmm sdk show texture` prints full signature + example.
- Auto-generated SDK reference at `docs/SDK.md` from docstrings,
  regenerated in CI on every release.

**Documentation tiers** (in place, refine):
- **README.md** — landing, quickstart only.
- **docs/MODDING.md** — recipe book, one section per content kind.
- **docs/SDK.md** — API reference, auto-generated.
- **docs/INTERNALS.md** — engine RE notes, quarantined for the curious.
- **docs/ROADMAP.md** — open work + version targets.

Modder reads README → succeeds with template → opens MODDING →
graduates to SDK reference. Never forced to read INTERNALS.

**First-class debugging.**
- `rsmm doctor --mod <id>` scoped check.
- `rsmm trace <id>` runs with `RSMM_TRACE=1` and surfaces log inline.
- `rsmm diff <id>` shows which cooked files this mod would change (shipped).

**Empty-state UX.**
- Fresh checkout + `rsmm doctor` → green or actionable WARNs only.
- Every WARN has a one-line fix command.

---

## 8. Safe Overrides (conflict resolution)

**Conflict tiers, framework response per tier:**

| Tier | What | Default response |
|---|---|---|
| 1 | Same file, different fields | Merge (live today for stat + texture) |
| 2 | Same file, same field | Sort by `load_order`, ties by id; later wins. Log. |
| 3 | Same record, semantic conflict | Framework can't reconcile. Surface, suggest pick-one. |
| 4 | Logical contradiction across records | Tier 2 + warning. |

**Manifest compatibility graph.**
- `requires = ["other-mod-id >= 1.2"]` — hard dep.
- `conflicts = ["incompatible-id"]` — hard refuse.
- `replaces = ["older-version-id"]` — supersedes; loader auto-disables.
- `priority = N` — secondary sort within same `load_order`.
- Loader pre-validates graph: cycle, conflict, missing-dep. Failure
  surfaces in `rsmm doctor` and refuses apply.

**Override granularity ladder.** Nudge modders down the ladder:
- Worst: raw cooked-file drop in `assets/<path>`. One owner. No merge.
- Better: `[[patch]]` block declarative. Field-level merge.
- Best: registry call via SDK (`m.register_*`). Conflict-free by
  namespacing.

`rsmm doctor` nudges: "MyMod: ships a whole copy of `Hero_SunWukong.entity...`",
and `rsmm lint <id>` prints the `[[patch]]` / `[[content]]` block that rebuilds
it (shipped; stat, `.ot` and hero talent values).

**Lua mutator chains.**
- All chain handlers run, ordered by priority.
- Each handler receives current accumulated value, returns new value.
  Pure functional pipeline.
- Handler may declare `final = true` — chain terminates after it.
  Framework warns if two handlers both want `final`.

---

## SDK improvements (continued)

**Static validation at build time.**
- SDK `Mod.__exit__` runs a validation pass: every `m.stat(name)`
  checked against asset_map; every `m.texture(donor)` checked for
  existence; every text key checked against bank.
- Errors raised BEFORE manifest is written. Modder catches typos at
  `python3 build.py`, not at `rsmm apply`.

**IDE autocomplete via type stubs.**
- Ship `.pyi` stub files for `rsmm.sdk`. Modders get hover docs +
  autocomplete in VS Code / PyCharm. Zero runtime cost.
- Catalog of friendly aliases (hero names, enemy names, item names)
  exposed as typed enums — autocomplete drives discovery.

**High-level composite recipes.**
- `m.rebalance_hero("Aladdin", damage_mult=1.2, hp_mult=0.9)` →
  expands internally to N `[[patch]]` blocks across the right files.
- `m.replace_skin("Aladdin", from_pack="my_textures/")` → batches a
  directory of donor PNGs.
- Compositions inspectable: `rsmm explain MyMod` prints the expanded
  patch list.

**Dry-run mode.**
- `sdk.dry_run()` context manager: SDK records calls, returns the
  patch plan, writes nothing. Useful in tests + tooling.

**Test harness.**
- `rsmm test <mod_id>` runs SDK build in dry-run, applies merge,
  decodes the result, diffs against an expected fixture. Modders
  ship fixtures; CI verifies their mod still produces expected
  output as framework evolves.

**Versioning + migration.**
- Manifest field `sdk_version`. Loader maps old SDK calls to new
  ones via shims. Two-version overlap window. Old SDK calls emit
  deprecation in `rsmm doctor`.
- Content registry: save-file migration hooks. Mod author registers
  `migrate("old_id", "new_id")` in init code.

**Live SDK in Python REPL.**
- `python3 -m rsmm.sdk` launches interactive shell pre-imported.
  Exploration friction zero — list assets, try aliases, build a mod
  incrementally.

**Telemetry (opt-in, anonymized).**
- One toggle, off by default. Sends: SDK verbs called per session,
  exception fingerprints, mod-set size. Never mod content. Helps
  prioritize which verbs to optimize, which conflict patterns to
  design around.

**Hot-reload for Lua mods.**
- Today: relaunch game to pick up Lua changes. Cost: 30+ seconds
  per iteration.
- Improvement: loader watches `mods/<id>/init.lua` mtime; on change,
  tears down + recreates that mod's lua_State without restarting
  the game. ~95% iteration cycle reduction.

**Modder-facing event recorder.**
- `rsmm record <session>` captures every event the loader fires +
  every mod callback that subscribes. Replays deterministically.
  Modders debug intermittent bugs without re-running the game 50
  times.

---

## What to build first, what to research

**Build now (1–2 weeks each):**
- SDK static validation pass.
- `requires` / `conflicts` / `replaces` graph in manifest + doctor
  enforcement.
- SDK type stubs (.pyi).
- Composite recipes (rebalance_hero, replace_skin).
- Hot-reload for Lua mods.
- `rsmm test` harness.

**Research / multi-week:**
- Engine event hooks (OnDamage, OnHeroSpawn, …) — needs MinHook on
  identified call sites.
- Multiplayer manifest handshake — needs Steam Networking hook surface.
- Content registry backing — needs text-`.ot` → binary-`.gen`
  re-encoder.

**Defer until engine RE matures:**
- True new heroes / enemies / items.
- Custom 3D mesh import.
- Determinism static analyzer for Lua mutator chains.

The architecture above is future-proof against the engine work being
slow: modders write against the stable SDK surface today, deeper
features light up incrementally as engine RE lands. No author
rewrite at any milestone.

---

# 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.

---

# Engine symbol reference

> The canonical engine symbol map and how to use it.

Source: https://docs.rsmm.me/reference/symbols/

One human-authored source (`data/symbols.json`) generates every downstream artifact:

```mermaid
flowchart LR
    S["data/symbols.json<br/>(canonical, hand-authored)"]
    S -->|"rsmm symbols gen"| H["loader C++<br/>symbols.gen.h + API"]
    S -->|gen| E["event bus<br/>event_table.gen.h"]
    S -->|gen| L["Lua resolver<br/>engine_gen.lua"]
    S -->|gen| P["Python consts<br/>_symbols_gen.py"]
    S -->|gen| D["this page<br/>+ docs/SYMBOLS.md"]
    S -->|"ghidra-export"| G["Ghidra DB names"]
```

> GENERATED by `rsmm symbols gen` from `data/symbols.json` — do not edit by hand.

Canonical map of Ravenswatch engine functions/globals/events to stable
semantic names. `status`: **ok** = resolvable by byte pattern in the current
corpus (survives game updates); **va** = base-relative absolute (data globals);
**unverified** = documented in an older corpus, address not re-confirmed.
Functions tagged `callable` have a typed C++ accessor in `engine::` and a Lua
resolver entry. See [CLAUDE.md] for the workflow.

Total: **299** symbols across 24 categories.

## analytics

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `AnalyticsBag_SetInt` | `0x14020abf0` | ❓ unverified |  | void*(void* bag, void* keyDesc, uint64_t value, void* alloc) |
| `AnalyticsBag_SetString` | `0x140201c10` | ❓ unverified |  | void*(void* bag, void* keyDesc, void* valueDesc, void* alloc) |
| `Analytics_EmitActiveBoss` | `0x1401f9170` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitChapterEnd` | `0x1401f5c70` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitHeroDeath` | `0x1401f6e50` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitObjectProposed` | `0x1401f7760` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitObjectSelected` | `0x1401f79c0` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitOpenChest` | `0x1401f8f30` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitSandmanBuy` | `0x1401f6800` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitSkillProposed` | `0x1401f7120` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |
| `Analytics_EmitSkillSelected` | `0x1401f7440` | ❓ unverified |  | void(void* analyticsCtx, float* skillEvent, void* unused) |
| `Analytics_EmitUnlockSkill` | `0x1401f7e50` | ❓ unverified |  | void(void* analyticsCtx, void* args, void* unused) |

## combat

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `HeroStats_OnDamageDealt` | `0x14039aef0` | ✅ ok |  | void(oCDtEntityCpntHeroController* hero, oCEntity* victim, oCDtProcessedDamage* payload… |
| `HeroStats_OnDamageTaken` | `0x1403a0940` | ✅ ok |  | void(void* hero, void* payload) |
| `ProjectileAttack_BeginAttack` | `0x14083e7d0` | ✅ ok | ✔ | void(void* projectile_attack_cpnt) |

## enemies

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `EnemyCamp_Stage3Filter` | `0x140323830` | ❓ unverified |  | void(void* candidatesVec, void* searchFilter) |
| `EnemyCamp_TierSelector` | `0x14032e790` | ✅ ok |  | void(void* selector) |
| `EnemyCamp_TribeEntryBuilder` | `0x14032fe20` | ✅ ok |  | void(void* selector, void* specialEntry, void* outEntries, float mult) |
| `EnemyDef_PostLoad` | `0x14031a800` | ✅ ok |  | bool(void* enemyDef) |
| `EnemyDefinition_ctor` | `0x1401df270` | ✅ ok |  | void*(void* self) |
| `EnemyTribeDef_PostLoad` | `0x14031bae0` | ✅ ok |  | bool(void* tribeDef) |
| `EnemyTribeDefinition_ctor` | `0x1400c5260` | ✅ ok |  | void*(void* self) |
| `Enemy_RuntimeSpawnPicker` | `0x140364360` | ❓ unverified |  | void(void* spawnerCpnt) |
| `MapCtx_DistributeEnemyCampTiers` | `0x1401e8830` | ✅ ok |  | void(void* mapSceneContext) |

## engine

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Entry_Ctor` | `0x1402154b0` | ✅ ok | ✔ | void(void* base, uint32_t count) |
| `Format_String` | `0x1402092a0` | ✅ ok |  | printf-style format/string builder (e.g. 'Is Hero liked by {}', 'Chance to give {} MO')… |
| `LevelLoad_Orchestrator` | `0x14028e5f0` | ✅ ok |  | i64(void* levelGs) |
| `String_Assign` | `0x140529860` | ✅ ok | ✔ | void(void* dst_slot, const StringDesc* src) |
| `Vector_Grow` | `0x140155230` | ✅ ok | ✔ | void(void* vec, void* /*dead RDX*/, uint32_t new_cap /*R8*/) |

## engine-core

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `AppSettings_SectionList` | `0x1412f5aa8` | 📍 va |  | Global list of application-settings SECTIONS: {void** data @+0x0, u32 count @+0x8}. Rea… |
| `ClassRegistry_FindByKey` | `0x140523a10` | ❓ unverified |  | void*(void* unused, void* identityKey) |
| `ClassRegistry_Global` | `0x141436690` | 📍 va |  | Global class-descriptor registry: ptr to {descPtr array @+0x0, u32 count @+0x8}. Scanne… |
| `Component_GetTypeId` | `0x1401e6950` | ❓ unverified |  | uint32_t(void* component) |
| `Controller_GetFieldByKey` | `0x140396df0` | ❓ unverified |  | void*(void* controller, uint32_t key) |
| `CustomFlagFilter_Serialize` | `0x140189830` | ✅ ok |  | bool(void* flagFilter, void* reader) |
| `CustomFlagList_Serialize` | `0x140681e60` | ❓ unverified |  | bool(void* flagList, void* reader) |
| `Engine_MainThreadId` | `0x141443148` | 📍 va |  | Thread id of the engine main thread. LevelLoad_ProgressTick compares GetCurrentThreadId… |
| `Engine_Singleton` | `0x14143cbd0` | 📍 va |  | Pointer to the oe::Engine singleton (object at 0x14143daf0; ctor FUN_1404564d0 stores b… |
| `GameScene_FindContextByTester` | `0x14066cad0` | ✅ ok |  | void*(void* gameScene, void* kindOfTypeTester) |
| `MetaClass_AddMember` | `0x14050aa30` | ✅ ok |  | void(void* metaClass, void* member, uint32_t id, void* name, void* unused, void* userData) |
| `MetaClass_FindMember` | `0x14050cd20` | ✅ ok |  | void* (void* metaClass, uint32_t nameOrId, void* kind, bool searchParents) |
| `Profiler_GetThreadScopeStack` | `0x14053a660` | ❓ unverified |  | void*(void) |
| `Property_EvaluateByGuid` | `0x1406ab910` | ✅ ok |  | bool(void* ctx, void* container, void* guid16, float* out) |
| `ResourceRef_Serialize` | `0x1401c8e60` | ✅ ok |  | bool(void* reader, void* refSlot) |
| `Serializer_GetClassVersion` | `0x1404fce50` | ✅ ok |  | void*(void* reader, void* out, uint32_t classHash) |
| `Serializer_ReadEnum` | `0x14020c450` | ✅ ok |  | bool(void* serializer, void* vec) |
| `Serializer_ReadObjectNamed` | `0x140500d70` | ❓ unverified |  | bool(void* loader, void* root, const char* name) |
| `Serializer_ReadObjectPayload` | `0x1405006d0` | ❓ unverified |  | bool(void* loader, void* obj, const char* name) |
| `Serializer_ReadPolyPtrVector` | `0x14020e000` | ✅ ok |  | bool(void* reader, void* vec, const char* label) |
| `Serializer_ReadVectorObjIds` | `0x1402f3cf0` | ✅ ok |  | bool(void* serializer, void* vec) |
| `Serializer_ReadVectorU32` | `0x140364270` | ✅ ok |  | bool(void* serializer, void* vec) |
| `Serializer_ReadVectorU8` | `0x1403646c0` | ✅ ok |  | bool(void* serializer, void* vec) |
| `Serializer_ResolveObjectId` | `0x140500630` | ❓ unverified |  | bool(void* loader, void** out, const char* label) |
| `ServiceRegistry_Global` | `0x14146f740` | 📍 va |  | Global engine service registry: service array @+0x30, u32 count @+0x38; each entry -> s… |
| `StringVector_Serialize` | `0x140684f30` | ❓ unverified |  | bool(void* reader, void* strVec) |
| `Vector_InsertRange` | `0x1401556e0` | ✅ ok | ✔ | void*(void* vector, unsigned index, unsigned count) |

## entity

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `EnemyController_Ctor` | `0x140389d00` | ✅ ok | ✔ | oCDtEntityCpntEnemyController*(oCDtEntityCpntEnemyController* self) |
| `EnemyController_vftable` | `0x140f30b78` | 📍 va |  | Vftable of oCDtEntityCpntEnemyController. Derived from MSVC RTTI (type descriptor .?AVo… |
| `EntityPool_AllocNode` | `0x140690e50` | ✅ ok |  | void*(void* pool) |
| `EntitySpawner_InstantiateRecord` | `0x140730f80` | ✅ ok |  | void(oCEntityCpntEntitySpawner* self, void* spawnRecord) |
| `EntitySpawner_SpawnOne` | `0x140730150` | ✅ ok |  | void(oCEntityCpntEntitySpawner* self) |
| `EntityStore_CreateEntity` | `0x1406f5dc0` | ✅ ok | ✔ | oCEntity*(oCEntitySpawner* spawner, oCEntitySettings* settings, oCEntitySpawnData* spaw… |
| `EntityValueEntry_Ctor` | `0x140747120` | ✅ ok | ✔ | void(void*, void*) |
| `EntityValueOverride_Alloc` | `0x140770290` | ✅ ok | ✔ | void*(void*, uint32_t, uint32_t) |
| `EntityValueStore_ApplyModifierEvent` | `0x14074b2f0` | ✅ ok | ✔ | void(void* store, void* modifierEvent, void* a3, void* a4) |
| `EntityValueStore_InitBaseValues` | `0x140747f20` | ✅ ok | ✔ | void(void* store) |
| `EntityValueStore_Recompute` | `0x140749a90` | ✅ ok | ✔ | void(void* store, void* valueDef) |
| `EntityValueUnion_Compare` | `0x14082ceb0` | ✅ ok | ✔ | uint32_t(void*, void*) |
| `EntityValueUnion_CopyAssign` | `0x14082b1d0` | ✅ ok | ✔ | void(void*, void*) |
| `EntityValueUnion_DefaultCtor` | `0x14082aa60` | ✅ ok | ✔ | void*(void*) |
| `EntityValueUnion_Destruct` | `0x14082dae0` | ✅ ok | ✔ | void(void*) |
| `EntityValueUnion_InitAsType` | `0x14082d670` | ✅ ok | ✔ | void(void*, uint32_t) |
| `EntityValue_Get` | `0x1403c7fa0` | ✅ ok | ✔ | void(void* valueCtx, oCEntityValueUnion* out, uint32_t crcKey) |
| `EntityValue_Lookup` | `0x140749260` | ✅ ok | ✔ | oCEntityValueUnion*(void* store, oCEntityValueUnion* out, uint32_t crcKey) |
| `Entity_AllocInstance` | `0x1406a8d80` | ❓ unverified | ✔ | void*(void* allocator) |
| `Entity_DispatchHit` | `0x1406e3ce0` | ✅ ok | ✔ | void(oCEntity* target, oCEntityHitData* hit) |
| `Entity_FindComponentByType` | `0x1406e3210` | ✅ ok | ✔ | oIEntityCpnt*(oCEntitySpawnerGo* go, oCMetaClass* meta) |
| `Entity_FindMagicalObjectComponent` | `0x1406fb8a2` | ❓ unverified | ✔ | void*(void* instance, void* mo_component_meta) |
| `Entity_GainHealthHandler` | `0x140399d00` | ✅ ok |  | void(oCEntity* hero, void* a2, void* valueCtx) |
| `Entity_GetComponentByTester` | `0x1406e3210` | ✅ ok | ✔ | void*(void*, void*) |
| `Entity_GetComponentFast` | `0x1406e31a0` | ✅ ok | ✔ | void*(void*, void*, uint32_t) |
| `Entity_ResolveAttackHits` | `0x1403dd540` | ✅ ok | ✔ | float(void* attacker, uint hitDefIndex, TargetList* targets, float damageMul, float bas… |
| `HeroController_Ctor` | `0x14038ec30` | ✅ ok | ✔ | oCDtEntityCpntHeroController*(oCDtEntityCpntHeroController* self) |
| `HeroController_HudMirror_Ctor` | `0x1403b3c70` | ✅ ok |  | Builds the hero's HUD HP-mirror object whose pointer is stored at hero+0x1d80 by HeroCo… |
| `Hero_ModifyDreamShards` | `0x14039a320` | ✅ ok | ✔ | void(oCDtEntityCpntHeroController* hero, float delta, oCCustomFlagList* sourceTags) |
| `HitPoint_SetHitPoints` | `0x140822db0` | ✅ ok | ✔ | void(oCEntityCpntHitPoint* hp, float value) |
| `MapCtx_LinkPairedSpawners` | `0x1401ebad0` | ✅ ok |  | void(void* mapSceneContext) |
| `ModifierEvent_Ctor` | `0x140389fb0` | ✅ ok | ✔ | void*(void* buf, void* valueDef) |
| `g_MagicalObjectComponentMeta` | `0x141470768` | 📍 va |  | oCMetaClass* for the magical-object component; passed to Entity_FindMagicalObjectCompon… |
| `oCCustomFlagList_vftable` | `0x140f01650` | 📍 va |  | vftable of oCCustomFlagList. An empty list is the 0x18-byte struct { vftable @+0x0, lis… |
| `oCEntityHitData_vftable` | `0x140f137d8` | 📍 va |  | vftable of oCEntityHitData (the ~0xb0-byte hit descriptor passed to Entity_DispatchHit … |
| `oCEntityValueUnion_vftable` | `0x140f95008` | 📍 va |  | vftable of oCEntityValueUnion, the ~0x20-byte tagged value returned by EntityValue_Look… |
| `oCGameEventNetworkModifier_vftable` | `0x140f322d0` | 📍 va |  | vftable of oCGameEventNetworkModifier — the durable stat-modifier named event (leaf of … |

## entity-values

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `EntityValueRegistry_RegisterAll` | `0x1401da350` | ✅ ok |  | void(void) |
| `SceneContextValue_Find` | `0x1401c9600` | ✅ ok | ✔ | oCEntityValueUnion*(void* sceneContext, uint32_t crcKey) |
| `SceneContextValue_SetBool` | `0x140209010` | ✅ ok | ✔ | void(void* sceneContext, uint32_t crcKey, bool value) |
| `SceneContextValue_SetFloat` | `0x14020a580` | ✅ ok | ✔ | void(void* sceneContext, uint32_t crcKey, float value) |
| `SceneContextValue_SetInt` | `0x1402091a0` | ✅ ok | ✔ | void(void* sceneContext, uint32_t crcKey, int32_t value) |
| `g_GlobalEntityValueSceneContext_Tester_vftable` | `0x140f09e68` | 📍 va |  | Vftable of oCTKindOfTypeTester<oCGlobalEntityValueSceneContext, oIGameSceneContext>, re… |

## event

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Analytics_SubmitNamedEvent` | `0x1401fad70` | ✅ ok | ✔ | void(void* analytics_mgr, void* payload_kv, StringDesc* event_name, char has_run_ctx) |
| `Crc32_TableInit` | `0x14051ef30` | ✅ ok |  | Builds the 256-entry CRC32 lookup table at DAT_141436710 (lazy, runtime — the table is … |
| `EventQueue_Drain` | `0x1406642d0` | ✅ ok |  | void(void* queue) |
| `Event_LevelUp` → `level_up` | `0x1401f6bf0` | ✅ ok | ✔ | Emitter whose body references the 'level_up_reach' string (xref 0x1401f64a4). void(ctx,… |
| `Event_RunEnd` → `run_end` | `0x1401f59c0` | ✅ ok | ✔ | Emitter whose body references the 'run_end' string (xref 0x1401f5347). Loader post-deto… |
| `Id_HashString` | `0x14033f7a0` | ❓ unverified |  | Runtime string -> 32-bit id hasher: standard CRC32 over the name bytes (init 0xffffffff… |
| `NamedEvent_ChannelMap_Find` | `0x14066dc10` | ✅ ok | ✔ | iter*(void* channel_map, iter* out, uint32_t* event_id) |
| `NamedEvent_Delete` | `0x1401273b0` | ✅ ok | ✔ | void(oCGameNamedEvent* ev) |
| `NamedEvent_Dispatch` | `0x14066b6b0` | ✅ ok | ✔ | void(void* dispatcher, oCGameNamedEvent* ev) |
| `NamedEvent_EmitNetworkDamageFromHit` | `0x1407276a0` | ✅ ok |  | Reference emitter for NETWORK_DAMAGE: stack-builds the full oCGameNamedEventNetworkDama… |
| `NamedEvent_GiveMagicalObject_Ctor` | `0x14030fd30` | ✅ ok | ✔ | oe::dt::NamedEventGiveMagicalObject*(void* buf) |
| `NamedEvent_HeroSubscribeAll` | `0x140391860` | ✅ ok | ✔ | void(oCEntity* hero) |
| `NamedEvent_HeroUnsubscribeAll` | `0x140395350` | ✅ ok |  | Hero teardown twin of NamedEvent_HeroSubscribeAll: walks the same (id global, slot) pai… |
| `NamedEvent_Id_FromCrc` | `0x14051f090` | ✅ ok | ✔ | uint32_t(uint32_t ns, uint32_t name_crc) |
| `NamedEvent_NetSend` | `0x140721630` | ✅ ok | ✔ | void(void* net_event_cpnt, oCGameNamedEvent* ev) |
| `NamedEvent_NetSendToPeer` | `0x1407216c0` | ✅ ok | ✔ | void(void* net_event_cpnt, oCGameNamedEvent* ev, uint64_t* peer_session) |

## gameplay

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `DayNightCycle_InitCycle` | `0x1401eca80` | ❓ unverified |  | Per-CHAPTER setup of the day/night component (this = component in RCX), called from the… |
| `DayNightCycle_PushValues` | `0x1401ee1c4` | ❓ unverified |  | Per-frame writer for the 'Day/Night cycle' value family (see DayNightCycle_RegisterValu… |
| `DayNightCycle_RegisterValues` | `0x1401ee9e3` | ❓ unverified |  | Registers the 'Day/Night cycle' entity-value family: 27 named values plus 9 named trigg… |

## hero

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `GroupLevelComponent_Ctor` | `0x1402e1de0` | ✅ ok | ✔ | void*(void* self) |
| `Hero_GainExperience` | `0x1402e2f00` | ✅ ok | ✔ | void(void*, void*) |
| `XpComponent_GetMaxLevel` | `0x1402e2d30` | ✅ ok | ✔ | uint32_t(void*) |
| `XpComponent_IsMaxLevel` | `0x1402e2d90` | ✅ ok | ✔ | bool(void*) |
| `XpComponent_SetLevel` | `0x1402e3190` | ✅ ok | ✔ | void(void*, uint32_t) |
| `XpComponent_SetXp` | `0x1402e3630` | ✅ ok | ✔ | void(void*, uint32_t) |
| `XpComponent_TypeTester` | `0x141476e00` | 📍 va |  | Type-tester global (DAT_141476e00) used by the XP component's own IsKindOf/parent-resol… |
| `XpComponent_XpForLevel` | `0x1402e2c30` | ✅ ok | ✔ | uint32_t(void*, uint32_t) |
| `XpComponent_vftable` | `0x140f231b0` | 📍 va |  | Vftable of the hero's XP/level component. CORRECTED 2026-07-18 from 0x140f23200, which … |

## heroes

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `ChallengeUnlock_IsUnlocked` | `0x1402b1100` | ✅ ok | ✔ | bool(void* condition_data) |
| `HeroDef_Deserialize` | `0x14031ef30` | ✅ ok | ✔ | bool(oCDtHeroDefinition* def, oCBinaryStream* stream) |
| `HeroDef_LoadBaseEntity` | `0x14031ece0` | ✅ ok |  | void(void* heroDef, void** outEntityRef) |
| `HeroDef_LoadSkinEntity` | `0x14031ea40` | ✅ ok |  | void(void* heroDef, uint16_t skinIndex, void* outHandle) |
| `HeroProgressionUnlock_IsUnlocked` | `0x1402b2b10` | ✅ ok | ✔ | bool(void* condition_data) |
| `HeroRankLock_IsUnlocked` | `0x1402b1c10` | ✅ ok | ✔ | bool(void* condition_data) |
| `HeroStoryUnlock_IsUnlocked` | `0x1402b21a0` | ✅ ok | ✔ | bool(void* condition_data) |

## items

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Entity_GiveHandler` | `0x1403c7560` | ✅ ok |  | void(oCEntityValueContext* heroValueCtx, oCEntity* hero, void* hitCtx) |
| `Entity_LookupMagicalObjectComponent` | `0x1406e3280` | ✅ ok | ✔ | void*(void* componentStore, void** out, oCEntity* entity) |
| `Hero_GrantMagicalObject` | `0x140397aa0` | ✅ ok | ✔ | void(oCDtEntityCpntHeroController* hero, void* def, uint16_t count, char dupFlag, void*… |
| `InitialLoading_SpawnMagicalObjects` | `0x140259060` | ❓ unverified |  | Boot 'InitialLoading - MagicalObject SpawnAllObjects' caller that invokes SpawnAllObjec… |
| `MagicalObjectPool_Grow` | `0x140156de0` | ❓ unverified | ✔ | void(void* pool_plus_0x10, uint32_t count, uint32_t by) |
| `MagicalObjectPool_SourceLookup` | `0x14025e3e0` | ❓ unverified | ✔ | void*(void* pool, void* out, void* id) |
| `MagicalObject_RegisterInstance` | `0x1403abb90` | ✅ ok | ✔ | void(oCDtEntityCpntHeroController* hero, void* instance, char addToActive) |
| `MagicalObject_SpawnAllObjects` | `0x140259060` | ✅ ok | ✔ | void(void* pool, void* scene) |
| `MagicalObject_SpawnContainingFunc` | `0x14025d9b0` | ✅ ok |  | Outer function (1283 bytes) that contains the inlined SpawnAllObjects entry at +0x70. T… |
| `g_MagicalObjectPool` | `0x14143cc18` | 📍 va |  | [2026-07-10: re-derived post 2026-07-09 patch (was 0x1414365d0); confirmed via readers … |

## library

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `AchievementDef_PostLoad` | `0x140312060` | ✅ ok | ✔ | bool(void* definition) |
| `ChallengeDef_PostLoad` | `0x140324f30` | ✅ ok | ✔ | bool(void* definition) |
| `DefinitionRegistry_Ctrl` | `0x1412f0a68` | 📍 va |  | Instance registry SwissTable (absl flat_hash_map) keyed on the class-descriptor pointer… |
| `DefinitionRegistry_Mask` | `0x1412f0a80` | 📍 va |  | Instance registry SwissTable (absl flat_hash_map) keyed on the class-descriptor pointer… |
| `DefinitionRegistry_Slots` | `0x1412f0a70` | 📍 va |  | Instance registry SwissTable (absl flat_hash_map) keyed on the class-descriptor pointer… |
| `Definition_DeserializeBase` | `0x140310180` | ✅ ok |  | bool(void* def, void* reader) |
| `Definition_PostLoad` | `0x140310200` | ✅ ok | ✔ | bool(void* definition) |
| `Definition_PreUnload` | `0x140310230` | ✅ ok | ✔ | void(void*) |
| `Definition_Unload` | `0x1403238a0` | ❓ unverified |  | bool(void* definition) |
| `DreamShardDef_PostLoad` | `0x140312690` | ✅ ok | ✔ | bool(void* definition) |
| `EnemyCampTierDef_PostLoad` | `0x140319620` | ✅ ok | ✔ | bool(void* definition) |
| `GameModeDefaultDef_PostLoad` | `0x140325950` | ✅ ok | ✔ | bool(void* definition) |
| `GameModifierDef_PostLoad` | `0x140326250` | ✅ ok | ✔ | bool(void* definition) |
| `GameModifierDef_RegisterAssetLoader` | `0x1403260b0` | ✅ ok |  | void(void* assetClassDesc) |
| `GoPtrOwnerRelay_ForwardCall` | `0x14066bf00` | ✅ ok |  | oIGoPtrOwnerRelay base virtual (slot +0x18): resolves owned via slot-0x30, forwards own… |
| `GoPtrOwnerRelay_ForwardGet` | `0x14066be70` | ✅ ok |  | oIGoPtrOwnerRelay base virtual (vtable 0x140f06820 slot +0x8): resolves the owned objec… |
| `GoPtrOwnerRelay_ForwardSet` | `0x14066bec0` | ✅ ok |  | oIGoPtrOwnerRelay base virtual (slot +0x10): resolves owned via slot-0x30, forwards own… |
| `HasGameModifierStateMachine_Register` | `0x140197780` | ✅ ok |  | void(void) |
| `HeroDef_PostLoad` | `0x14031fd70` | ✅ ok | ✔ | bool(void* definition) |
| `IngredientDef_PostLoad` | `0x140323190` | ✅ ok | ✔ | bool(void* definition) |
| `Library_AchievementDefinition_vftable` | `0x140f27660` | 📍 va |  | vftable of oCTLibrary<oe::dt::AchievementDefinition> singleton. ⚠ ADDRESS CORRECTED 202… |
| `Library_ChallengeDefinition_vftable` | `0x140f299d8` | 📍 va |  | vftable of oCTLibrary<oe::dt::ChallengeDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-… |
| `Library_DreamShardDefinition_vftable` | `0x140f27178` | 📍 va |  | vftable of oCTLibrary<oCDtDreamShardDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-… |
| `Library_EnemyCampDifficultyDefinition_vftable` | `0x140f280e0` | 📍 va |  | vftable of oCTLibrary<oCDtEnemyCampDifficultyDefinition> singleton. ⚠ ADDRESS CORRECTED… |
| `Library_EnemyCampTierDefinition_vftable` | `0x140f2ad30` | 📍 va |  | vftable of oCTLibrary<oCDtEnemyCampTierDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-… |
| `Library_EnemyDefinition_vftable` | `0x140f2b450` | 📍 va |  | vftable of oCTLibrary<oCDtEnemyDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-17: t… |
| `Library_EnemyTribeDefinition_vftable` | `0x140f2aeb8` | 📍 va |  | vftable of oCTLibrary<oCDtEnemyTribeDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-… |
| `Library_EntitySettingsResource_vftable` | `0x140f75e60` | 📍 va |  | vftable of oCTLibrary<oCEntitySettingsResource> singleton. ⚠ ADDRESS CORRECTED 2026-09-… |
| `Library_GameModifierDefinition_vftable` | `0x140f2a960` | 📍 va |  | vftable of oCTLibrary<oe::dt::GameModifierDefinition> singleton. GameModifiers = the ru… |
| `Library_IngredientDefinition_vftable` | `0x140f29a18` | 📍 va |  | vftable of oCTLibrary<oCDtIngredientDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-… |
| `Library_MapDefinition_vftable` | `0x140f29810` | 📍 va |  | vftable of oCTLibrary<oCDtMapDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-17: the… |
| `Library_MelodyDefinition_vftable` | `0x140f29af8` | 📍 va |  | vftable of oCTLibrary<MelodyDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-17: the … |
| `Library_RewardDefinition_vftable` | `0x140f298a8` | 📍 va |  | vftable of oCTLibrary<oCDtRewardDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-17: … |
| `Library_TileDefinition_vftable` | `0x140f2b0e0` | 📍 va |  | vftable of oCTLibrary<oCDtTileDefinition> singleton. ⚠ ADDRESS CORRECTED 2026-09-17: th… |
| `Library_VersionDefinition_vftable` | `0x140f297c0` | 📍 va |  | vftable of oCTLibrary<oe::dt::VersionDefinition> singleton (LiveOps version manifest). … |
| `MapDef_PostLoad` | `0x1403234f0` | ✅ ok | ✔ | bool(void* definition) |
| `MapDef_RegisterAssetLoader` | `0x140323350` | ✅ ok |  | void(void* assetClassDesc) |
| `MelodyDef_PostLoad` | `0x140326f50` | ✅ ok | ✔ | bool(void* definition) |
| `Mem_Alloc16Zeroed` | `0x14050d5c0` | ✅ ok |  | malloc(0x10) + zero two qwords + bump global alloc counter DAT_1414442b4 = 16-byte zero… |
| `PtrVector_Resize` | `0x140155230` | ✅ ok |  | pointer-vector resize: param_3==0 frees vec[0] (free-counter DAT_14146d854), else mallo… |
| `Registry_EnemyDefinition_desc` | `0x141470208` | 📍 va |  | Class registry descriptor for oCDtEnemyDefinition (set by registrar FUN_14022d940; UID … |
| `Registry_EnemyTribeDefinition_desc` | `0x14146f938` | 📍 va |  | Class registry descriptor for oCDtEnemyTribeDefinition (registrar FUN_140189410; UID 0x… |
| `RewardDef_RegisterAssetLoader` | `0x140324460` | ✅ ok |  | void(void* assetClassDesc) |
| `Rt_FailFast` | `0x140cc7e04` | ✅ ok |  | CRT fail-fast: FUN_140cc7c90 then _invoke_watson (noreturn). 4459 refs. Naming it de-no… |
| `SharedRef_AddRefCopy` | `0x1401663a0` | ✅ ok |  | base virtual: copies {*(this+0x18) data, *(this+0x20) refblock} into out and addrefs at… |
| `SharedRef_AddRefCopy_b` | `0x14021e390` | ✅ ok |  | identical twin of SharedRef_AddRefCopy (separate TU); base virtual in 298 vtables. Deco… |
| `SharedRef_Release` | `0x140111cf0` | ✅ ok | ✔ | void(void*) |
| `TileDef_Deserialize` | `0x140324690` | ❓ unverified |  | bool(oCDtTileDefinition* def, oCBinaryStream* stream) |
| `TypeDesc_HashName` | `0x1404fd5d0` | ✅ ok |  | base virtual: vcall slot0 -> type descriptor, reads its oCString name (inline @+8 / hea… |
| `TypeDesc_HashName_b` | `0x1401c96e0` | ✅ ok |  | identical twin of TypeDesc_HashName (separate TU); base virtual in 292 vtables. Decompi… |
| `oCString_Dtor` | `0x140111d90` | ✅ ok |  | oCString destructor: SSO threshold 0xf; heap buffer's real alloc ptr at [buf-8], frees … |

## melodies

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `HeroMelodyPersistentData_vftable` | `0x140f12f40` | 📍 va |  | vftable of HeroMelodyPersistentData ("Dt Hero Controller Owned Melody Persistent Data",… |
| `oCGameNamedEventChooseMelody_vftable` | `0x140f25c48` | 📍 va |  | vftable of NamedEventChooseMelody (RTTI .?AVNamedEventChooseMelody@dt@oe@@, typedesc 0x… |
| `oCGameNamedEventRemoveMelody_vftable` | `0x140f22608` | 📍 va |  | vftable of NamedEventRemoveMelody (typedesc 0x14137bc38); same shape and origin as oCGa… |

## netcode

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Entity_GetNetComponent` | `0x140312db0` | ✅ ok | ✔ | void*(oCEntity* entity) |
| `Entity_GetNetId` | `0x1407273c0` | ✅ ok |  | uint32_t(void* entity) |
| `Fcm2_OnClosedConnection` | `0x140ac94a0` | ✅ ok |  | void(FullyConnectedMesh2* this, const SystemAddress& addr, RakNetGUID guid, int reason) |
| `Netcode_Channel_LookupById` | `0x140241a50` | ✅ ok | ✔ | iter*(void* channel_map, iter* out, uint32_t* event_id) |
| `Netcode_Channel_Unsubscribe` | `0x1401c8da0` | ✅ ok | ✔ | void(void* node_plus_8, void** sub_slot) |
| `Netcode_ConnectionFactory` | `0x140b287f0` | ❓ unverified |  | Builds a Stormancer::RakNetConnection for an incoming RakNetGUID and files it in the co… |
| `Netcode_ConnectionRegistry_Emplace` | `0x140b2fd80` | ❓ unverified |  | MSVC std::unordered_map<uint64,...>::try_emplace for the netcode's CONNECTION REGISTRY.… |
| `Netcode_DropPeer` | `0x1402b4d50` | ✅ ok |  | Drops a peer after the reconnect window (default 60s) elapses. Pattern-verified 2026-07… |
| `Netcode_EntityReplSetup` | `0x14073dda0` | ❓ unverified | ✔ | void(void* replContext) |
| `Netcode_PeerStateTick` | `0x1402b03a0` | ✅ ok |  | Per-peer connection-state tick (peer conn-state enum at peer+0xCC; 3=connected). Reconn… |
| `Netcode_SessionCtx_LocalGuid` | `0x1408b7550` | ❓ unverified |  | oCDtP2PSessionSceneContext::vft[0x88] — returns THIS machine's session id. Ghidra 2026-… |
| `P2PSession_OnFcm2NewHost` | `0x1408b8530` | ✅ ok |  | The game's ID_FCM2_NEW_HOST handler -- i.e. where RakNet's FullyConnectedMesh2 host ELE… |
| `P2PSession_SetState` | `0x14085ca70` | ✅ ok |  | void(oCDtP2PSessionSceneContext* ctx, int newState) |
| `P2PSession_StateNames` | `0x140eece10` | 📍 va |  | struct { const char* s; uint32 len; } [14]  // 0x10 stride |
| `RakNetConnection_Ctor` | `0x140b9cd50` | ❓ unverified |  | Stormancer::RakNetConnection constructor. Ghidra 2026-08-21: installs Stormancer::IConn… |
| `RakPeer_GetGuidFromSystemAddress` | `0x140ae33d0` | ✅ ok |  | RakNetGUID(RakPeer* this, const SystemAddress& addr) |
| `RakPeer_GetMyGUID` | `0x140ae3280` | ❓ unverified |  | const RakNetGUID&(RakPeer* this) |
| `RakPeer_GetSystemAddressFromGuid` | `0x140ae3570` | ✅ ok |  | SystemAddress(RakPeer* this, const RakNetGUID& guid) |
| `RakPeer_GetSystemList` | `0x140ae1700` | ✅ ok |  | void(RakPeer* this, List<SystemAddress>& addresses, List<RakNetGUID>& guids) |
| `SLNetworkObject_GetOwnerId` | `0x1408c0d40` | ❓ unverified |  | void* __fastcall(oCSLNetworkObject* self, uint64_t* out) |

## options

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `GameModifierUi_PadSelectedSlots` | `0x140360c20` | ✅ ok | ✔ | void(void* uiController, void* unknown, void* selectedVector) |
| `g_GameOptions` | `0x14143cb58` | 📍 va |  | [2026-07-10: re-derived post 2026-07-09 patch (was 0x141436510); ctor is now FUN_1401ca… |

## resource

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `BinarySaver_CollectDependencies` | `0x1404fc950` | ❓ unverified |  | bool(void* saver, void* rootObject) |
| `BinarySaver_WriteGraph` | `0x140501a30` | ✅ ok | ✔ | bool(void* saver, void* rootObject, const char* label, void* ctx) |
| `BinarySaver_WriteObject` | `0x1405016c0` | ✅ ok | ✔ | bool(void* saver, void* object, const char* label, bool flag) |
| `Definition_PreloadResourceCache` | `0x140310fb0` | ❓ unverified |  | void(void* definition) |
| `Definitions_LoadGroup` | `0x140310300` | ✅ ok |  | Loads the 'Definitions' group / VersionDefinition manifest (triggers loading the curate… |
| `FileStream_Open` | `0x14053a730` | ❓ unverified |  | bool(void** outHandle, const char* path, int* mode) |
| `InitialLoading_LoadAllDefinitions` | `0x140260b80` | ✅ ok |  | void(void* nameFilter) |
| `LevelBinary_Load` | `0x1404764f0` | ❓ unverified |  | bool(void* container, void* stream, void* lvlId, void* links) |
| `LevelDatabase_BuildAndRegister` | `0x14047cf80` | ✅ ok |  | bool(void* db, void* level, bool flag) |
| `LevelLoad_AbortPredicate` | `0x140456c70` | ❓ unverified |  | uint32_t() |
| `LevelLoad_ProgressTick` | `0x140516cd0` | ❓ unverified |  | uint32_t(float delta) |
| `LevelObject_DestroyVectors` | `0x140476f60` | ❓ unverified |  | void(void* container) |
| `LevelObject_LoadOrCreate` | `0x14047c1e0` | ✅ ok |  | bool(void* mgr, void* key, void** outLevel, char link, char flag, void* lvlId, void* re… |
| `LevelStream_LoadLevel` | `0x14047b4f0` | ❓ unverified |  | bool(void* mgr, void* key, void** outLevel, char applyLinks, void* userData) |
| `LevelStream_LoadStep` | `0x140476770` | ✅ ok |  | bool(void* container, void* resourceSlot, void* lvlId, void* links) |
| `LevelStream_ProgressHook` | `0x1412ebf30` | 📍 va |  | Function pointer for load-progress phases, set to LevelLoad_AbortPredicate in FUN_14045… |
| `LevelText_Load` | `0x140476340` | ❓ unverified |  | bool(void* container, char** name, void* lvlId, void* links) |
| `Object_CloneViaSerialize` | `0x1404fe640` | ✅ ok | ✔ | bool(void* dstObject, void* srcObject, void* ignored3, void* ignored4) |
| `Object_LoadFromStream` | `0x1404fd6b0` | ✅ ok | ✔ | bool(void* object, void* readStream) |
| `Object_SaveToFile` | `0x1404fd7e0` | ✅ ok | ✔ | bool(void* object, void* pathString, bool cooked, void* ctx) |
| `Registry_EnumInstances` | `0x140241750` | ✅ ok | ✔ | void*(void* unused, void* out3, void** classDescPtr) |
| `Registry_RegisterInstance` | `0x1403119d0` | ✅ ok |  | void(void* definition) |
| `Registry_UnregisterInstance` | `0x140311a50` | ✅ ok | ✔ | void(void*) |
| `ResourceCache_Parse` | `0x140492a10` | ❓ unverified |  | bool(void* outVector, void* cachePath) |
| `ResourceCache_Submit` | `0x1404aa3a0` | ✅ ok |  | void(void* resourceSink, void* entryVector) |
| `ResourceRef_Resolve` | `0x140492540` | ✅ ok |  | void(void* refBlock, void* classDesc, void** outResolved, void* policy) |
| `Resource_LookupByPath` | `0x14049b2a0` | ✅ ok | ✔ | void*(const char* decoded_path, void*, void*, void*) |

## rewards

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `CustomFlagList_ContainsAll` | `0x14066ac70` | ✅ ok |  | bool(void* flagListA, void* flagListB) |
| `CustomFlagList_ContainsAny` | `0x14066ad90` | ✅ ok |  | bool(void* flagListA, void* flagListB) |
| `RewardDef_Deserialize` | `0x1403244c0` | ✅ ok |  | bool(void* rewardDef, void* reader) |
| `RewardItem_Serialize` | `0x140323dd0` | ✅ ok |  | bool(void* oCItem, void* reader) |
| `RewardSelectorSettings_Serialize` | `0x140340470` | ✅ ok |  | bool(void* settings, void* reader) |
| `RewardType_Serialize` | `0x140324260` | ✅ ok |  | bool(void* oCType, void* reader) |
| `Reward_GenerateAndDistribute` | `0x1401ecd10` | ❓ unverified |  | void(void* mapSceneContext) |
| `Reward_InitAllRewards` | `0x1401e9800` | ✅ ok |  | _InitAllRewards (7351 bytes): reward-type registrar. The actual reward roller is a sibl… |

## session

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Account_GetDisplayName` | `0x140929940` | ✅ ok |  | void(std::string* out, void* account) |
| `HeroSelect_IsHeroAvailable` | `0x14032b460` | ✅ ok | ✔ | bool(void* menu, int hero_index, bool flag) |
| `LobbyAttributes_Parse` | `0x140922f20` | ✅ ok | ✔ | void*(void* self, StringDesc* blob) |
| `LobbyAttributes_Serialize` | `0x140923e00` | ✅ ok | ✔ | void*(void* out, void* member) |
| `LobbyMembers_List` | `0x140925420` | ❓ unverified |  | void(void** scene, std::vector<LobbyMember*>* out) |
| `LobbyMembers_Local` | `0x1409253a0` | ❓ unverified |  | void(void** scene, LobbyMember** out) |
| `LobbyPlayerName_Registry` | `0x141476268` | 📍 va |  | std::string[]  // count at 0x141476270 |
| `Netcode_PeerCount` | `0x14143f780` | 📍 va |  | uint32_t |
| `Netcode_PeerSlots` | `0x14143f600` | 📍 va |  | PeerSlot[]  // 0x60 stride; live count at Netcode_PeerCount |

## skill

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `EntityComponent_Activate` | `0x140712c50` | ✅ ok | ✔ | void(void* unused, oIEntityCpnt* cpnt) |
| `EntityEventTrigger_Fire` | `0x140713b00` | ✅ ok | ✔ | void(EventTrigger* trig) |
| `HeroController_AddSkill` | `0x1403974b0` | ✅ ok | ✔ | void(HeroController* hero, oCDtEntityCpntSkillController* ctrl) |
| `HeroController_RemoveSkill` | `0x1403977b0` | ✅ ok | ✔ | void(HeroController* hero, oCDtEntityCpntSkillController* ctrl, bool clear_hud) |
| `SkillController_SetTier` | `0x1402edd80` | ✅ ok | ✔ | void(oCDtEntityCpntSkillController* ctrl, int32_t tier) |

## skins

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `SkinGrid_Populate` | `0x1401f16f0` | ✅ ok | ✔ | void(void* ctx, void* arg) |
| `SkinRoster_Build` | `0x1401dd2c0` | ✅ ok |  | Skin-pack roster builder. Selectable-skin count (9) is baked into its loop; a new selec… |
| `g_RosterManager` | `0x141436590` | 📍 va |  | Manager pointer global (relocated by the live image base) walked by the skin-grid popul… |

## stats

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `g_StatReportRoot` | `0x14143cb28` | 📍 va |  | Singleton pointer whose object holds the CACHED hero stats the game reports and display… |

## ui

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `BookController_ResolveSettings` | `0x140307a30` | ✅ ok | ✔ | void(oCDtEntityCpnt3DBookController* self) |
| `BookController_ResolveTabs` | `0x140308cd0` | ✅ ok | ✔ | void(oCDtEntityCpnt3DBookController* self) |
| `HeroSelect_ConfirmBlockReason` | `0x14026dbc0` | ✅ ok |  | int(void* screen) |
| `HeroSelect_ConfirmPressed` | `0x1403e9300` | ✅ ok |  | int(void* screen) |
| `HeroSelect_SetConfirmEnabled` | `0x1403e9500` | ✅ ok |  | void(void* screen, bool enabled) |
| `HeroSelect_ValidateBlockedPtr` | `0x14143cb58` | 📍 va |  | Pointer to the object whose byte at +0x11a8 blocks the Select_Hero_Book_Page 'Validate … |
| `UiButton_InputPoll` | `0x1407d72a0` | ✅ ok | ✔ | void(ButtonUiCpntArray* cpnts) |
| `UiButton_PressCommit` | `0x1406a08a0` | ✅ ok | ✔ | void(oCUINavigableZoneDesc* widget) |
| `UiButton_PressReturnSite` | `0x1407d7382` | ✅ ok |  | (code location, not callable) |
| `UiController_BindComponent` | `0x14034c180` | ❓ unverified |  | void(void* uiController) |
| `UiController_OnHide` | `0x140352b40` | ❓ unverified |  | void(void* uiController) |
| `UiController_OnShow` | `0x140352aa0` | ❓ unverified |  | void(void* uiController) |
| `UiController_UnbindComponent` | `0x14034c200` | ❓ unverified |  | void(void* uiController) |

## world

| name | address | status | callable | signature / note |
|------|---------|--------|----------|------------------|
| `Chapter_Serialize` | `0x1403254d0` | ✅ ok |  | bool(Chapter* this, void* serializer) |
| `GameModeDefaultDef_Serialize` | `0x1403256e0` | ✅ ok |  | bool(GameModeDefaultDefinition* this, void* serializer) |
| `LevelStream_Deserialize` | `0x1404767e0` | ❓ unverified |  | bool(void* loader, void* a_pLevel, void* a_pLvlId, void* a_pLinks) |
| `MapDef_Serialize` | `0x1403233b0` | ✅ ok |  | bool(oCDtMapDefinition* this, void* serializer) |
| `TileKindPool_ReportEmpty` | `0x1403421f0` | ✅ ok | ✔ | void(void* tileSpawnerSettings, void* outMessages) |
| `TileKind_Serialize` | `0x140340fc0` | ✅ ok |  | bool(oCDtTileKind* this, void* serializer) |
| `TileSlotScenarioKindCompat_Serialize` | `0x140341190` | ✅ ok |  | bool(oCDtTileSlotScenarioKindCompatibility* this, void* serializer) |
| `TileSlotSettings_Serialize` | `0x1403411f0` | ✅ ok |  | bool(oCDtTileSlotSettings* this, void* serializer) |
| `TileSlotSize_Serialize` | `0x140341780` | ✅ ok |  | bool(oCDtTileSlotSize* this, void* serializer) |
| `TileSpawn_DistanceConstraints` | `0x140345890` | ✅ ok | ✔ | void(void*, void*) |
| `TileSpawn_PlaceTiles` | `0x140343ad0` | ✅ ok | ✔ | void(void* tileSpawnerComponent) |
| `TileSpawnerSettings_Serialize` | `0x140341b10` | ✅ ok |  | bool(oCDtEntityCpntTileSpawnerSettings* this, void* serializer) |
| `TileSpawner_Spawn` | `0x140343640` | ✅ ok | ✔ | void(void* tileSpawnerComponent) |

---

# 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` |

---

# Bosses

> A boss is a flag-tagged enemy plus a BossTimer controller component — the settings layout, the named-event encounter gates, and the reward hookup.

Source: https://docs.rsmm.me/reverse-engineering/bosses/

:::note
Status: Tier-1 RE backing `src/rsmm/sdk/kinds/bosses.py`, from live Ghidra MCP +
headless decompilation. Items marked *unconfirmed* are inferred, not read from the
binary.
:::

:::tip[What the `boss` kind does today (2026-09-19)]
The shipped kind does not build the BossTimer chain below. It **swaps** which
boss an arena spawns. Measured over the shipped corpus: a den or shrine
boss's own flag (`BossCrab`, `Boss_Marsh_Ghoul`, …) is referenced by exactly
one arena, and the boss entity is referenced by nothing but its definition.
So the arena selects by flag and spawns the definition's `entity_ref`, and
rewriting that one field is the whole swap. Quest bosses, the Jinn and the
witch trio fail that test and are refused. This page remains the map for
the harder goal of a genuinely new encounter.
:::

Per-kind companion to [Mod hooks](/reverse-engineering/mod-hooks/) ("Enemies &
bosses", "level-load pipeline"). Scope: one custom boss encounter — a tagged enemy
with an `oCDtBossTimerUiControllerEntityCpnt` component, wired into the existing
named-event spawn fabric, guaranteed to drop a reward.

## Summary — bosses are tagged enemies with a controller component

1. `oCDtBossTimerUiControllerEntityCpnt` is the runtime component driving the
   boss-fight UI / HP bar. It is **not** in `class_registry.json` — it's a
   component, not a UID-keyed serializable record (same shape as
   `oCDtEntityCpntMagicalObject`).
2. `oCDtBossTimerUiControllerEntityCpntSettings` is the *authored* settings
   container — what asset bytes describe. Its four embedded `oCEntityCpntPicker`
   slots are the fields a level designer fills in.
3. The encounter is gated by `oCGameNamedEvent`s named `BOSS_FIGHTING_START` /
   `BOSS_ACTIVATED` / `BOSS_FIGHTING_STOP` / `BOSS_DEFEATED`. Each string is
   CRC32-keyed at static init into a `_DAT_*` slot; `FUN_14027fde0` is the master
   listener-binder wiring those keys to per-listener thunks.
4. Bosses are otherwise vanilla `oCDtEnemyDefinition` records (UID `0x176debb7`,
   size `0x350`, library `0x1414118c0`) — "is a boss" is a **bit in the enemy's
   `oCCustomFlagList`**, not a separate class. Flag bits are unnamed in the binary
   (`"Flag 0"`.."Flag 63"` are the only labels).

## The chain

```
oCDtEnemyDefinition                       data class (UID 0x176debb7)
    +-- oCCustomFlagList                  tag list — one bit = "is_boss"
    |
    +-- oCDtBossTimerUiControllerEntityCpntSettings   per-encounter cfg
            +-- picker @ +0xf8   target enemy / arena anchor
            +-- picker @ +0x138  intro / cinematic ref
            +-- picker @ +0x250  music cue / FMOD event
            +-- picker @ +0x310  post-kill reward (oCDtRewardDefinition)
            |
            v (resolved at level-load)
        oCDtBossTimerUiControllerEntityCpnt   runtime component (UI + HP bar + timer)
            +-- oCEntitySpawner    embedded at +0x68
            +-- bool signals       at +0x18 (is_active) / +0x38 (ever_activated)
```

Named-event keys: `BOSS_FIGHTING_START` → `_DAT_1412c0430`, `BOSS_ACTIVATED` →
`_DAT_1412bfcb8`, `BOSS_DEFEATED` (string `0x140ef1788`), `BOSS_FIGHTING_STOP`
(string `0x140ef1798`).

:::caution[Rebase note]
The `0x140368xxx` / `0x14147ff74` addresses below are from the pre-rebase corpus
and are stale in the current binary. The core claim was re-verified: the settings
vftable is now `0x140f2da98`, deserialize is slot 3 = `FUN_140374250`, and it reads
exactly `+0xf8`, `+0x138`, `+0x178`, `+0x250` unconditionally plus `+0x290` and
`+0x310` gated on class-version tag `0x17e9a0ae >= 1`. **The offset tables stand;
re-derive the addresses before using them.**
:::

## Runtime component layout

From the ctor + dtor. Mirrors `oCDtEntityCpntHeroSpawner` (same spawner-shaped
pattern).

| Offset | Field |
|---|---|
| `+0x00` | vftable (`oIEntityCpnt` first, then specialized) |
| `+0x08..+0x10` | parent / scene-graph backrefs (0 at ctor) |
| `+0x18` | `EntityCpntValueSignal<bool>` — **is_active** (boss enters fight) |
| `+0x20..+0x30` | signal body (listener list head/tail) |
| `+0x38` | `EntityCpntValueSignal<bool>` — **ever_activated** (first encounter) |
| `+0x40..+0x50` | signal body |
| `+0x64` | low-nibble-masked status byte (`& 0xf0` cleared by ctor) |
| `+0x68` | embedded `oCEntitySpawner` — **what actually creates the boss entity** |
| `+0x70..+0x88` | spawner body; `0xffffffffffffffff` is the unresolved-prefab sentinel |
| `+0x90..+0xb8` | spawner state (parent entity backref, prefab cache) |
| `+0xc0..+0xe8` | controller state — boss-fight HUD / HP bar context *(unconfirmed)* |
| `+0xd8`, `+0xe8` | heap signal-listener pointers; released by the dtor when non-null |
| `+0xe4`, `+0xf4` | ints — phase index / phase count *(unconfirmed; inferred from the dtor's matched pair of refcounted listeners)* |

## Settings layout

The settings struct is the **authoring** record. Each picker is an
`oCEntityCpntPicker` — the same "pick one named resource" primitive items use.

| Offset | Field | Notes |
|---|---|---|
| `+0x00` / `+0x08` | primary / secondary vftable | multiple-inheritance ABI |
| `+0xf8` | **picker 1** | target entity — anchor to attach the boss prefab to |
| `+0x100` / `+0x108` | picker 1 name ptr / hash | `0x80000000` = unresolved |
| `+0x118` | picker 1 resolved `oCMetaClass*` | fixed up by the resolve pass |
| `+0x138` | **picker 2** | intro cinematic / intro entity *(unconfirmed)* |
| `+0x158` | picker 2 resolved meta | |
| `+0x178` | scalar/array slot (no picker vftable) | likely per-phase settings or HP cutoffs *(unconfirmed)* |
| `+0x1b0` | array-tail pointer | resolves to `+0x278` |
| `+0x250` | **picker 3** | music cue, likely over the FMOD event library *(unconfirmed)* |
| `+0x290` | scalar/array slot | possibly the `oCCustomFlagList` of fight tags |
| `+0x2c8` | picker target ptr | resolved-meta sentinel |
| `+0x310` | **picker 4** | reward — the guaranteed-drop `oCDtRewardDefinition` |
| `+0x330` | picker 4 resolved meta | |

Deserialize calls the sub-object reader six times, one per field. The sixth
(`+0x310`) is **gated** on the cooked-asset version-tag test for `0x17e9a0ae`, so
the reward picker is a newer schema addition and may be absent on older records.
**A mod must emit version tag `0x17e9a0ae` for the reward picker to deserialize.**

## How the boss actually appears

There is **no direct factory call** for bosses in the level-load resource loader.
Instead:

1. Stage 3 (*Enemies settings loading*) walks
   `oCTLibrary<oCDtEnemyDefinition>` and filters via
   `EnemyDefInternal::SearchFilter` + `oCCustomFlagFilter`. Survivors join the
   camp pool.
2. Stage 12 (*Generate enemy camps*) fires a named event; camp-spawner components
   instantiate enemies. A boss enemy lands in the pool with the right tag, and the
   camp's `oCDtEnemyFlagListEntitySelectorToSpawnEntityCpntSettings` picks it
   because its `oCCustomFlagList` matches.
3. When the player approaches the arena, the attached controller wakes — its
   `is_active` signal flips, the engine raises `BOSS_FIGHTING_START`, and the
   listener-binder's `MapSceneContext` closure runs.
4. On death `BOSS_DEFEATED` fires and the reward picker at `+0x310` dispatches
   through the reward-selector chain
   ([Rewards](/reverse-engineering/rewards/)).

So the "spawn the boss" hook is not a call — it's the combination of a tagged
enemy definition clearing the stage-3 filter, a controller component attached to
that enemy or its arena anchor, and the existing camp machinery doing the creation
at stage 12. **Modders don't fire any new event**: with the boss tag and the
component, the engine handles the rest.

## What the "boss flag" is, concretely

The engine walks every enemy in the library and tests each against
`oCCustomFlagFilter`; the camp's selector carries its own `oCCustomFlagList`. A
boss is an enemy whose bitfield has the bit the boss-arena camp filter demands.
The exact bit index isn't string-labelled, so in practice: read a vanilla boss's
asset `oCCustomFlagList` bitfield, and copy it onto the custom enemy.

## Insertion recipe

1. **Enemy definition** — clone a vanilla boss `oCDtEnemyDefinition`; set the
   resource path/name, HP/damage scalars, and the `oCCustomFlagList` bits to
   include the boss flag the stage-3 camp filter looks for.
2. **BossTimer settings** — picker `+0xf8` → arena anchor entity name, `+0x138` →
   intro entity, `+0x250` → FMOD music cue, `+0x310` → reward definition, with
   version tag `0x17e9a0ae` in the cooked stream.
3. **Component attach** — at level load a controller must sit on either the boss
   enemy or its arena anchor; it reads its settings through the normal
   entity-component plumbing.
4. **Arena** — the map's camp must include a spawn tag matching the new enemy's
   flag list, or route through a per-map selector patch.

Unknown fields fall back to **clone-from-base**: copy a vanilla boss's bytes
verbatim and patch only the offsets above, carrying a `synthesized: {offset: value}`
map and a `cloned_from` field so the apply layer can audit which bytes are real
schema and which are inherited.

## Harder bosses vs "all moves at once"

- **Harder bosses (HP / damage scaling)** — reachable today. A boss is an enemy
  entity: scale it via the difficulty levers (`Game Difficulty` `0x18700873`,
  `Camp Difficulty Modifier` `0x187aaecf`; see
  [Game modifiers](/reverse-engineering/game-modifiers/)) or per-entity stat
  overrides. A "slider to 1000%" is thin UI over a value multiplier — no RE wall.
- **"All moves at once"** — hard and unmapped. Ability sequencing lives in the
  boss **behaviour tree** plus per-ability controllers (cooldown / windup / phase
  gates), not a scalar. True simultaneity needs BHV-asset surgery or a per-tick
  ability-force-trigger hook, which is engine-AI and MP-determinism sensitive. The
  closest tractable approximation is driving ability **cooldowns** toward zero, if
  they surface as entity-value keys.

---

# Calling game functions

> Invoke any of ~53k game functions by name from a Lua mod.

Source: https://docs.rsmm.me/reverse-engineering/calling-game-functions/

Goal: any reverse-engineered function in `Ravenswatch.exe` is callable
from a mod's `init.lua` by name, without rebuilding the loader and
without baking absolute addresses that break on every game patch.

This document is the user-facing API + the design that backs it.

## Pipeline

```
Ravenswatch.exe                                      data/
  │                                                    │
  │   Ghidra headless analyze                          │
  │   docs/_re/scripts/dump_symbols_strings.py         │
  ▼                                                    │
docs/_re/out/symbols.json (54k function VAs + names)   │
  │                                                    │
  │   scripts/gen_function_patterns.py                 │
  │   (disassembles each prologue, masks               │
  │    relocation-sensitive bytes, extends             │
  │    until pattern is unique-or-indexed)             │
  ▼                                                    │
data/function_patterns.json (53k entries)──────────────┘
  │
  │   shipped alongside winhttp.dll
  ▼
loader DLL → fn_resolver scans .text at runtime
           → fn_call_raw invokes via Win x64 ABI
           → exposed to Lua as rsmm.resolve / rsmm.call
```

## Lua API

```lua
-- 1. Resolve a function by symbolic name (defaults to the FUN_xxx
--    symbol Ghidra assigned, unless a label has been pinned).
local seed_register = rsmm.resolve("FUN_14073df80")
if not seed_register then error("not found — game patched?") end

-- 2. Call it. Signature is "<ret><args>" using single-char type codes:
--    i u l f d p s v   (int32, uint32, int64/ptr, float, double,
--                       void*, c-string, void)
rsmm.call(seed_register, "v l", entity_persistent_data_ptr)

-- 3. Or call by name in one shot:
rsmm.call("FUN_1401c6d60", "v l", game_options_struct)

-- 4. Raw memory access for game globals:
local module = rsmm.module_base()              -- runtime image base
local seed_va = module + 0xf59758              -- m_uRandomSeed string
rsmm.write_u32(seed_va, 42)                    -- override
print(rsmm.read_u32(seed_va))

-- 5. Read a c-string:
local s = rsmm.read_cstr(module + 0xeed8b8)    -- "Forced seed"
```

### Custom-seed example (speedrun use case)

```lua
-- mods/SeedPinner/init.lua
rsmm.on_event("ready", function()
    local SEED = 12345
    -- Game has a built-in "Forced seed" oe::UIntGameOption (id 0x1949b098).
    -- Easiest: find the global option registry and set the u32 field.
    local set_uint = rsmm.resolve("oe_GameOptions_set_uint")  -- alias TBD
    if not set_uint then
        rsmm.log("[SeedPinner] set_uint missing — game version drift")
        return
    end
    local enable = rsmm.resolve("oe_GameOptions_set_bool")
    rsmm.call(set_uint, "v u u", 0x1949b098, SEED)
    rsmm.call(enable,   "v u u", 0x1949b099, 1)       -- flip the enable bool
    rsmm.log(("[SeedPinner] seed forced to %d"):format(SEED))
end)
```

## Type codes

| Code | C type        | Reg slot (x64)            |
|------|---------------|---------------------------|
| `i`  | int32_t       | rcx/rdx/r8/r9 (or stack)  |
| `u`  | uint32_t      | rcx/rdx/r8/r9             |
| `l`  | int64_t       | rcx/rdx/r8/r9             |
| `p`  | void*         | rcx/rdx/r8/r9             |
| `f`  | float         | xmm0..xmm3                |
| `d`  | double        | xmm0..xmm3                |
| `s`  | const char*   | rcx/rdx/r8/r9 (pointer)   |
| `v`  | void          | return-type only          |

Max 8 args. Beyond that you need either a wrapper function recorded as
its own pattern, or libffi which we haven't pulled in.

## How resolution survives game patches

Every entry in `data/function_patterns.json` carries:

```json
{
  "name": "FUN_14073df80",
  "addr": "0x14073df80",          // link-time VA when captured
  "size": 832,
  "pattern": "48 89 5c 24 ?? ...", // first ≥12, up to 128 bytes
  "used_bytes": 64,
  "match_index": 3                 // Nth match in .text scan
}
```

`pattern` is the instruction prologue with relocation-sensitive bytes
(CALL/JMP rel32, RIP-relative leas, MOV mem disp32) replaced by `??`.
What stays in `pattern` is opcodes + register encoding + small
immediates — the *shape* of the instruction stream.

After a game patch:
1. Compiler emits the same source as a similar instruction sequence.
2. Addresses shift; opcode bytes stay.
3. `fn_resolver` scans `.text`, finds the same pattern at a new VA.
4. `match_index` disambiguates when multiple functions share a
   prologue (templated dtors, vtable thunks, tiny wrappers).

Validated on the current build: **>99% of patterns resolve to the
exact recorded VA** under the same exe. Cross-build drift is empirically
~90% — short patterns survive; functions that the optimizer reshuffled
need a regenerated entry. The pipeline is one command:

```sh
./rsmm rebuild-asset-map           # re-runs the Ghidra dumps
python3 scripts/gen_function_patterns.py
```

## Anti-tamper caveat

`rsmm.call` invokes game functions via a normal indirect call, which is
safe. Hooks work too: `rsmm.hook(...)` and the loader's own detours install
through MinHook once the loader has settled. The earlier crashes came from two
specific targets (a `CreateFileW` prologue rewrite under Wine and a D3D
`Present` hook on a Vulkan game), not from an integrity check; see
[Anti-tamper protector](/reverse-engineering/protector/).

A hook target must be a real function entry (the loader checks `.pdata`).
Mod-supplied addresses get a warning rather than a refusal, and the mod author
owns that risk.

## Memory access discipline

`rsmm.write_*` writes process memory directly. There is **no guard**
against writing into:

- `.text`  — would crash or be reverted by AT;
- vtables — corrupts dispatch;
- save data — corrupts player progress.

Treat writes as a sharp tool. Pattern-resolve the field's owner first
(`rsmm.resolve` returns the function that registers it), inspect the
decompile output, then poke. The
`docs/_re/out/decompiled_all/<bucket>/<name>__<addr>.c` files are the
authoritative reference for what each address means.

## Where to look

| Want to know… | Read |
|---|---|
| every function's prototype | `docs/_re/out/symbols.json` |
| what a function does | `docs/_re/out/decompiled_all/.../<name>.c` |
| every string the game uses | `docs/_re/out/strings.json` |
| what calls a given address | `docs/_re/out/xrefs.json` |
| how seed plumbing works | `docs/_re/SEED_MAPGEN.md` |

## Status

- **`rsmm.resolve` / `rsmm.call`** — designed and wired into
  `src/loader/src/script_lua.cpp`. Build the loader (`src/loader/build.sh`)
  and `./rsmm install-loader` to deploy.
- **Pattern database** — 53,427 entries, regen'd from current exe.
- **Aliases** (friendly names instead of `FUN_xxx`) — shipped for the
  subsystems that have been reverse-engineered: they are the named entries in
  `data/symbols.json`. Everything else is still looked up by `FUN_xxx` via
  `symbols.json` and the decompiled C.
- **Hook API** — shipped (`rsmm.hook`, plus the loader's own detours).

---

# Combat & damage

> The hit pipeline — why healing the hero is easy, damaging an enemy is not, and the ride-an-existing-attack mod path.

Source: https://docs.rsmm.me/reverse-engineering/combat-damage/

:::note
Status: RE complete, 2026-06-14, with the hit-data layout corrected 2026-08-15.
Addresses verified live against the shipped `Ravenswatch.exe` (image base
`0x140000000`). The **read** half ships as `R.damage`; the write half (scaling
or redirecting a hit) is documented here but deliberately not implemented.
:::

## TL;DR

`R.shards` (formerly `R.combat`, which was documented as healing) changes the
**hero's dream shards** via `Hero_ModifyDreamShards(hero, delta, tags)` — the
routine was misnamed `Entity_ModifyHealth` until 2026-09-18.
That routine is **hero-only** — it dereferences the HUD HP mirror at `hero+0x1d80`
unconditionally, which enemies do not have, so calling it on an enemy
access-violates.

To damage an **enemy** the engine builds an `oCEntityHitData` and hands it to
`Entity_DispatchHit(target, hit)`. There is **no low-arity "damage entity by N"
call** and **no standalone `oCEntityHitData` constructor** — the struct is built
inline inside the attack resolver. The viable mod path is to **hook the resolver
and amplify/redirect** an attack the hero already makes.

## The two appliers

| Function | Symbol | Role |
|---|---|---|
| `FUN_1406e3ce0` | `Entity_DispatchHit` | LOCAL apply: runs the target's hit handlers. `(oCEntity* target, oCEntityHitData* hit)`. |
| `FUN_1407276a0` | `NamedEvent_EmitNetworkDamageFromHit` | `(attacker, target, hit)`. Applies locally via `Entity_DispatchHit` when the target is not ours or the attack is not replicated; builds and sends `oCGameNamedEventNetworkDamage` only when this machine owns the target **and** the attacker is remote — which is why the event never fires in solo. |

Both consume a fully-built `oCEntityHitData`.

## oCEntityHitData layout (~0xb0 bytes)

vftable `0x140f0e4b8`.

| Offset | Field |
|---|---|
| `+0x00` | vftable |
| `+0x10` | refcounted per-hit **handle** |
| `+0x18..0x90` | float/vector block: positions, normals, direction (defaults from constants `0x140fc6c10`, `0x140fc6c50`, `0x140fc6e70`, `0x140fc7240`) |
| `+0x70` | attacker **context** (its entity at `+0x8`) |
| `+0x88` | u16 flags |
| `+0xa0` | hit-**value** object (f32 damage at `+0x8`) |

:::caution[Layout corrected 2026-08-15]
`+0x10` and `+0xa0` used to be documented as the source and target entities.
They are a per-hit handle and the hit-value object: both producers fill them
from a handle allocator and a value object and release each through its own
destructor. **The target is not stored in the hit data at all** — it is
`Entity_DispatchHit`'s first argument. The stale names reached the Lua bus as
`target_entity` / `instigator_entity` on `gameplay:NETWORK_DAMAGE`, where they
could never match anything; they have been removed.
:::

The damage **amount** is not a plain float here — it lives in the hit-value
object at `+0xa0` (`*(hitval+0x8)` = damage). The resolver's RETURN value is
that same number, which is how `R.damage` reads it without touching the struct.

## The producer: `Entity_ResolveAttackHits` (`FUN_1403dd540`)

```c
float resolve(void* attacker, uint hitDefIndex, TargetList* targets,
              float damageMul, float baseDamage)
```

- `attacker` — hit-def array @ `+0xd8`, entity @ `+0x8`.
- `hitDefIndex` — index into the attacker's hit-def array;
  `attacker[+0xd8 + i*8]` → `vtable[+0x20]()` → the hit-value object.
- `targets` — `{ u32 count @+0x0, oCEntity** @+0x8 }`.
- `damageMul × (baseDamage or the hit-def's value)` → written to `hitval+0x8`.

Per target it allocs a hit handle, stack-builds the `oCEntityHitData` (fully
inlined — no constructor `CALL`), then calls `Entity_DispatchHit(target, hitData)`.

## Why synthesis is impractical

A standalone "deal N damage to enemy E from hero H" would have to fabricate: a
hit-value object with the right vtable, a valid hit handle (alloc + release
lifecycle), the source net-id (host-authoritative replication), the
position/normal block, and correct refcounts on both entity pointers. Any error
corrupts the hit pipeline or desyncs multiplayer.

## Recommended mod path

**Ride an existing attack.** Hook `Entity_ResolveAttackHits` (`FUN_1403dd540`)
read/modify and either scale the hit-value damage (`*(hitval+0x8)`) for a "+X%"
effect, or swap/extend the target list to redirect/widen a hit. This reuses a
real, fully-formed hit the engine already built — no fabrication, netcode-correct.
Engine-mutating, so it runs on the game main thread (see
[loader thread model](/reverse-engineering/mod-hooks/)) behind an env gate until
verified. Not yet implemented.

The **read-only** half of that hook ships today as `R.damage`: it replays the
original with the arguments it received and only reads the returned damage, so
per-player damage attribution needs none of the fabrication above. See
[Authoring mods](/guides/modding/#damage-attribution-rdamage).

## See also

- [Anatomy of an entity](/reverse-engineering/entity-anatomy/) — what an entity is, and the three places a number can live.
- [Entity values](/reverse-engineering/entity-values/) — where combat modifiers live.
- [Event systems](/reverse-engineering/event-systems/) — `NETWORK_DAMAGE` payload decode.
- [Multiplayer](/reverse-engineering/multiplayer/) — why the net-id matters.

---

# Enemies

> The enemy definition layout, the tribe roster that actually drives camp spawns, and why registering in UsedRscList is the entire contract for a custom enemy.

Source: https://docs.rsmm.me/reverse-engineering/enemies/

:::note
Status: load chain closed statically — a loaded enemy def **self-registers** into
its tribe's runtime roster, so the existing apply pipeline is sufficient. Scope is
non-boss `oCDtEnemyDefinition`; bosses share the class but route through the
BossTimer controller ([Bosses](/reverse-engineering/bosses/)).
:::

## Class anchors

| Class | UID | Size | Library | Cooked ext |
|---|---|---|---|---|
| `oCDtEnemyDefinition` | `0x176debb7` | `0x350` | `0x1414118c0` | `*.enemydef.ot` |
| `oCDtEnemyTribeDefinition` | `0x176dc2eb` | `0x2d8` | `0x141411200` | `*.enemytribedef.ot` |
| `oCDtEnemyCampTierDefinition` | `0x176e18f8` | `0x2a0` | `0x141411560` | `*.enemycamptierdef.ot` |
| `oCDtEnemyCampDifficultyDefinition` | — | — | `0x141411710` | — |
| `oCDtEnemyCampEntitySelectorToSpawnEntityCpntSettings` | `0x16b7d175` | ≥ `0x440` | — | — |
| `oCDtEnemyCampEntitySelectorToSpawnTribeEntrySettings` | `0x16b81d80` | — | — | — |
| `oCDtEnemyFlagListEntitySelectorToSpawnEntityCpntSettings` | `0x17019bf9` | — | — | — |

The registrar confirms size `0x350`; the schema-declarer only sets the display
name and extension — the full field schema lives in the deserializer's
UID-versioned reader.

## `oCDtEnemyDefinition` layout

`+0x288` and `+0x2e8` are **0x38-byte typed resource-ref blocks**:

```
{ char* name, u32 hash, char* parentPath, u32 hash2,
  void* classDescriptor @+0x20, u8 resolved @+0x28, void* resolvedPtr @+0x30 }
```

| Offset | Field |
|---|---|
| `+0x000` | vftable chain (`oISerializable → oIResource → oCDtDefinition → oCDtEnemyDefinition`) |
| `+0x008..+0x280` | base-class members (refcount `+0x10`; name/hash `+0x270..+0x284`) |
| `+0x284` | `{u8 flagA=1, u8 flagB=1}` — `oCDtDefinition` flags |
| `+0x288` | **entity ref block** (descriptor default `DAT_14146f740`, override `+0x2a8`, resolved-flag `+0x2b0`, resolved entity `+0x2b8`) |
| `+0x2c0` | `oCCustomFlagList` — vftable here, data `+0x2c8`, count `+0x2d0`, capacity `+0x2d8` |
| `+0x2dc` | `f32` minTier (init `0.1f`) |
| `+0x2e0` / `+0x2e4` | tier range `{min, max}` (init `{0,5}`) |
| `+0x2e8` | **tribe ref block** (tribe class descriptor at `+0x308`, resolved-flag `+0x310`, resolved `oCDtEnemyTribeDefinition*` `+0x318`) |
| `+0x320` | `f32` weightA (init `-1.0f`) — default weight |
| `+0x328` / `+0x330` | tier-weight table A: `{u32 tier, f32 weight}` pairs, 16 B/entry + count |
| `+0x338` | `f32` weightB (init `-1.0f`) — alternate spawn-mode weight |
| `+0x340` / `+0x348` | tier-weight table B + count |

:::caution[Superseded readings]
An earlier pass read `+0x2b8` as a `MaxOccurence` vector and `+0x2b0` as
`isElite`. Both were wrong: `+0x2b8` is the **resolved entity pointer** and
`+0x2b0` its resolved-flag. "Elite" is tag membership in the `oCCustomFlagList`,
not a dedicated bit.
:::

**HP / damage / move speed are not on the enemy def.** They live on the
`oCEntitySettings` referenced by the entity-ref block; the 0x350 budget is spent
on tag lists, tier curves and resource refs. Adjusting stats means editing the
referenced entity.

## Tribe layout

Flag list `+0x288`; **cooked** entry vector `+0x2a0`/`+0x2a8` (resolved by the
tribe post-load; empty in all 25 vanilla tribes); **runtime roster**
`+0x2b8`/`+0x2c0` (zero-init, written only by `EnemyDef_PostLoad`); tier
aggregates `+0x2c8` (min, FLT_MAX init), `+0x2cc` (max, -FLT_MAX), `+0x2d0` (u32
max tier-hi).

## Camp pipeline

```
oCDtEnemyDefinition         ──┐
   (one stat block + tags)    │
                              ▼
oCDtEnemyTribeDefinition (one tribe groups N enemies)
   - +0x288 oCCustomFlagList (tribe-wide tag set)
   - +0x2b8 runtime roster (the actual candidate list)
                              │
                              ▼
oCDtEnemyCampTierDefinition (which tribes show up at this tier, +0x290)
                              │
                              ▼
oCDtEnemyCampDifficultyDefinition (curves multipliers per tier)
                              │
                              ▼
oCDtEnemyCampEntitySelectorToSpawnEntityCpntSettings (UID 0x16b7d175)
   - +0x0f8 oCCustomFlagFilter A  (must-have / must-not-have tags)
   - +0x400 oCCustomFlagFilter B  (second pass, elite override?)
   - several oCResourceRef + float weights (10.0f, 20.0f, 1.0f)
```

The two filter slots explain how one camp expresses "normal-enemy filter + elite
filter" without a separate class. A custom enemy needs its tag list to match
**filter A** of the camps it should appear in, and to stay clear of **filter B**'s
negative list.

## The stage-3 filter

Invoked at level-load stage 3 ("Enemies settings loading"), it walks the candidate
vector and **removes** entries failing any of:

1. The resolved-flag/exclude check when the request is a special-spawn pass.
2. Tier check: `request_tier ∈ [tier_lo, tier_hi]`.
3. Minimum tier float: `enemy.minTier <= request_tier_float`.
4. Tag include/exclude against a locally built `EnemyDefInternal::SearchFilter`
   (set-intersection non-empty / empty helpers).
5. Tribe whitelist: if the tribe resolved-flag is 0 skip; else the resolved tribe
   pointer must be in the request's accept list.
6. Weight derivation: pick the largest `(tier, weight)` pair whose `tier <=
   request_tier` from table A (default pass) or table B (special pass); a
   resulting weight of `0.0` drops the entry.

This is the **only** filter between a registered enemy def and a camp roster.
There is no separate opt-in list.

## The candidate list is the tribe roster

The camp tier selector builds the candidate vector directly from the tribe's
roster, then hands it to the stage-3 filter:

```c
// tribe entry -> oCDtEnemyTribeDefinition*
FUN_1401c2fd0(&cand, tribe[+0x2b8], tribe_count[+0x2c0]); // candidates FROM tribe roster
FUN_1403194c0(&cand, &search_filter);                     // stage-3 trims by tier/tag/weight
```

Two consequences:

1. The stage-3 filter only **trims** what the roster holds — flags and tiers never
   *add* an enemy. Selection is tribe-roster-driven, not "flag-list selector by
   tag".
2. The roster at `+0x2b8` is **runtime-populated**, not read from the cooked tribe
   file. The cooked tribe's own entry vector deserializes to `+0x2a0` and ships
   `count == 0` in all 25 vanilla tribes — if `+0x2b8` were that vector, no enemy
   would ever spawn. **Patching the cooked tribe is useless** (wrong vector).

## The roster writer — enemies self-register

`EnemyDef_PostLoad` is the `oCDtEnemyDefinition` vftable slot at `+0x90`
(post-deserialize callback). It:

1. Resolves the tribe ref block via the generic `ResourceRef_Resolve` when the
   resolved-flag is 0, writing the live tribe pointer to `+0x318`. Resolution
   **loads the tribe def on demand** — tribes are excluded from the boot
   definitions scan.
2. If the tribe is loaded and valid, **push_backs self onto `tribe+0x2b8`/`+0x2c0`**
   — *the only roster write in the binary* — and folds the tier aggregates into
   `tribe+0x2c8`/`+0x2cc`/`+0x2d0`.
3. Registers the instance in the per-class registry via `Registry_RegisterInstance`;
   registries are enumerated by every selector.

What loads enemy defs at all is `InitialLoading_LoadAllDefinitions` (boot stage
"InitialLoading - Load all definitions"): it loads
`Versions/LiveOps5.versiondef.ot` first, then **directory-scans the `Definitions`
folder of the resource filesystem** (whose index is `UsedRscList.ot`) and creates
a load job for every definition file except 7 excluded classes. The tribe class is
excluded (lazy load); the enemy class is not.

:::tip[Contract for the apply step]
Registration in `UsedRscList.ot` — which `apply_mods.sync_usedrsclist` already
does with a 3-line record — is the **entire** contract. Boot scan → deserialize →
`EnemyDef_PostLoad` → tribe roster → camp tier selector candidate.
:::

The in-level spawner path (`Enemy_RuntimeSpawnPicker`) enumerates the **class
registry** rather than the tribe roster, filtered by an allowed-tribe pointer
list — so the registry registration in step 3 matters for both paths.

## Authoring recipe

1. Author an `oCDtEnemyDefinition` cooked record: name, entity ref (clone a
   vanilla enemy's entity if nothing custom), min tier, tier range, a
   `oCCustomFlagList` carrying the same tags as the vanilla enemy you want to sit
   beside, tribe ref pointing at the target tribe, and a sane tier-weight table.
2. Register it in `UsedRscList.ot` — nothing else.
3. Optional text-bank override for the visible name, namespaced
   `RSMM_<modid>_<id>_name`. The text key lives on the visual entity, so a custom
   name means cloning that entity and repointing its name key.

A historical custom enemy that never spawned had two confounds — a rewritten
`tribe_ref` and a spawn weight of `9999`. The SDK now guards both
(unknown-tribe reject, `SPAWN_WEIGHT_MAX`, cross-tribe warning).

## Open

- AI profile reference — likely another resource-ref slot; confirm by diffing two
  vanilla enemy defs.
- `oCResourcePath` byte layout: find-by-name uses `{char* name, u32 name_hash,
  char* parent_path}`, but the hash algorithm isn't confirmed.
- Tag string vocabulary — vanilla tag names need a string-pool scan to enumerate.

## See also

- [Anatomy of an entity](/reverse-engineering/entity-anatomy/) — what an entity is, and the three places a number can live.

---

# Anatomy of an entity

> What an entity is in Ravenswatch, what it owns, and the three different places a number like health, damage or armour can actually live.

Source: https://docs.rsmm.me/reverse-engineering/entity-anatomy/

:::note
Status: assembled from symbols that are individually proven — several in game
(the health chain, the hit resolver, the entity-value store, the component
lookup). Every offset here is quoted from `data/symbols.json`; where a reading
is static-only or disputed it says so inline.
:::

Every other page in this section describes one system. This one describes the
thing all of them hang off: the **entity**. Read it first if you have ever
wondered why `R.hp` and `R.stat` reach into completely different places, or why
a stat you successfully changed still displayed as `0`.

## Everything in the world is an entity

A hero, a gnoll, a barrel, a shrine, a dropped item and the boss are all the
same C++ class: `oCEntity` — class id `0x05146457`, `0x640` bytes.

What is surprising the first time you look at one is how **little** an entity
holds. There is no health field on it, no damage, no name, no faction. It owns
a transform, a few links to the world around it, and a bag of components:

| Offset | What it is |
|---|---|
| `+0x08` | owner / back-pointer used by components (`component+0x08` is the owning entity) |
| `+0x28` | the **definition** it was built from — the template, see below |
| `+0x30` | the scene it belongs to |
| `+0x38` | the spawner that placed it |
| `+0x208` | the on-spawned functor copied from its spawn data |
| `+0x324` | position (rotation and scale follow) |
| `+0x500` | the event pool its components register listeners on |
| `+0x5e8` / `+0x5f0` / `+0x600` | the **component map** — control bytes, slots, mask |

Everything a thing in Ravenswatch can *do* is a component in that map. An
entity with a `HitPoint` component can be killed; one without it cannot be
damaged at all, no matter what the attack does.

## Definition versus instance

Mods almost never touch a live entity. They edit the **definition** — the
authored, cooked template — and let the engine build instances from it.

```mermaid
flowchart LR
  A["Cooked file<br/>(enemydef, entity, herodef)"] --> B["oCEntitySettings<br/>the template<br/>0x1e8 bytes"]
  B --> C["EntityStore_CreateEntity"]
  C --> D["oCEntity instance<br/>template kept at +0x28"]
  D --> E["components activate"]
```

`EntityStore_CreateEntity` (`FUN_1406f5dc0`) is the one spawn primitive, proven
in game on 2026-09-13: give it a spawner, a template and a spawn-data record
and it returns a live entity that the engine then treats as its own. `R.spawn`
is built directly on it.

This split is why [Enemies](/reverse-engineering/enemies/) notes that **HP,
damage and move speed are not on the enemy definition**: `oCDtEnemyDefinition`
spends its `0x350` bytes on tags, tier curves and resource references, and the
actual stat block lives on the `oCEntitySettings` it points at. Change the
numbers by editing the referenced entity, not the enemydef.

## The component model

There are **188 component classes** in the shipped registry
(`data/class_ids.json`, mined by `tools/mine_class_ids.py`). They follow a
naming convention that is worth learning, because it tells you where a value
lives before you open a disassembler:

| Suffix | Count | Meaning |
|---|---|---|
| *(none)* | 188 | the live component — runtime state |
| `…Settings` | 176 | the **authored** data it is built from — this is what a mod edits |
| `…NetworkData` | 17 | the slice that replicates to other players |
| `…PersistentData` | 14 | the slice that survives a chapter transition |

So `oCEntityCpntHitPoint` is the live health component, `…HitPointSettings` is
the starting values a designer typed in, and `…HitPointPersistentData` is what
carries across a chapter. When you are hunting for "where is the note count
stored", the `PersistentData` list is only 14 entries long and is the right
place to look first.

The components that matter most:

| Component | Class id | Size | Role |
|---|---|---|---|
| `oCEntityCpntHitPoint` | `0x0fdffbf9` | `0x238` | current and max health. **Every damageable entity has one, enemies included.** |
| `oCDtEntityCpntCharacterController` | `0x1560fd89` | `0xba0` | the hub: links to the HitPoint component *and* to the entity-value store |
| `oCDtEntityCpntHeroController` | `0x155aac59` | `0x1e48` | the hero brain — abilities, dream shards, HUD, per-hit log |
| `oCDtEntityCpntEnemyController` | `0x1561073c` | `0x118` | the enemy counterpart, and how `R.damage` tells an enemy from a prop |
| `oCDtEntityCpntHittable` | `0x15596096` | `0x2b0` | the receiving half of the hit pipeline |
| `oCEntityCpntNetwork` | — | — | replication identity (RakNet under the hood) |

### Finding a component

The engine never reads a component from a fixed offset. It asks the class:

- `Entity_GetComponentFast` (`FUN_1406e31a0`) — resolve through the type→index
  hash map, then confirm with a virtual `IsKindOf`. Needs the 32-bit class key.
- `Entity_GetComponentByTester` (`FUN_1406e3210`) — linear scan, confirming each
  candidate against a type tester. Use this when the key is unknown.

:::caution[There is no fixed slot per component type]
Session 7068 chased `entity+0x678` / `entity+0xad8` chains and they were heap
coincidence — that conclusion still stands and is recorded in
[RE notes](/reverse-engineering/notes/). Never seed a chain to a component.

Two layouts get confused here. The plain array at `+0x190` with its count at
`+0x198` belongs to `oCEntitySpawnerGo`, **not** to `oCEntity`; reading it on a
plain entity yields garbage or an unrelated vector that looks plausible, which
cost a playtest on 2026-08-17. An `oCEntity`'s components are in the map at
`+0x5e8`/`+0x5f0`/`+0x600`, keyed by class id. `R.entity.components()` reads the
`+0x190` form and guards every step (pointer plausibility, a bounded count, and
a vftable slot that must literally be `mov eax, imm32; ret`), so it fails closed
rather than inventing components — but it is the spawner-go shape, and that is
why it can return `nil` on something that plainly has components.
:::

## Where a number actually lives

This is the part that catches everyone. There is no single "stat block". A
gameplay quantity lives in one of **three** places, and they are updated at
different times by different code.

```mermaid
flowchart TD
  D["definition<br/>(authored base values)"] --> S
  M["modifiers<br/>(items, talents, melodies)"] --> S
  S["2 · entity-value store<br/>keyed, folded on recompute"] --> P
  P["1 · plain field on a component<br/>the hot path the game reads"] --> C
  C["3 · display cache<br/>what the UI prints"]
```

**1 — A plain field on a component.** The hot path. Health is a float at
`hitpoint+0xe8` with its maximum at `+0xec`. Dream shards are a float at
`heroController+0x15c8`. These are read every frame by gameplay code, so they
are plain, unkeyed and fast. A mod reads and writes them through `R.hp` and
`R.shards`.

**2 — The entity-value store.** Almost everything else: attack power, cooldown
reduction, status-effect stacks, the hundreds of item and talent effects. Each
value is addressed by a 32-bit key, and the stored number is *computed*:
`EntityValueStore_Recompute` seeds each key from the definition's base value and
then folds in every registered modifier in priority order. See
[Entity values](/reverse-engineering/entity-values/) for the layout and
[Stats & XP](/reverse-engineering/stats/) for the 221-key catalog.

:::caution[A raw poke into the store does not stick]
Writing a value straight into the override cache works right up until the next
recompute, which any gameplay event can trigger — and the recompute rebuilds
that entry from base + modifiers and discards your write. A durable change has
to **be** a modifier. That is why `R.stat.modify` dispatches the game's own
`ADD_MODIFIER` event on the hero's bus rather than poking memory.
:::

**3 — A display cache.** The in-run stat strip does **not** read the store. It
reads three floats out of a cached report object, refreshed only when the engine
folds a modifier. This is exactly why a working attack-power change once showed
`0` on the strip: the store had the new number, the damage code used it, and the
cache nobody had refreshed still held the old one. `R.stat.cached` reads that
cache so a mod can see what the player sees.

Which to use:

| Quantity | Lives in | Read / write it with |
|---|---|---|
| Health, max health | HitPoint component | `R.hp.get` / `set` / `heal` / `damage` |
| Dream shards | hero controller field | `R.shards.get` / `add` / `spend` |
| Attack power, cooldowns, ~200 more | entity-value store | `R.stat.get` / `R.stat.modify` |
| Status stacks (ignite, chilled, …) | entity-value store | `R.stat` with a `status_*` key |
| Armour | **nowhere addressable** | not exposed — see below |
| What the stat strip prints | display cache | `R.stat.cached` |
| Experience | XP component | `R.xp` |

:::note[Armour is the exception that proves the rule]
Armour is registered into the value store with **key `0`**. It has a display
name and an editor icon, but no id, so nothing can address it — no `R.stat` call
can ever read or write it. Its live value is a plain field. The five armour
*effects* ("Armour per missing health" and friends) are keyed normally and work.
Full detail in [Stats & XP](/reverse-engineering/stats/).
:::

## Health

The chain, measured in game on 2026-09-18:

```text
heroController + 0x2f8   -> oCDtEntityCpntCharacterController
             ... + 0x78  -> oCEntityCpntHitPoint
             ... + 0xe8  = current HP (f32)
             ... + 0xec  = max HP (f32)
             ... + 0x08  = the owning oCEntity
```

Note that `+0x2f8` is the *character controller*, not the entity — and the same
object carries the entity-value store at `+0x4c8`. One hop serves both systems.

`HitPoint_SetHitPoints` (`FUN_140822db0`) is the real setter, and it does more
than store a float: it clamps to `[0, max]`, fires the death listeners at
`+0x108` when the value crosses zero, fires the change listeners at `+0xf0`,
replicates through the entity's net component, and writes current and max into
the UI bar. Thirteen gameplay readers take exactly this path and compute
`+0xe8 / +0xec` as a fraction — "increase damage at critical health" is one of
them.

`R.hp` re-checks the link on every access: the RTTI of the component must name a
HitPoint class, and `component+0x08` must equal the hero's entity. `R.hp.diagnose`
prints the whole walk with class names when something looks wrong.

:::caution[Health is host-authoritative]
In co-op the host owns HP. A client-side write is expected to be overwritten, or
to replicate only from the host. See [Multiplayer](/reverse-engineering/multiplayer/).
:::

## Damage

Damage is not a number you set. It is a **hit object** that travels a pipeline:

```mermaid
flowchart LR
  A["attacker acts"] --> B["Entity_ResolveAttackHits<br/>builds oCEntityHitData inline"]
  B --> C["Entity_DispatchHit(target, hit)"]
  C --> D["target's Hittable component"]
  D --> E["HitPoint_SetHitPoints"]
  E --> F["listeners + replication + UI"]
```

The amount is not a plain float on the hit: it lives in a hit-**value** object
hanging off `hitData+0xa0`, as a float at `+0x08`. The resolver returns that
same number, which is how `R.damage` reads every hit without touching the
struct at all.

There is **no** low-arity "deal N damage to entity E" function, and no
standalone constructor for the hit data — the struct is built inline inside the
resolver. Fabricating one means inventing a hit-value object with the right
vtable, a valid refcounted handle, the source net id, and the position/normal
block; any mistake corrupts the pipeline or desyncs multiplayer. The path that
works is to **ride an attack the hero already made**. The read-only half of that
ships today as `R.damage`. Full detail, including the corrected layout, is in
[Combat & damage](/reverse-engineering/combat-damage/).

## Heroes versus enemies

They are the same class with different components. What actually differs:

| | Hero | Enemy |
|---|---|---|
| Controller | `HeroController` (`0x1e48` bytes) | `EnemyController` (`0x118` bytes) |
| Health | HitPoint component | HitPoint component — **the same one** |
| Entity values | full store, hundreds of keys | store present, far fewer keys |
| HUD mirror | `+0x1d80`, **local player only** | none |
| "Is this me" | byte at `+0x1d88` | n/a |
| Damage accounting | `HeroStats_OnDamageDealt` / `…Taken` | n/a |
| Authored by | `oCDtHeroDefinition` (no class UID — [Heroes](/reverse-engineering/heroes/)) | `oCDtEnemyDefinition` + tribe + tier |

The HUD mirror at `+0x1d80` is the single most useful discriminator in the whole
engine: only the local player's hero controller has one, so its presence is how
the SDK decides "this is the hero *I* am playing" rather than an ally or a
remote player.

The asymmetry in damage accounting is netcode, not an oversight.
`HeroStats_OnDamageDealt` fires for **every** hero in the session, local or
remote, which is what makes a co-op damage meter possible without touching the
netcode. `…OnDamageTaken` does not: a hit on an ally is applied on that ally's
machine, so a remote player's "taken" is always zero locally.

## Inspecting a live entity

You do not need Ghidra to answer "what is this thing". From a mod, on the main
thread:

```lua
local e = R.entity.hero()          -- the hero controller, once captured
R.log(R.rtti.name(e))              -- class name straight from RTTI

R.log(R.hp.diagnose())             -- the whole health walk, with class names
R.log(R.hp.get(), R.hp.max(), R.hp.frac())

for _, c in ipairs(R.entity.components(e) or {}) do
  R.log(("%x  %s"):format(c.type_id or 0, R.rtti.name(c.ptr)))
end

R.log(R.stat.get("attack_power"))  -- from the value store
R.log(R.stat.cached("attack_power"))  -- what the strip prints
```

`R.debug.dump(ptr)` prints a window of an object with pointers, floats and
strings identified; `R.debug.find_arrays(obj)` and `R.debug.strings(obj)` turn
what used to be a multi-launch struct hunt into one launch. `R.defs.classes()`
enumerates every loaded definition class.

For "who wrote this byte", `R.watch.on(va, {len=4})` arms a hardware watchpoint
and `R.watch.report()` names the writer — four slots in the whole CPU, per
thread, and the address must be aligned to its length. It needs
`RSMM_ENABLE_WATCH=1` and is a debug tool only.

:::caution[Reading is free, calling is not]
Native `read_*` is page-guarded: a bad read returns `nil` and cannot fault the
game. The moment a probed pointer becomes a **call argument**, the engine owns
the dereference and a wrong pointer is a crash. Validate with `R.ptr.*` and
prefer `R.engine.call_safe`. `Entity_GetNetId` is specifically banned from the
SDK for this reason — it walks the component map with no guard of its own, and
an entity whose slot holds the `-1` sentinel is an access violation rather than
a `nil` return.
:::

## Traps worth knowing before you start

- **`heroController+0x15c8` is dream shards, not HP.** It was documented as
  health until 2026-09-18 and the misreading reached a shipped symbol name. Real
  health is the HitPoint chain above.
- **The stat strip reads a cache.** A store write that the game honours can still
  print as `0`. Check with `R.stat.cached`.
- **A store poke is transient.** Durable changes must be modifiers.
- **`+0x190` is the spawner-go component array**, not the entity's.
- **Armour is unaddressable** (key `0`). Use the armour effects instead.
- **The definition, not the instance,** is what a mod should be editing in almost
  every case.

## See also

- [Entity values](/reverse-engineering/entity-values/) — the keyed store's read path and layout.
- [Stats & XP](/reverse-engineering/stats/) — the 221-key catalog, delivery routes, the strip cache.
- [Combat & damage](/reverse-engineering/combat-damage/) — the hit pipeline in full.
- [Enemies](/reverse-engineering/enemies/) — definitions, tribes and camp spawning.
- [Heroes](/reverse-engineering/heroes/) — why a hero definition is the hardest kind.
- [Spawn system](/reverse-engineering/spawn-system/) — creating an entity at runtime.
- [Event systems](/reverse-engineering/event-systems/) — the bus that component changes fire on.

---

# Entity values

> The engine's generic CRC-keyed per-entity value store — where most dynamic stats and modifiers live.

Source: https://docs.rsmm.me/reverse-engineering/entity-values/

:::note
Status: read path fully mapped 2026-06-14 and shipping since; the write path was
mapped later and is **not** what this page originally assumed — see
[The mod-facing API](#the-mod-facing-api). Addresses verified live against the
shipped `Ravenswatch.exe` (image base `0x140000000`).
:::

## What it is

A few quantities sit at plain fixed offsets: health on the HitPoint component,
dream shards at `heroController+0x15c8`. See
[Anatomy of an entity](/reverse-engineering/entity-anatomy/) for which is which.

Everything else dynamic and per-entity — combat modifiers, "dream shards on
damage", run meta, scaling coefficients — lives in a generic **keyed value
store**, and there are hundreds of them. Each value is addressed
by a 32-bit key (same id space as gameplay-bus event ids). This is the engine's
`oCEntityValue` system, and it is the read surface a mod uses to inspect any
named value.

## Read path

```text
valueCtx = *(hero + 0x2f8)          # the entity's value context
store    = *(valueCtx + 0x4c8)      # the value map (0 => no values)
EntityValue_Lookup(store, &out, crcKey)   # out is a ~0x20-byte union
```

`EntityValue_Get` (`FUN_1403c7fa0`) wraps the `+0x4c8` deref;
`EntityValue_Lookup` (`FUN_140749260`) is the core lookup:

1. Linear scan of an **override array** — `store+0xc0`, count at `store+0xc8`,
   0x38-byte entries, key = int at `entry+0x0`. Holds runtime-modified values.
2. Fallback **hash map** at `store+0x80` (Fibonacci hash, multiplier
   `0xde5fb9d2630458e9`) — the base/default values from the definition.
3. Miss → the union is initialised to value `0`.

## oCEntityValueUnion (~0x20 bytes)

vftable `0x140f8fed8` (base `oISerializable::vftable` `0x140efed08`).

```text
+0x00  vftable
+0x08  type tag   (4 = value stored inline at +0x10)
+0x10  value      (inline f32 when tag==4; else (tag & ~1) is a pointer to it)
+0x18  u16 = 0x000a
```

Engine read pattern (e.g. in `Hero_ModifyDreamShards`):

```c
EntityValue_Lookup(store, &out, key);
float* p = (float*)(out + 0x10);
if (*(uint64_t*)(out + 8) != 4) p = (float*)(*(uint64_t*)(out + 8) & ~1ull);
float value = *p;
FUN_14082ca50(&out);   // destruct the union
```

## Keys are sequential ids, NOT name hashes

`crcKey` is a 32-bit value id. Observed: `0x173900d4`, `0x173900d6`,
`0x188831a6`, `0x12e831f3`/`0x12e831f4`, `0x171c27b5`. Two proofs they are
**structured ids, not hashes of the value name**:

1. **Adjacency** — `0x12e831f3`/`0x12e831f4` differ by 1; `0x173900d4`/`0x173900d6`
   by 2. Independent CRC32 hashes could never land on consecutive integers.
2. **Computed base+index** (decisive) — `Hero_GrantMagicalObject` reads
   `EntityValue_Lookup(store, &out, rarityIdx + 0x1a19e789)` where `rarityIdx` is
   0..5. The key is literally a base id plus an index.

So a mod **cannot** compute a value key by hashing a name — the key must come
from the value's definition (a GUID/id) or be discovered empirically (observe the
immediate the engine routine uses).

For contrast, the engine's string→id hash *does* exist and **is** plain CRC32 —
`Id_HashString` (`FUN_14033f7a0`) = `crc32_pair(0, crc32(name))`, poly
`0x04C11DB7`. But that scheme is for **named events / interned name ids**, not
these value keys.

## The mod-facing API

Both halves ship now. `R.entity.value(name)` and `R.stat.get` take the read path
above: resolve `EntityValue_Lookup` by pattern, take a **numeric** key, allocate
a zeroed ~0x20-byte scratch for `out`, call the lookup, read per the union
layout, then destruct.

The **write** path turned out not to be the override array. Poking a value into
`store+0xc0` works only until the next `EntityValueStore_Recompute`, which
rebuilds every entry from the definition's base value plus the registered
modifiers and discards the poke. A durable write therefore has to *be* a
modifier, and the reliable way to register one is the game's own: `R.stat.modify`
dispatches an `ADD_MODIFIER` named event on the hero's bus, which applies once,
refreshes the display cache and survives a chapter change. See
[Stats & XP](/reverse-engineering/stats/#making-a-write-durable) for the routes and
their trade-offs, and for the mined catalog of 221 keys.

## See also

- [Anatomy of an entity](/reverse-engineering/entity-anatomy/) — how this store relates to components and plain fields.
- [Stats & XP](/reverse-engineering/stats/) — the key catalog and the write routes.
- [Combat & damage](/reverse-engineering/combat-damage/) — `Hero_ModifyDreamShards` reads this store.

---

# Event systems

> The two distinct event systems — the analytics firehose and the oCGameNamedEvent gameplay bus — and how the loader bridges both to Lua.

Source: https://docs.rsmm.me/reverse-engineering/event-systems/

:::note
Status: Tier-1 RE backing `hook_events.cpp`. The gameplay bus is **proven live**
under Proton (4200+ events, 82 distinct names captured); the analytics firehose
is string-verified. Image base `0x140000000`.
:::

## Two event systems

Ravenswatch has **two** independent event systems. Do not conflate them.

| | Analytics firehose | oCGameNamedEvent bus |
|---|---|---|
| Sink / hook | `Analytics_SubmitNamedEvent` `FUN_1401fa470` | `NamedEvent_Dispatch` `FUN_14066a700` |
| Payload | analytics key/value JSON | live entity handles + typed fields |
| Timing | **after** the action | **at** the action (subscribers run inline) |
| Lua event | `R.on("<name>")` | `R.on("gameplay:<NAME>")` |
| Use | "when X happens, do Y" triggers | mutate the actor, read damage, give items |
| Env gate | on by default (`RSMM_DISABLE_GAME_EVENTS=1` to turn off) | on by default (`RSMM_DISABLE_GAMEPLAY_EVENTS=1` to turn off) |

## Analytics firehose

All lowercase snake_case analytics events funnel through one central sink,
`Analytics_SubmitNamedEvent` (`FUN_1401fa470`) — ~37 callers build a KV payload
and submit it as JSON to Passtech's backend. The event name is `arg3`, a
`StringDesc { const char* ptr @+0; u32 len|0x80000000 @+8 }`.

`install_analytics_firehose()` detours that single sink, reads the name, and
emits it to Lua — so **one hook exposes every named event**, and any name a patch
adds shows up automatically. Confirmed names: `game_start` `run_start` `run_end`
`chapter_end` `level_up_reach` `enemy_killed` `unlock_skill` `unlock_hero` …

**Observation-grade, not a gameplay bus** — fires after the action and carries
analytics KV, not a live entity handle. Perfect for triggers, useless for
mutating the actor.

## oCGameNamedEvent gameplay bus

Each entity that wants events owns a **NamedEventDispatcher** sub-object — for a
hero it lives at `entity + 0x4d8`; the world has one at `world + 0x340`.

```text
dispatcher + 0x00..0x18   pending-dispatch queue (intrusive)
dispatcher + 0x28         channel map (SwissTable: id -> channel node)
```

A **channel node** (one per interned event id, 0x20 bytes): `+0x00` id,
`+0x08` subscriber array, `+0x10` count, `+0x14` cap. A **subscription**:
`+0x00` owner entity, `+0x10` handler functor (invoked `(*handler)(ev, sub)`).

### Event object header (every subclass)

```text
ev + 0x00   vftable     (oCGameNamedEvent -> ...Network -> concrete subclass)
ev + 0x08   u32 = 2     (type tag)
ev + 0x20   const char* PLAINTEXT name, e.g. "GIVE_MAGICAL_OBJECT"
ev + 0x30   u32         interned event id (THE channel key)
ev + 0x38   u64         owning-peer/session id (network leg stamps this)
```

Because the plaintext name sits at `ev+0x20`, the loader needs **no per-event
table** and survives the game adding event names. Interned ids are
`crc32_reflected(name)` via `NamedEvent_Id_FromCrc` (`FUN_14051e0e0`).

### The hook point — `NamedEvent_Dispatch` (`FUN_14066a700`)

```c
void NamedEvent_Dispatch(void* dispatcher, oCGameNamedEvent* ev)
```

Clones the event, enqueues it, drains the queue — per event, finds the channel
node by `ev->id`, iterates subscribers invoking `(*(sub+0x10))(ev, sub)`, then
deletes the clone. **One detour here exposes every entity-context gameplay event.**
The loader forwards the original first, reads name@`+0x20` and id@`+0x30`, decodes
verified payloads, and publishes `gameplay:<NAME>`.

## Verified payloads

### GIVE_MAGICAL_OBJECT (size 0x60) — ctor `FUN_14030f430`

```text
+0x20  name "GIVE_MAGICAL_OBJECT"   +0x30 interned id   +0x38 peer = -1
+0x50  u64 MO definition GUID lo    (from MagicalObjectDefinition+0x88)
+0x58  u64 MO definition GUID hi
```

### NETWORK_DAMAGE (size 0x110) — emitter `FUN_140726610`

```text
+0x40  f32 damage value      +0x48 u64 source net-id
+0x50  oCEntityHitData embedded (+0x60 target, +0x100 instigator)
```

## Give-item recipe (proven in-game 2026-06-12)

Any currently-loaded item's identity GUID is just `def+0x88`/`+0x90` of a
`g_MagicalObjectPool` source-array entry — read it live, no file parsing:

```lua
-- g_MagicalObjectPool @ 0x1414365d0; *ptr = {src[] @+0, u32 srcN @+8}
local pool = I.module_base() + (0x1414365d0 - 0x140000000)
local def  = I.read_u64(I.read_u64(I.read_u64(pool)))   -- source slot 0
local lo, hi = I.read_u64(def + 0x88), I.read_u64(def + 0x90)
local ev = R.engine.call("NamedEvent_GiveMagicalObject_Ctor", I.scratch(0x60))
I.poke(ev + 0x50, lo, 8); I.poke(ev + 0x58, hi, 8)
R.engine.call("NamedEvent_Dispatch", hero_dispatcher, ev)
```

The item is granted **directly to inventory** (no world orb). This is wrapped in
the SDK as **`R.give`** (`R.give.random()` / `.by_index(0)` / `.by_guid(lo,hi)`),
which auto-captures the hero dispatcher from any hero-anchored event.

:::note[Solo vs network]
`GIVE_MAGICAL_OBJECT` and `NETWORK_DAMAGE` never fire in solo play (item-grant and
damage are direct calls there) — they only fire on the network-replication path
or our own emit. The hero's handlers are still subscribed, so *emitting* them from
Lua is the give-item lever regardless.
:::

## See also

- [Pickable talents](/reverse-engineering/pickable-talents/) — rides `POWER_UP_COLLECT_REQUEST`.
- [Combat & damage](/reverse-engineering/combat-damage/) — the `NETWORK_DAMAGE` hit-data.
- [Mod hooks](/reverse-engineering/mod-hooks/) — loader detour + thread model.

---

# Game modifiers

> The run mutators ("negative modes") — where their state lives, which keys drive difficulty and XP, and why the 5-slot selection cap is not in the spawner data.

Source: https://docs.rsmm.me/reverse-engineering/game-modifiers/

:::note
Status: definition + state layers mapped; `modifier` SDK kind and the read-only
`R.modifier` Lua API ship today. Class `oe::dt::GameModifierDefinition`, asset
glob `*.gamemodifierdef.ot`.
:::

The toggleable run mutators the game calls **GameModifiers** — the New Game Plus
checkboxes (*No boss timer*, *No minimap*, *Day only*, *More experience*, …).

## Three layers

| Layer | What | Status |
|-------|------|--------|
| **Definition asset** | `.gamemodifierdef.ot`, loaded by the typed `oCTLibrary<GameModifierDefinition>` singleton | Additive — same dir-scan + `UsedRscList` path as enemy defs. A new def file registers automatically. |
| **State slot** | a CRC-keyed boolean per modifier in the generic entity-value store (on = active this run) | Mapped (keys below) |
| **Behavior** | what the modifier DOES is hardcoded C++ branching on the state key | Per-modifier. New behavior needs a Lua hook gated on the key, exactly like talents/items. |

## Key functions

- **`GameModifierDef_RegisterAssetLoader`** `FUN_1403257b0` — registers the
  `*.gamemodifierdef.ot` glob → library loader (label "Game modifier definition"),
  via the generic glob-register `FUN_1404a2190`. This is what proves defs are
  file-additive.
- **`EntityValueRegistry_RegisterAll`** `FUN_1401d9b70` — registers every CRC-keyed
  game-state value (difficulty, modifiers, multiplayer, location flags) with its
  label + type. Source of the key table below.
- **`HasGameModifierStateMachine` registrar** `FUN_140197170` — the per-run
  state-machine component (id `0x1b49a36c`) holding which modifiers are on.
- **`Library_GameModifierDefinition_vftable`** `0x141411b50`.

## State keys (CRC32 of the label)

Read these through the entity-value store — see
[Entity values](/reverse-engineering/entity-values/).

### Toggles (bool)

| Modifier | Key |
|----------|-----|
| No boss timer | `0x1a7945fc` |
| Less day/night half cycle | `0x1a77d42d` |
| More experience (any source) | `0x1a77e2e4` |
| No revive token | `0x1a793d1a` |
| No minimap | `0x99f27eac` |
| One chapter | `0x1a8a3688` |
| Day only | `0x1a8b53b4` |
| Night only | `0x1a8b53bc` |
| Random hero at map start | `0x1ab183ab` |
| All same heroes | `0x1ab58780` |

### Difficulty / XP scalars

| Value | Key |
|-------|-----|
| Game Difficulty | `0x18700873` |
| Difficulty Xp Modifier | `0x19bddb2e` |
| Global Xp Modifier | `0x187afd1d` |
| Rare Skill Chance Modifier | `0x1871c2fa` |
| Dream Shard Costs Modifier | `0x187310ec` |
| Half Cycle Count Before Boss Awakens Modifier | `0x187443de` |
| Camp Difficulty Modifier | `0x187aaecf` |
| Camp Difficulty Modifier Chance To Apply | `0x187ab36e` |

`Camp Difficulty Modifier` + `Game Difficulty` are the "harder camps/bosses"
levers; `Global Xp Modifier` / `Difficulty Xp Modifier` are the XP levers.

## Deserialization: no bespoke reader

`GameModifierDefinition` / `oCDtNewGamePlusModifier` are **not** read by a
hand-rolled byte reader. The ctor `FUN_1401ad830` zeroes 0x238 and inits; the def
goes through the engine's generic property-reflective serializer (own property
`Difficulty`, descriptor registrar `FUN_1401fe980`, field flag `0x70001`;
component id `0x18705119`, registrar `FUN_1401926c0`).

Implication: a new modifier def = clone an existing `.gamemodifierdef.ot`, edit
identity + `Difficulty`, register via `UsedRscList`. No versioned-reader wall
(unlike herodefs and skills).

## Lua API (shipped)

`R.modifier` reads modifier/difficulty state by name. The values live in the
**global scene context** (the "New Game Plus" group of the entity-value
registry), not on the hero — read from the hero's store every one of them came
back `0.0` in game. So `R.modifier` goes through `R.game`:

```lua
R.modifier.active("No minimap")        -- true if the toggle is on this run
R.modifier.value("Game Difficulty")    -- numeric value, or nil
R.modifier.why()                       -- why the last read was nil
R.modifier.names()                     -- known modifier/scalar names
```

`SceneContextValue_Find(ctx, key)` returns the map entry's **record**, not a
value union. Read off the engine's own setter (`FUN_1402091a0` →
`FUN_140716470` → `FUN_140706660`) and named by RTTI:

| Offset | Field |
|--------|-------|
| `+0x00` | `oCGlobalEntityValueSettings*` |
| `+0x08` | `EntityCpntValueSignal<oCEntityValueUnion const&>` (change signal) |
| `+0x30` | `oCEntityValueUnion` — `+0x08` storage tag, `+0x10` inline data, `+0x18` type byte |

Storage: tag `4` means the data is **inline** at `union+0x10`; any other
non-zero tag is the data's **address** with bit 0 used as a flag (`tag & ~1`).
The type byte, from `EntityValueUnion_InitAsType`'s jump table:

| Type | Value | Size / align | Stored |
|------|-------|--------------|--------|
| `0` | f32 | 4 / 4 | inline |
| `1` | int32 (first dword of the slot) | 16 / 8 | always out of line |
| `2` | bool | 1 / 1 | inline — the modifier **toggles** |
| `10` | unset | — | — |

The decode follows the union's own type byte. Measured in game at a run start:
`Global Xp Modifier` 0.25, `Difficulty Xp Modifier` 1.25, `Current chapter` 0.

### Writing (experimental, local-only)

```lua
R.schedule.next_main(function()          -- engine-mutating: main thread only
  R.modifier.enable_writes()             -- opt-in, shared with R.stat
  R.modifier.set("Global Xp Modifier", 1.5)   -- true when it reads back
  R.modifier.clear("Global Xp Modifier")      -- restores the pre-write value
end)
```

`R.modifier.set` calls the engine's own setter — `SceneContextValue_SetFloat`
(`FUN_14020a580`), `SceneContextValue_SetInt` (`FUN_1402091a0`) or
`SceneContextValue_SetBool` (`FUN_140209010`), picked by the value's type byte —
so the change signal fires like any engine write. **Proven in game:** setting
`No minimap` to 1 mid-run removed the minimap immediately. Both land in `FUN_140706660`, which is the replication
gate: `settings+0xbe` marks a value as **replicated**, a client's write to one is
dropped silently, and a host's is queued for peers. So:

- a **replicated** value is written only when the run is provably solo
  (`Hero Count` reads exactly 1) — refused in co-op and when the count is
  unreadable. ⚠ `Hero Count` read **0** at the start of a solo run, so this gate
  currently refuses replicated values even solo; the two values tested so far
  are not replicated;
- every write is **read back**, because the engine's refusal returns normally;
- a key the context does not hold is refused (the setter never creates one);
- `R.modifier.why()` gives the reason for any `false`.

Modifiers consumed at map generation ("One chapter", "Day only", "Random hero
at map start") change nothing when set mid-run, and the challenge screen does
not show a value set this way.

## SDK kind (shipped)

`modifier` (`src/rsmm/sdk/kinds/modifiers.py`, engine `game_modifier_cook.py`)
clones a vanilla def under a new id with an optional relabel + effect-key swap:

```python
m.register("modifier", id="DoubleTrouble", base="NoBossTimer",
           name="Double Trouble", description="...",
           effect="Game Difficulty")   # reuse another modifier's behaviour key
```

Emits the cooked def + text-bank keys; `apply` registers it additively via
`UsedRscList`. Confidence `guess` — the def cooks and loads, but the UI slot
appearance is unproven. The cook rewrites only whole ASCII identity strings and
the 4-byte behaviour key (every binary marker/count copied verbatim), so it can't
desync the opaque tail. Tests: `tests/test_game_modifier_cook.py`.

## The "5 selected modifiers" cap

Resolved as **not** a spawner-data field. The select screen is the
`Dt Challenge Ui Controller` (registrar `FUN_14035f7f0`), whose settings expose
`m_oGameModifierUiSpawner` (`0x1871e0aa`) and `m_bDisplayEmptySlots`
(`0x1871e0ab`) — which is what first suggested a data-driven slot count. The
actual cap is the controller's pad-to-5 loops plus progressive slot unlocking
keyed off a profile value; lifting it above 5 means patching those loops, which
is high risk and currently parked.

## Open

1. Playtest-verify `R.modifier.*` reads real values, and whether a cloned modifier
   *shows* in the select screen.
2. Type the modifier-def tail in the codec (title/desc keys + behaviour key as
   first-class fields) so relabel/effect stop relying on string surgery.

---

# Ghidra MCP

> Interactive reverse engineering of Ravenswatch through the Ghidra MCP bridge.

Source: https://docs.rsmm.me/reverse-engineering/ghidra-mcp/

LaurieWired's GhidraMCP exposes the live Ghidra session over HTTP and
bridges it to MCP. Claude Code (or any MCP client) can then
`decompile_function`, `list_methods`, `rename_function`, etc. against
the already-analyzed `Ravenswatch.exe` without re-running headless
scripts.

This is complementary to the headless pipeline in [PIPELINE.md](/reverse-engineering/pipeline/):

- **Headless / `out/`** — bulk, batch, regenerated after game patch.
- **GhidraMCP** — live, iterative; great for "what calls this?" or
  "rename these 12 functions before the next dump".

## Inputs

```
~/Documents/Programming/ghidra_11.3_PUBLIC/      Ghidra install (v11.3)
~/.var/app/.../Ravenswatch/Ravenswatch.exe       target binary
./ghidra_project/Ravenswatch.rep/                pre-analyzed project
```

## One-time install

1. **Extension** — already installed at:
   `~/Documents/Programming/ghidra_11.3_PUBLIC/Ghidra/Extensions/GhidraMCP/`
   (`extension.properties` patched to `ghidraVersion=11.3` because the
   upstream release ships as 11.3.2.)

2. **Bridge** — `tools/ghidra_mcp/bridge_mcp_ghidra.py`. PEP-723 inline
   metadata declares `requests` + `mcp`; `uv run --script` resolves
   them on first run.

3. **MCP registration** — `.mcp.json` at repo root registers the
   `ghidra` server with stdio transport pointing at
   `http://127.0.0.1:8080/` (the embedded HTTP server inside Ghidra).

## Running

1. **Start Ghidra GUI**:

   ```
   ~/Documents/Programming/ghidra_11.3_PUBLIC/ghidraRun
   ```

2. **Enable the plugin** — `File → Configure → Miscellaneous`, check
   `GhidraMCPPlugin`. (First launch after install only.)

3. **Open the project + program** — `File → Open Project`,
   pick `./ghidra_project/Ravenswatch.gpr`, then double-click
   `Ravenswatch` in the project window so a CodeBrowser tool opens
   with the program. The HTTP server only serves the *currently open*
   program.

4. **Verify the server** — should be listening on
   `127.0.0.1:8080`:

   ```bash
   curl -s http://127.0.0.1:8080/methods | head
   ```

5. **Reload MCP in Claude Code** — `.mcp.json` is picked up on
   session start; `/mcp` lists the `ghidra` server.

## Available MCP tools

`list_methods`, `list_classes`, `list_segments`, `list_imports`,
`list_exports`, `list_namespaces`, `list_data_items`, `list_functions`,
`search_functions_by_name`, `decompile_function`,
`decompile_function_by_address`, `disassemble_function`,
`get_function_by_address`, `get_current_address`, `get_current_function`,
`rename_function`, `rename_data`, `rename_variable`.

Renames flow straight into the live Ghidra database — they persist
when you save the project, so iterative naming work survives across
sessions.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `curl: (7) Failed to connect` to `:8080` | No program open in CodeBrowser, or plugin not enabled. Open `Ravenswatch` in CodeBrowser. |
| `/mcp` shows `ghidra: failed` | Bridge couldn't reach `:8080`. Start Ghidra first, then restart Claude Code. |
| Ghidra refuses to load extension | Version mismatch in `extension.properties` — patch `ghidraVersion=` to match installed Ghidra. |
| Renames don't stick | Save project (`Ctrl+S` in CodeBrowser) before closing. |

---

# Heroes

> Why a hero definition has no class UID, what its 29 named slots hold, and how the runtime hero controller differs from the definition that builds it.

Source: https://docs.rsmm.me/reverse-engineering/heroes/

:::note
Status: Tier-1 RE backing `src/rsmm/sdk/kinds/heros.py`, from live Ghidra MCP +
headless decompilation. Fields marked *unconfirmed* need verification before byte
emission. A **net-new hero is the hardest content kind**; a reskin works today.
:::

Heroes are the hardest playable kind because `oCDtHeroDefinition` has **no
registered class UID** — it lives as a nested definition inside a parent
`SkillProfileDataSettings` record. The hero is created and destroyed by the
*parent's* deserializer, not by a top-level factory lookup.

## The chain

```
SkillProfileDataSettings   (UID 0x186adbdf, size 0xd0, factory FUN_1403122f0)
    |  embeds (typed field)
    v
oCDtHeroDefinition         (no UID, ctor FUN_1403143b0, >= 0x900 bytes)
    |  named slots resolve through
    v
oCTLibrary<oCDtHeroDefinition>     (dtor FUN_14032deb0, acquire FUN_14032e960)
                                   (singleton address NOT located — see below)
```

`SkillProfileDataSettings` derives from `oISerializable` (UID `0x1da16c`).

| Class | UID | Size | Ctor | Dtor |
|---|---|---|---|---|
| `SkillProfileDataSettings` | `0x186adbdf` | `0xd0` | registrar `FUN_140192330`, schema cb `FUN_1403122f0` | — |
| `oCDtHeroDefinition` | **none** | **≥ `0x900`** | `FUN_1403143b0` | `FUN_140314930` |
| `oCTLibrary<oCDtHeroDefinition>` | — | — | acquire `FUN_14032e960` | `FUN_14032deb0` |

## The 29 named slots

The ctor writes a long sequence of named-slot tuples plus two sub-record ctors.
Each slot is `{char* name = &DAT_140eb46d0 (empty sentinel), u32 hash =
0x80000000 (unresolved), u32 flag}`, most with an **owner pointer** naming the
library the name resolves in.

| Group | Slots | Owner | Inferred semantic |
|---|---|---|---|
| Pre-ability pairs (`+0x2b8`, `+0x2c8`, `+0x2f0`, `+0x300`) | 4 | `DAT_141447250` | idle / locomotion animation IDs |
| Ability blocks × 4 (`+0x328`, `+0x398`, `+0x408`, `+0x478`) | **12** | `DAT_141446e18` | 4 abilities × {name A, name B, description key} — A likely the power id, B the upgraded variant |
| Standalone (`+0x4e8`) | 1 | (none) | base entity / model ref |
| UI spawner pair (inline, `+0x500..+0x5d8`) | 2 | `DAT_141446f38` | portrait / select-screen UI spawn |
| Melody/talent × 4 (`+0x5d8`, `+0x610`, `+0x648`, `+0x680`) | 8 | `DAT_141447250` | 4 melodies (or talent trees) × {name, alt} |
| Late slot (`+0x7e8`) | 2 | `DAT_1414470f0` | voice bank / sound bank |

Total 29. The owner globals are `oCMetaClass*` records for the respective ID types
(animation, power, sound, UI) — they tell the asset loader **which library to look
the name up in**. Hash `0x80000000` marks the slot unresolved; the loader replaces
it with the real hash and swaps the pointer for a pooled string once the ID
resolves.

*The per-owner mapping is inferred from position and count (4 abilities × 3 names
matches the per-hero ability roster), not confirmed from a dumped record.*

Other notable offsets: `+0x288` installs `oIGameProfileDataOwner` with a 16-byte
GUID from `CoCreateGuid`; `+0x6b8..+0x7d0` is a fixed vector of 5 × 0x38-byte
entries; `+0x7d0` is another `{ptr, count, cap}` collection of 0x38-byte entries;
`+0x828..+0x8a0` is an `oCGameLockSettings` + event-listener + flag-list complex
(the unlock condition); `+0x2a0` is set to 1 at the end of the ctor as a
"fully initialized" marker.

### Three parallel arrays

The dtor shows the parallel-pointer-array pattern plainly:

```c
A : ptr=+0x8a0, count=+0x8a8, cap_flag=+0x8ac
B : ptr=+0x8b0, count=+0x8b8, cap_flag=+0x8bc
C : ptr=+0x8c0, count=+0x8c8, cap_flag=+0x8cc
```

Each loop body is the standard
`for i in 0..count: entry->vftable[8](entry); entry->vftable[0x10](entry, 1)` —
every entry is a polymorphic owning pointer with a virtual destructor. The extra
field is the capacity-allocated flag; when set, the buffer itself is released.

Allocation size is therefore at least `0x8d0`, almost certainly rounded to `0x900`
for the pool.

## How the hero gets built

`Register_SkillProfileDataSettings` sets up UID `0x186adbdf`, size `0xd0`, factory
`FUN_1403122f0`. The `oCDtHeroDefinition` name string is referenced **twice from
data** inside the field-schema table the registrar emits — i.e.
`SkillProfileDataSettings` declares a typed nested field of type
`oCDtHeroDefinition`. So the parent deserializer:

1. Reads the parent's `0xd0`-byte preamble.
2. Hits the nested field marker → looks up `oCDtHeroDefinition` **by name, not by
   UID**.
3. Calls the hero ctor to construct it inline.
4. Streams the named-slot values into the right offsets, replacing the sentinel.
5. Streams the variable-length arrays A / B / C.

The acquire helper pulls an entry off the library's free list at `+0x170`, runs
the ctor, and links it via the library's `+0x180` critical section.

## The missing library singleton

The `oCTLibrary<oCDtHeroDefinition>` singleton **address** is the one piece of
metadata still missing. The dtor is reached only via a scalar-dtor thunk that is
itself referenced exclusively as slot 0 of the library's own vftable, and the
static-init that does `_DAT_<addr> = vftable;
InitializeCriticalSectionAndSpinCount(...)` is unnamed — likely inlined into a
larger group init.

**Until that singleton is located, runtime injection of new heroes through the
library is not possible.** The path that does work is the parent record: emit a
cooked asset containing a `SkillProfileDataSettings` and let the normal level-load
deserializer build the hero.

## Insertion recipe (cooked-asset path)

1. **Parent settings record** — `0xd0` bytes, UID `0x186adbdf` in the cooked
   header. The factory runs at load time to set the display name.
2. **Embed the hero** in the layout above: animation name pairs, 4 ability blocks
   (two name strings + a description key each), 4 melody/talent name pairs,
   portrait/voice slot, standalone model ref.
3. **Variable-length arrays** — lengths + entries for A, B, C and the 0x38-stride
   vector. **What A/B/C contain is not confirmed**; most likely powers, talents
   and melodies as full nested records.
4. **Text bank** — one i18n entry per ability description key plus the hero's
   display name, using the `RSMM_<modid>_<heroid>_<slot>` key convention.
5. **Hero pool** — the level-load orchestrator reads `Map+0x720..0x728` (random
   hero pool) and `Map+0x738..0x748` (played hero pool) at stage 0. A custom hero
   must be listed in at least one to be selectable in a run. There is no clean
   splice for this yet.

Unknown fields fall back to **clone-from-base**: copy a vanilla hero's bytes
verbatim and patch only the offsets above.

## The runtime hero object

Everything above is the **definition** — static data used to *build* a hero. At
runtime the playable hero is a different object: `oCDtEntityCpntHeroController`
(`HeroController_Ctor`), the hero controller **component** of the entity. This is
what the loader captures as the "hero pointer" for `R.entity` / `R.combat`.

| Offset | Field |
| --- | --- |
| `+0x15c8` | current HP (f32, plain mirror) |
| `+0x15cc` | max HP (f32) |
| `+0x15d0` | missing-health ratio (f32, default 1.0) |
| `+0x15d4` | ratio divisor (f32, default 0.5) |
| `+0x1d80` | HUD HP-mirror pointer (local player only) |
| `+0x1fc..+0x220` | 10-slot ability/input config (int tags `{0,1,1,1,2,1,1,1,1,3}`) |

Controller size ≈ `0x1e40`.

**Most hero stats are not plain fields.** They are
`oe::EntityCpntValueSignal<bool|int|float|oCVec3>` sub-components — the ctor builds
dozens. Writing a signal fires a change notification on the gameplay bus, which is
*why* stat changes surface as named events. Dream shards are the exception (this
field was documented as HP until 2026-09-18): they are additionally
mirrored to the plain f32 at `+0x15c8` for the hot path, which is exactly why
`R.shards` can read and write them directly while energy, cooldowns and speed live
inside signal objects with no fixed plain-float offset. Reaching those is a
per-signal RE job, not a constant lookup — see
[Stats & XP](/reverse-engineering/stats/) for the keyed store that covers most of
them.

## See also

- [Anatomy of an entity](/reverse-engineering/entity-anatomy/) — what an entity is, and the three places a number can live.

---

# Hookpoints

> Candidate hook targets mapped from game feature to engine function.

Source: https://docs.rsmm.me/reverse-engineering/hookpoints/

Distilled from a string-anchor sweep of `out/strings.json` and the
`out/decompiled_all/` corpus. Each row maps one of the community
feature requests to the most promising candidate function(s) for
`rsmm.hook` once the API ships.

Status legend:

- **anchor** — we have a string constant inside the function, so the
  function clearly *participates* in this subsystem; deeper RE
  needed to confirm whether to hook the function itself, its caller,
  or one of its callees.
- **registry** — function constructs the event-name table (or
  similar metadata); not itself a useful hookpoint, but its
  string-xrefs lead to the real dispatchers / consumers.
- **dispatcher** — function emits events of this type; hookable
  directly (intercept arg) or in chain (replace pre/post).
- **consumer** — function reacts to the event (likely the gameplay
  logic).

## Glossary

The game's internal vocabulary differs from the community's:

| Community word | Engine word           |
|----------------|-----------------------|
| Talent         | **Skill**             |
| Item           | **Magical Object** (MO) |
| Curse / Curse item | MO with `Cursed` tag |
| Refugee / Vendor   | **Refugee Archetype** (NPC archetype picker) |
| Aggro range        | not yet found — probably on `oCEnemyCampDifficultyDefinition` or similar |
| Difficulty/scaling | **Camp Difficulty Modifier** + `Difficulty Xp Modifier` |
| Talent stacking    | **Skill** add — currently dedup-guarded somewhere downstream of "Skill selected" |
| Talent restriction | **Skill** rolltable filter (in `Skill propose`) |

## Anchors found so far

| Feature                              | Anchor fn (link VA)     | Source string(s)                                                                 | Role |
|--------------------------------------|-------------------------|----------------------------------------------------------------------------------|------|
| Game event-name registry             | `FUN_1401d1850` (`0x1401d1850`) | `Skill propose`, `Skill selected`, `Level up`, `Pick Up Magical Object`, `Magical Object Destroyed`, `{Common,Rare,Epic,Legendary,Cursed} Magical Object Destroyed`, `Hero kill streak`, `Hero permadeath`, `Final victory never using any feather` | registry |
| Game-state machine (modifiers)       | `FUN_1401d6b10` (`0x1401d6b10`) | `Is in victory sequence`, `Is in defeat sequence`, `Difficulty Xp Modifier`, `Camp Difficulty Modifier`, `Camp Difficulty Modifier Chance To Apply`, `Half Cycle Count Before Boss Awakens Modifier` | dispatcher |
| Skill choice surface (`Extra skill` / `Extra MO`) | `FUN_1401d2e90` (`0x1401d2e90`) | `Extra skill choice`, `Extra MO Choice`                                          | dispatcher |
| GameOptions ctor (Forced seed lives here) | `FUN_1401c6d60` (`0x1401c6d60`) | `Forced seed`                                                                | registry — already used by `mods/ExampleSeedPin` |
| Run-end emitter                      | `FUN_1401f1a40` (`0x1401f1a40`) | `run_end`                                                                       | dispatcher |
| Run-level emitters                   | `FUN_1401f3b90`, `FUN_1401f2c80` | `level_reached`, `level_up_reach`                                              | dispatcher |
| Run-abandon emitter                  | `FUN_140291190`, `FUN_1402836a0`, `FUN_140292090` | `Abandon`                                                              | dispatcher (multiple call sites — narrow before hooking) |
| Resource lookup (already hooked Phase 3) | `FUN_140487040` (`0x140487040`) | n/a                                                                          | consumer — every cooked entity-by-path resolution |

## Feature → action plan

The "next RE step" column points at the concrete work needed before
each hook can be implemented. Most of them are short follow-ups on the
anchor function (a single Ghidra xref pass, or a 10-minute decomp
read).

### Talents

| User-requested feature                            | Anchor / candidate         | Next RE step                                                                                                   |
|---------------------------------------------------|---------------------------|----------------------------------------------------------------------------------------------------------------|
| Add talents (custom Lua-defined skill)            | Need: `Skill propose` consumer | Xref `"Skill propose"` from `FUN_1401d1850`; find the *emitter*; the row of three skills is built somewhere in that flow. |
| Restrict which talents can appear                 | Same as above             | Hook the skill-roll function; filter the candidate list before it's returned to UI.                            |
| Stack same talent multiple times                  | Find the dedup guard      | Xref `"Skill selected"` consumer; the function that records the chosen skill onto the hero almost certainly contains an `if (already_has(skill_id)) reject;` branch — patch / hook that. |
| Talent selection beyond lvl 10 (Heredos)          | `FUN_1401d2e90` (`Extra skill choice`) | Read decomp; find the `level >= 10` guard or the cap-counter increment; either bump the cap or insert hook to grant. |
| "Activate all talents" buff                       | Need: skill-effect dispatcher | Find the function that, on hero update, walks the hero's skill list and applies each — call it from a Lua tick with every skill id. |
| "Pick one talent" item                            | Need: `Skill propose` emitter | Same flow as restrict; replace candidate list with a single deterministic id. |
| Add extra talents at level 11 (curse / legendary) | `FUN_1401d2e90` + skill-grant | Combine: emit `Extra skill choice` on level 11 with a curse-tagged pool. |

### Magical Objects (items, curses, legendaries)

| Feature                                  | Anchor                       | Next step                                                                                                  |
|------------------------------------------|------------------------------|------------------------------------------------------------------------------------------------------------|
| Add new MO                               | Asset-side (entity def)      | Already partially supported via cooked-asset overrides; new entity needs the `.gen` re-encoder (separate track). |
| Modify MO (effects)                      | `FUN_1401d1850` events + the MO def | Live-modify via memory writes on the MO's modifier table. |
| Legendaries/cursed limited to 1          | Need: MO pool filter         | Xref `"Legendary Magical Object Destroyed"` / `"Cursed Magical Object Destroyed"` to find the picker; insert hook that rejects a second roll of the same rarity. |
| Extra MO choice (already exists as engine surface) | `FUN_1401d2e90` (`Extra MO Choice`) | Same function as `Extra skill choice` — confirm both go through one dispatcher. |

### Scaling / difficulty

| Feature                                | Anchor                       | Next step                                                                                                  |
|----------------------------------------|------------------------------|------------------------------------------------------------------------------------------------------------|
| Act 2 / Act 3 harder than baseline     | `FUN_1401d6b10` (`Camp Difficulty Modifier`, `Difficulty Xp Modifier`) | Read decomp; modifiers are floats. Two paths: (a) hook the modifier *getter* and multiply, (b) write the underlying float to `GlobalValues_Common/NGP_Enemy_*_Modifier.globalvalue` cooked file. Path (b) ships today; (a) needs hooks. |
| 4-player density (XP / HP / stagger scaled) | Same                         | The same modifier struct includes XP. Hook the player-count → modifier-product function; bump density independently of player count. |
| Movement speed / attack speed / cooldown / aggro range (player or enemy) | Need: stat-getter           | Stats live in `oIEntityValueModifierComputer` (in strings.json). Hook its `compute()` and apply a tag-keyed multiplier. |

### Spawn / generation

| Feature                                | Anchor                       | Next step                                                                                                  |
|----------------------------------------|------------------------------|------------------------------------------------------------------------------------------------------------|
| All enemies = crabs                    | Need: enemy-template picker  | `EntityCpntMethodPicker`, `AliasPicker`, `RefugeeArchetypePicker` (in strings.json) are pickers. The enemy version probably has a similar name; needs a Ghidra class-walk. Once found, hook the picker, force return = crab template id. |
| Modify NPCs (vendors / refugees)       | `RefugeeArchetypePicker`     | Decompile + hook to pin a chosen archetype.                                                                |
| Reward / chest content by difficulty   | Need: reward roller          | Xref `"_InitAllRewards"` (`FUN_1401e6030`) — it's a reward-type registrar; the actual roller will be a sibling. `oCDtRewardDefinition` is the entity class. |

### Seed / run

| Feature                                  | Anchor                          | Next step                                                                                                  |
|------------------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------|
| Per-chapter seed input                   | `Forced seed` (already mapped)  | The bool/value pair is one global. Hook the chapter-init function (xref `"Chapter 1 Complete"` etc.) and reseed per chapter. |
| Quest selection (enable/disable)         | Need: quest roller              | No direct anchor yet. Look for `quest` / `Quest` strings; if absent, the quest system probably re-uses `_InitAllRewards`-style entity drop tables. |

### Run-end / stats

| Feature                                | Anchor                          | Next step                                                                                                  |
|----------------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------|
| Win / Lose / Abandon counter per hero / difficulty / coop | `FUN_1401d6b10` (`Is in victory sequence`, `Is in defeat sequence`) + `Abandon` dispatchers | Hook the three dispatchers; record `(hero_id, difficulty, coop?)` to a JSON in `mods/<id>/state.json`. Read-only memory access — no game-state mutation needed. |
| Enable shapeshifter by default on Scarlet | Need: hero-load function       | No `Shapeshift` string found. Likely encoded as a class name. Walk Scarlet's cooked entity files for `oCDtEntityCpnt*Shapeshift*` and then xref. |

## Recommended first POC for `rsmm.hook` validation (task #6)

**Pick one of:**

1. **Win / Lose / Abandon counter** — pure read-side hooks on the
   three dispatchers in `FUN_1401d6b10` + `FUN_140291190`. No
   mutation, can't break a run, easiest to prove the API works.
2. **Difficulty multiplier hook** — pick the modifier-getter inside
   `FUN_1401d6b10`, multiply by N from Lua. Visible in-game
   immediately (enemies harder), trivial to roll back.

Either choice would prove the full chain: `rsmm.resolve(name) →
rsmm.hook(va, "sig", cb) → callback fires → modifies behavior →
unhook on mod disable`.

## Methodology used (so this is repeatable)

1. `python3` over `out/strings.json` bucketed by feature-keyword
   regex (see this commit's `_re/HOOKPOINTS.md` for the list).
2. `grep -rE "<exact string>" out/decompiled_all/` to find the
   containing functions.
3. Most "feature event" strings (`Skill propose`, `Camp Difficulty
   Modifier`, etc.) collect inside *two* functions:
     - a giant **registry** function (`FUN_1401d1850`,
       `FUN_1401d6b10`) that constructs the event/modifier name
       table at boot,
     - the actual **dispatcher** that takes the name and routes it.
   The registry is found first; the dispatcher is a Ghidra xref of
   the name string from outside the registry function.
4. To get the dispatcher we need a small Ghidra script —
   `docs/_re/scripts/xrefs_to.py` already exists; run it for each
   anchor string. That gives the consumer functions per feature.

Next pass should be a script that takes the list of anchor strings
from this doc and dumps decompiled bodies of every xrefing function
into `out/hookpoint_candidates/`. That's the menu we hook from.

---

# Items (magical objects)

> Class layouts behind the magical-object drop chain — reward definitions, drop settings, selectors — and the pickup component the engine spawns.

Source: https://docs.rsmm.me/reverse-engineering/items/

:::note
Status: Tier-1 RE from live Ghidra MCP + headless decompilation. Fields marked
*provisional* are inferred from ordering, not proven by a string in the binary.

The **authoring** path is shipped and verified end-to-end in the SDK — a custom
magical item is a manifest plus `rsmm apply`. See
[Custom items](/guides/custom-items/). This page is the engine-side reference
behind it.
:::

## The chain

```
oCDtRewardDefinition                  data class
    |  referenced-by
    v
oCDtRewardEntitySelectorToSpawnEntityCpntSettings   per-drop selector
    |  owns
    v
oCCustomFlagList                      filter tags
    |
    v
oCDtEntityCpntMagicalObject           runtime component (pickup entity)
    |
    v
oCDtEntityCpntMagicalObjectsDropSettings   drop-table config (0xa50 bytes)
```

The "settings" type is the *authored* container referencing each magical object's
prefab; the runtime component is the instance the engine spawns for one pickup.

## Class registry

The schema addresses are **schema-declarer callbacks**, not deserialization
factories: each calls `MetaClass::SetDisplayName(name)`, writes flags into the
declarer state, then registers the field groups. Ctor/dtor/size live in a separate
registrar that walks `oCMetaClass_FindByKey` then `oCMetaClass_Alloc`.

| Class | UID | Size | Registrar | Schema cb | ctor | dtor |
|---|---|---|---|---|---|---|
| `oCDtRewardDefinition` | `0x176f164e` | `0x298` | `FUN_140237f40` | `FUN_14031a040` | `FUN_1401e3ca0` | `FUN_1401e3d50` |
| `oCDtEntityCpntMagicalObjectsDropSettings` | `0x168afca6` | `0xa50` | `0x140277790` | `FUN_1402d2290` | `FUN_1402d2310` | `FUN_1402d0cc0` |
| `oCDtEntityCpntMagicalObject` (runtime) | — | ≥ `0x2b0` | — (component, not registry-keyed) | — | `FUN_1401e0e10` | `FUN_1401e10f0` |
| `oCDtRewardEntitySelectorToSpawnEntityCpntSettings` | — | — | — | — | `FUN_1401e3e90` | — |
| `oCDtEntityCpntMagicalObjectSettings` (authoring) | — | ≥ `0xc00` | — | — | `FUN_1402ce2b0` | — |

## `oCDtRewardDefinition` (size `0x298`)

| Offset | Field | Notes |
|---|---|---|
| `+0x00` | vftable | |
| `+0x08..+0x20` | `oISerializable` slots | zeroed by ctor |
| `+0x30` low byte | `oIResource` flags | `& 0xe0` at ctor — high 3 bits preserved by caller |
| `+0x34` | refcount | set to `1` |
| `+0x3c` | resource state | `0` |
| `+0x40` | `oCResourcePath::name` | **the logical id lives here** once loaded |
| `+0x48` | `oCResourcePath::hash` | u32 |
| `+0x50` / `+0x58` / `+0x5c` | resource-list prev / next / count | |
| `+0x60..+0x260` | `oCDtDefinition` body | sub-records |
| `+0x270` | `oCDtDefinition` ptr | released in the dtor — likely display name / description |
| `+0x284` | `oCDtDefinition` flags | `0x0101` |
| `+0x288` | **entries** ptr | qword array, freed slot-by-slot in the dtor |
| `+0x290` / `+0x294` | entries length / capacity | |

The named slot at `+0x40`/`+0x48` is what `oIResourceManager::FindOrLoad` keys on.

For the **fully typed** rewarddef grammar (the section directory, per-class version
gating, `oCItem` rows) see [Rewards](/reverse-engineering/rewards/).

## `oCDtEntityCpntMagicalObject` (size ≥ `0x2b0`)

| Offset | Field |
|---|---|
| `+0x00` | vftable |
| `+0x18` | `EntityCpntValueSignal<bool>` — "is_active" |
| `+0x38` | `EntityCpntValueSignal<bool>` — "ever_spawned" |
| `+0x58..+0x68` | small int / flag block (low nibble of `+0x64` masked) |
| `+0x90..+0xf8` | three closure slots (signal binder header, ctx + del) |
| `+0x1f8` | `EntityCpntValueSignal<int>` — **rarity** *(provisional)* |
| `+0x218` | `EntityCpntValueSignal<int>` — **count** *(provisional)* |
| `+0x238` | `EntityCpntValueSignal<int>` — **level** *(provisional)* |
| `+0x290` | `oCCustomFlagList::vftable` — tag list |
| `+0x298..+0x2a8` | flag-list body |
| `+0x2ac` | `0xffffffff` sentinel |

The rarity / count / level labels come from ordering alone — no schema string in
the binary proves the mapping. Treat them as provisional until a save-game diff
confirms which signal carries which int.

## `oCDtEntityCpntMagicalObjectsDropSettings` (size `0xa50`)

High level only — the body is a 0x80-byte stride array built by
`_eh_vector_constructor_iterator_`.

| Offset | Field |
|---|---|
| `+0x00` | vftable |
| `+0x1f8` | array of 12 × 0x80-byte entries (drop-table rows) |
| `+0x3f8`, `+0x478`, … | further rows, pattern repeating |
| `+0x9d0` | `oCEntityCpntPicker` 1 |
| `+0xa10` | `oCEntityCpntPicker` 2 |
| `+0xa48` | tail |

The SDK does not synthesize new drop-table rows — it threads a new reward through
an existing one.

## `oCDtRewardEntitySelectorToSpawnEntityCpntSettings`

| Offset | Field |
|---|---|
| `+0x00` / `+0x08` | vftable (`oIEntitySelectorToSpawnEntityCpntSettings` first, then specialized) / secondary vftable |
| `+0xf8` / `+0x100` / `+0x104` | target name ptr (empty sentinel) / hash `0x80000000` / resolved flag |
| `+0x108` / `+0x110` / `+0x114` | parent path ptr / hash / resolved flag |
| `+0x118` | resolved `oCMetaClass*` = `DAT_141447bd0` (`oCDtRewardDefinition` meta) |
| `+0x120` low byte | enable flag (`1`) |
| `+0x130` | `oCCustomFlagList::vftable` |
| `+0x138..+0x148` | flag-list body |

So a selector pins to one named reward definition, its parent resource group, and
a tag filter.

## Engine-side insertion

Following the `oIResourceManager` slot-3 by-name lookup ABI:

1. **Register UID** — the `oCMetaClass` for `oCDtRewardDefinition` is
   `DAT_141447bd0`; its registrar static-inits before `main()`, so nothing is
   needed for the existing class. A *new* UID would require running the same
   `oCMetaClass_FindByKey → oCMetaClass_Alloc → set sizeof+align → SetDisplayName
   → register factory` sequence at boot.
2. **Construct** an `oCDtRewardDefinition` (or clone a vanilla one) and fill
   `+0x40` = `"rwd_<mod>_<id>"`, `+0x48` = name hash, the `oCDtDefinition` fields.
3. **Insert** into `oCTLibrary<oCDtRewardDefinition>` (singleton `0x141412e00`) via
   vftable slot 3 (`+0x18`, `FindOrLoad`) with an `oCResourcePath`. The library
   allocates an entry, links it into the `+0x150` head / `+0x148` tail list under
   the `+0x118` critical section, and returns a refcounted pointer.
4. **Selector** — for every drop site, the selector's target name must match the
   new reward's name, and its tag list must contain at least one tag matching the
   dropper's `oCCustomFlagFilter`.
5. **Magical object** — the pickup entity's own flag list at `+0x290` must overlap
   the drop-settings row's filter.

:::tip
In practice none of this is done at runtime. The shipped pipeline is asset-level:
a cooked def plus a `versiondef` magical-object vector entry plus a `UsedRscList`
registration, all emitted by the `item` kind. Runtime library injection stays a
fallback for cases assets can't reach.
:::

---

# Level format and build path

> The four layers of a cooked level, the gate that decides whether its objects are ever instantiated, and what an empty tile does and does not prove.

Source: https://docs.rsmm.me/reverse-engineering/level-format/

A tile's level is the file that says *what stands where*. Editing one is how a
mod adds a structure to the world, and it is the part of the pipeline where a
mistake is hardest to see: a malformed level parses, round-trips, passes every
cache and reference check, and produces a tile that is placed, built, and
completely empty. Nothing logs and nothing crashes.

This page is the map of that file and of the code that consumes it.

## A level is four nested layers

`<Biome>\Tiles\<Name>.level.ot` cooks to a `.GameStream.gen`, and an edit has to
be legal at every layer. Traced from `LevelStream_LoadStep` downward:

1. **The outer cooked container.** Type B, declaring class `oCGameStream`
   (id `0x14c31bf`, version 1.1). Sections are `MARK_BEGIN`/`MARK_END`
   delimited. `rsmm.engine.cooked` parses and re-emits it.
2. **`BufferLen`, and it is load-bearing.** `oCGameStream::Deserialize` reads a
   `u32` the engine itself names `BufferLen`, resizes a buffer to it, and then
   reads exactly that many raw bytes. **Everything past it is never seen.** That
   field is the `u32` pair at section-payload `+0x08`/`+0x0c`, equal to
   `len(payload) - 16`, which `cooked_schemas.asset_refs._restamp_self_size`
   maintains. It is not a corpus convention — it is the number the engine reads.
3. **A second cooked container fills that buffer.** Type A, `"Cooked"` magic,
   starting at payload `+0x10`. Its class table declares only
   `oCGameLevelIdentifier` (id `0x6494652`, version 1.3) and `oISerializable`,
   so every sub-object in a level is a level identifier plus a transform blob.
   Sections here carry **no length fields** — the reader scans for the balanced
   end marker — so an insert needs balanced markers and nothing else.
4. **The identifier itself.** `oCGameLevelIdentifier::Deserialize` reads four
   fields, gated on class version 1, 2 and 3. Shipped files are 1.3, so all four
   are read, and a clone must carry the class table through untouched.

### What a placement record contains

Records of one size within a level are byte-identical except for the transform.
Measured across a donor's 29 same-size records, the only varying bytes are
position, rotation and scale. **There is no per-object identity field**, so a
record copied as a template cannot collide with the one it came from, and the
level's own identity GUID is not back-referenced by its objects — it appears
exactly once in the file.

## The build path, and the gate

One function builds a level, and it is four calls:

```text
ResourceRef_Resolve            resolve the level resource
LevelStream_LoadStep(...)      false -> destroy the level, bail
gate(db, level, 0)             false -> destroy the level, null the slot
                               true  -> keep it, and instantiate its objects
```

`db` is the runtime `oCGameLevelDatabase` (class id `0x064a9acd`). **No shipped
asset declares it** — it is runtime-only, so there is no registry file a mod can
add itself to.

Inside the gate, after appending the level to the database's vector, a loop
walks the level's objects and calls a load-or-create for each. Three things can
leave a level empty, and all three are silent:

| Path | What happens |
| --- | --- |
| The accept check refuses | the loop never runs at all |
| The object count is zero | there is nothing to walk |
| Each object fails a mask test | they are skipped one by one |

:::caution[The skip test is a zero check, not a comparison]
The engine's `test` / `jbe` pair looks like a magnitude comparison. `test`
always clears the carry flag, so that `jbe` is really `je`: an object is skipped
precisely when the AND comes out **zero**. The array stride is the size of a
resource reference block, which puts the tested field exactly where a resolved
pointer lives — so this may be "skip every object whose resource never
resolved", the documented null-preload failure seen from the skip side rather
than the crash side.
:::

The symbols are in the map as `LevelDatabase_BuildAndRegister` and
`LevelObject_LoadOrCreate`; see [Engine symbols](/reference/symbols/). Both were
promoted only after the module's exception table confirmed each is a genuine
function start, which is the rule for any hook target.

## What an "incomplete" level load does not mean

`LevelStream_LoadStep` returns false in exactly two cases: the progress tick
says stop, or a state field is not 1. The tick is a **frame budget**, so a step
that has not finished is ordinarily a deferral and the loader is called again
next frame.

A trace of these fired once per placed mod tile across six playtests and was
recorded as a contradiction every time. It was the frame budget. Read the
resource names, never the count.

## Reading the evidence

Two habits cost more playtests in this area than every genuine bug combined.

### Pick probes by corpus exclusivity

A resolve count only means something if the name can only have come from the
thing you are testing. In one Dark Hills map:

| Probe | Shipped levels in the chapter that place it |
| --- | --- |
| A grass patch | 24 |
| A pike | 4 |
| A broken log | 3 |
| The bonfire | **0** — its only tile is in another chapter |

Four runs were spent on the first three, measuring vanilla traffic and
concluding nothing. Counting how many shipped levels place a name is one loop
over the uncooked corpus, and it is the difference between a measurement and a
number. Do it before reading any count.

### Decide whether a field is an input or an output

The gate fills `level+0xc8` and `level+0xc0` while it runs. A probe that read
them *before* the call reported zero objects for every level in the game, and
that was twice mistaken for a wrong offset. The offsets were right; the fields
are empty on entry.

Before reading a struct field around a call, decide whether that call *consumes*
the field or *produces* it, and read on the matching side. Read an output after,
and only when the call succeeded — on a failure the engine here destroys the
level, so anything read then is freed memory.

### A number that is wrong everywhere is a broken instrument

If a probe reports zero for levels that visibly build, the probe is wrong, not
the game — either the offset, or the moment, as above. Sanity-check every new
measurement against a case you know works *before* reading anything into the
case you are investigating. Where you can, prefer measurements that depend on no
struct offset at all, such as counting calls or resource fetches across a
window; they survive both mistakes.

Two more instrument traps, both of which produced confident wrong answers here:

- **A log budget can hide the one line that matters.** A cap of 40 met a map
  that builds exactly 40 levels, so the mod's own level was never printed and
  the run read as "our level never reaches the gate".
- **A trace that reads the wrong string field says nothing, loudly.** The
  resource trace printed the resource *root* for its whole life, so every line
  read `shaders` or `3D` and its name filter had never once been seen working.
  "Resolved zero times" and "the read is broken" were indistinguishable.

Both are fixed, and they are why the findings here cite what was measured rather
than what was inferred.

## Additive levels

A mod can own a level and place its own entity in it. `poi` supports this with
`own_level = true` plus a `places` entry naming `@prop`, which stands the entity
the def emits at a transform the def chooses. Nothing shipped is modified: no
entity is overwritten, no vanilla object is destroyed to borrow its slot, and
the marker's icon is cooked under a name the mod owns rather than repainted over
a shipped texture. A clean apply of such a mod creates **no backups**, which is
the check that it is genuinely additive.

The contrast is `swaps`, which re-dresses a slot the level author chose and
**inherits that slot's transform whole** — position, rotation and scale. That
single fact produced, in order: props tipped over, props buried below ground,
and a structure wedged inside a boulder. Prefer `places`.

:::note[Status]
A mod-owned level is placed, its resource resolves, and the gate keeps it. As of
this writing, whether its objects are instantiated is still open, and it is the
last unknown in the additive route. The three paths above are the whole
remaining hypothesis space.
:::

---

# Maps & chapters

> How a run is assembled from a chapter sequence, which layer is editable today, and why a brand-new playable level is out of reach.

Source: https://docs.rsmm.me/reverse-engineering/maps-chapters/

:::note
Status: chapter re-sequencing **proven in-game** 2026-07-11. A net-new level is
blocked on level-asset authoring, not on RE.
:::

## Three layers

| Layer | Class / asset | Codec |
|-------|---------------|-------|
| **Map** | `oCDtMapDefinition`, `*.mapdef.ot` (loader `MapDef_RegisterAssetLoader` = `FUN_140322a50`) | `cooked_schemas.definitions` `mapdef.json` — `level_ref`, `field_a`, `tribe_ref` + `_tail_hex` |
| **Chapter** | `GameModeDefInternal::Chapter` | inside the game-mode def tail |
| **Sequence** | `GameModeDefaultDefinition`, `*.gamemodedefaultdef.ot` (library `Library_GameModeDefaultDefinition`) | `gamemodedefaultdef.json` — `field_a` + `_tail_hex` |

A run is a `GameModeDefaultDefinition`: an ordered list of chapters, each
referencing the map(s) it can roll. `GAME_END_NEXT_CHAPTER` advances it. The
"One chapter" modifier truncates the sequence to one — see
[Game modifiers](/reverse-engineering/game-modifiers/). "Current chapter" and
"Current map id" are entity-value keys
([Entity values](/reverse-engineering/entity-values/)).

## Sequence layout

The `GameModeDefaultDefinition` tail is a plain `u32 count` followed by `count`
× `u32` chapter index (vanilla `[0,1,2,3]`).

Deserializer-verified: `GameModeDefaultDefinition::Deserialize` reads the list via
`Serializer_ReadPolyPtrVector` into the ordered vector at `def+0x290`, and each
`GameModeDefault` entry is a resource-ref to its chapter content at `entry+0x8`.
So the u32s are sub-object ids into the file's section directory, and **the vector
order IS the run order as stored**.

## SDK kind (shipped)

```python
m.register("game_mode", id="ReverseRun", chapters=[3, 2, 1, 0])  # reorder
# [0,0,0] repeats biome 0; [3] is a one-chapter run.
```

`game_mode` (`src/rsmm/sdk/kinds/game_modes.py`, engine `game_mode_cook.py`),
confidence `experimental`. Indices must reference existing chapters (`0..3`).
Tests: `tests/test_game_mode_cook.py`.

**Proven route is override-in-place**: overriding the retail `All_Chapters` def at
its own cooked path with `chapters=[2, 3]` starts the run directly in the third
chapter — the engine honours the rewritten order, and skipping indices 0/1 hits no
first-run/tutorial coupling (`mods/SeedRunsChapter3`). A net-new *selectable* mode
id is still unproven, as are repeat orders like `[0,0,0]`.

A re-sequenced start is a *fresh* run — no items or talents from the skipped
chapters. Grant a loadout at run start with `R.give` if the mod wants one.

## Blackboard consumers

`FUN_1401da350` is the game-context **blackboard registrar**: it declares every
runtime cvar with a hashed id — `"Current chapter"` (`0x181d17fd`),
`"Current map id"` (`0x193495b8`), `"Random seed"` (`0x17a117c6`),
`"Reroll count"` (`0x1a922cd6`), the four biome map ids, and all
`GameModifier : …` flags.

Run-setup `FUN_1401eca80` (called from `FUN_14028e5f0` at "DayNightCycle
InitCycle") **reads** those modifier hashes via `FUN_1401c9600(ctx, hash)`, making
it the game-modifier consumer as well. The run reads `"Current chapter"` to index
the ordered vector at `def+0x290`.

## What each goal needs

- **Re-sequenced maps** — shipped (above). Determinism caveat: map selection is
  part of the seeded run state, so randomization must be *data-level* (edit the
  pool), never a per-peer runtime choice, or multiplayer desyncs — see
  [Multiplayer](/reverse-engineering/multiplayer/).
- **Brand-new map** — hard. A `mapdef` clone is cheap, but `level_ref` points at a
  cooked LEVEL (geometry, spawn volumes, nav); authoring one is far beyond a def
  edit. The realistic near-term "new map" is a **remix**: a new mapdef reusing an
  existing `level_ref` with a different tribe/reward profile.

## Open

1. Prove or rule out a net-new selectable game-mode id; test repeat orders.
2. Mapdef remix kind (clone + repoint `tribe_ref`).
3. New levels remain out of scope for def cloning.

---

# Melodies

> The Piper's lost melodies — a fully decoded def layout, the modifier-exclusion list, and why there can be no thirteenth melody.

Source: https://docs.rsmm.me/reverse-engineering/melodies/

:::note
Status: codec byte-stable over all 12 retail defs; `melody` SDK kind ships at
confidence `guess` (no in-game playtest yet). Class
`oe::dt::MelodyDefinition`, asset glob `*.melodydef.ot`.
:::

Codec: `cooked_schemas.definitions._dsl_spec("MelodyDefinition", "melodydef.json", …)`
— a generic DSL spec with byte-stable round-trip over **all 12** retail files
(`tests/test_melody_kind.py::test_all_retail_melodydefs_round_trip_byte_for_byte`).

:::caution
The Ghidra VAs below come from the MCP-attached program, a different/older build
than the live exe. Treat them as class-identity evidence, never as addresses to
bake into anything.
:::

- `oe::dt::MelodyDefinition::vftable` `0x140f29b70` (31 slots, deserialize-shaped)
- `oCTLibrary<oe::dt::MelodyDefinition>::vftable` `0x140f29af8`
- runtime: `MelodyEntityCpnt` `0x140ed74a0`, `MelodyProfileData` `0x140f00af0`,
  `MelodyUiViewerEntityCpnt` `0x140f2e910`

No function in the attached DB is named `*Melody*` — the deserializer is still an
unnamed `FUN_*`, so the field names below are mined from the **data population**,
not decompiled.

## Corpus

12 defs under `data/uncooked/Definitions/Melodies` (`Deal_Damage_Around`,
`Fully_Heal`, `Grant_Damage_Overtime`, `Increase_Fountain_Effect`,
`Increase_Move_Speed_At_Day`, `Instant_Level_Up`, `Power_Up_Level_Max`,
`Reduce_MO_Per_Collection`, `Refill_Sandman_Dreams`, `Remove_Key_Requirement`,
`Reveal_Map`, `Slow_Hourglass_Flow`). Each has a paired effect entity, cooked and
present: `EntitySettings\Objects\Melodies\<stem>.entity.ot.EntitySettingsResource.gen`.

## Decoded layout

The DSL spec exposes `field_a` + `entity_ref`; everything after is preserved
verbatim in `_tail_hex`. Parsing the tail across the corpus gives a completely
uniform shape:

```
field_a    u32     melody enum index
entity_ref tresptr ["EntitySettings", "Objects\\Melodies\\<stem>.entity.ot"]
--- _tail_hex ---
a          u32     4 | 5 | 6            (unknown; tier/weight?)
b          u32     always 3             (version tag?)
flags      u8 x3   varies per melody    (unknown)
guid       16B     unique per melody
           u32=1, u8=0                  (constant across all 12)
BEGIN(4)
  BEGIN(5) u32 count=0 END              (empty list, always)
  BEGIN(5) u32 count, lstr*count END    <- game-modifier exclusion list
END
```

`BEGIN`/`END` = `1111bbaa` / `2222bbaa`, the standard `ot_decoder` block framing;
the u32 after `BEGIN` is a class tag, not a length.

### `field_a` is a dense enum index

Across the 12 defs `field_a` takes the values `{0..11}`, each exactly once
(`test_field_a_is_a_dense_unique_enum_index`). It is an index, not free data.

### The trailing string list is game-modifier exclusions

Every string in every def is an exact stem of a file in
`data/uncooked/Definitions/GameModifiers`
(`test_every_retail_exclusion_is_a_real_modifier_stem`):

| Melody | Exclusions |
|---|---|
| `Fully_Heal` | `NightOnly`, `DayOnly`, `NoFeathers` |
| `Slow_Hourglass_Flow` | `NoBossTimer`, `OneChapter` |
| `Reveal_Map` | `NoMinimap` |
| `Increase_Fountain_Effect` | `NoFountains` |
| `Grant_Damage_Overtime` | `NoBossTimer` |
| `Power_Up_Level_Max` | `OneChapter` |
| (6 others) | *(empty)* |

The semantics read straight off the pairings: a melody is withheld when a run
modifier would make it meaningless (`Reveal_Map` under `NoMinimap`). **Direction
is inferred, not proven** — exclude-when-active fits all 12, but a whitelist
reading with an inverted flag elsewhere isn't ruled out.

## Why this kind is override-only

Same wall as [skins](/reverse-engineering/skins/) and heroes:

1. `field_a` is dense `{0..11}` — no free index for a 13th melody.
2. `Ui\Melodies` ships exactly 12 per-melody icons plus `_bg` / `_Hover` /
   `_Locked` chrome — a 1:1 match with the 12 defs.
3. The melodydef carries **no icon ref and no name/text ref**. The def→icon→name
   mapping is resolved outside the asset, by index or by name, somewhere the def
   cannot reach.

A net-new melodydef would deserialize but have no index, no icon and no label. The
kind doesn't attempt it — it edits the 12 that exist, as a plain retail override
(emitted at the vanilla decoded path; `rsmm apply` backs up + replaces).

## Levers the `melody` kind exposes

- `effect="<stem>"` — repoint `entity_ref` at another retail melody's effect
  entity. The melody keeps its own index, GUID, icon and name; only the granted
  effect changes.
- `exclude=[...]` — replace the modifier exclusion list (`[]` clears it). Unknown
  stems raise, as a typo guard against the `GameModifiers` corpus.

`field_a`, `a`, `flags` and `guid` are deliberately **not** exposed — the first
and last are identity, the middle two are unmined.

## Open

- **No in-game playtest of either lever** — that's why the kind is `guess`.
- `a` (∈ {4,5,6}) and the 3 flag bytes are unidentified. Candidates: unlock tier,
  chapter gating, day/night applicability.
- Exclusion-list direction (blacklist vs whitelist) unconfirmed.
- Corroborating *runtime* offsets exist from a read-only third-party melody
  overlay: melody GUID slots at scene-context `+0x760` (3 × 16B, slot order =
  unlock order), hero melody array at hero `+0x13a0` with u32 count at `+0x13a8`,
  melody state at cpnt `+0x68` (1 = collecting, 2 = completed), melody asset GUID
  at `+0x1c8`. The per-melody GUID in the def is the natural join key if a runtime
  `R.melody` API is ever wanted.

---

# Mod hooks

> Where the game creates, spawns, and loads things — the moddable surface.

Source: https://docs.rsmm.me/reverse-engineering/mod-hooks/

:::note
Status: **draft, derived from headless RE artifacts** under
`docs/_re/out/`. Use [GHIDRA_MCP.md](/reverse-engineering/ghidra-mcp/) to verify and
deepen anything below interactively.
:::

This document explains *why* asset edits weren't taking effect: the
game does not read loose definition files — it reads UID-keyed binary
records into singleton libraries at startup, and every "create item",
"spawn enemy", "instantiate boss" call goes through that registry.

## The two systems you need

### 1. The **class registry** (UID → factory)

Every serializable type registers itself on startup with a 32-bit UID,
a class-name string, a struct size, an alignment, a ctor thunk, and a
deserialization factory. The pattern (from
`FUN_140277790` registering `oCDtEntityCpntMagicalObjectsDropSettings`):

```c
local_38 = 0x168afca6;                           // class UID
lVar1   = FUN_1404f3bb0(0, &local_38);            // existing? lookup
plVar2  = FUN_1401a6c20();                        // allocate registry slot
(**(code **)(*plVar2 + 0xd8))(plVar2, 0xa50, 8);  // sizeof = 0xa50, align = 8
local_48 = "oCDtEntityCpntMagicalObjectsDropSettings";
(**(code **)(*plVar2 + 0x10))(plVar2, &local_48); // store name
*(undefined4 *)(plVar2 + 5) = 0x168afca6;         // store UID
FUN_1404f3c70(uVar4, plVar2, FUN_1402d2290);      // register factory
plVar2[0x10] = (longlong)&LAB_1401b6e70;          // ctor thunk
```

| Symbol | Meaning |
|---|---|
| `FUN_1404f3bb0(0, &uid)` | registry lookup — returns slot or 0 |
| `FUN_1401a6c20()` | allocate new registry slot |
| `FUN_1404f3c70(_, slot, factory)` | insert factory into hash table |
| `slot[5]` | UID (4 bytes) |
| `slot+0xd8 thunk` | set sizeof+align |
| `slot[0x10]` | ctor thunk pointer |
| `slot+0x10 thunk` | set class-name string |

**Where this matters for mods:** when the engine deserializes a cooked
record it reads the leading UID, looks the slot up, allocates
`sizeof` bytes, invokes the ctor thunk, then calls the factory to
populate fields from the byte stream. Without a registered UID the
record is silently skipped. Custom classes therefore need a
registrar call before any asset that mentions their UID is loaded.

The full table (706 classes, 337 with factories, 646 with sizes) is
saved as [out/class_registry.json](out/class_registry.json). The
short list below is the mod-relevant subset.

### 2. The **`oCTLibrary<T>` singletons** (runtime collections)

After a class is registered, the *instances* live in a per-type
template library. Each library is a singleton at a fixed global
address, has its own critical section, and exposes lookup + iteration
through its vftable. The library vftable is installed at static-init
(example for rewards, `FUN_14004adc0`):

```c
FUN_14048b230(&DAT_141412e00);
_DAT_141412e00 = oCTLibrary<class_oCDtRewardDefinition>::vftable;
_DAT_141412f70 = 1;
InitializeCriticalSectionAndSpinCount(&DAT_141412f80, 4000);
atexit(&LAB_140e73cd0);          // dtor on shutdown
```

Library singleton addresses are saved in
[out/libraries.json](out/libraries.json). The mod-relevant ones:

| Type | Singleton | Type UID | Record size |
|---|---|---|---|
| `oCDtRewardDefinition` | `0x141412e00` | `0x176f164e` | `0x298` |
| `oCDtEnemyDefinition` | `0x1414118c0` | `0x176debb7` | `0x350` |
| `oCDtEnemyTribeDefinition` | `0x141411200` | — | — |
| `oCDtEnemyCampTierDefinition` | `0x141411560` | `0x176e18f8` | `0x2a0` |
| `oCDtEnemyCampDifficultyDefinition` | `0x141411710` | — | — |
| `oCDtHeroDefinition` | *(via FUN_14032deb0 dtor)* | — | ≥ `0x2c4` |
| `oCDtMapDefinition` | `0x141412520` | — | — |
| `oCDtTileDefinition` | `0x141412080` | `0x1781ca4d` | `0x358` |
| `oCDtDreamShardDefinition` | `0x141411050` | — | — |
| `oCDtIngredientDefinition` | `0x141412c50` | — | — |
| `MelodyDefinition` | `0x1414129c0` | — | — |
| `oCEntitySettingsResource` | `0x141441b60` | — | — |
| `oCGlobalEntityValueSettings` | `0x141441980` | — | — |

`oCDtHeroDefinition`, `oCDtMapDefinition`, etc. with no UID column are
**not standalone records** — they live as nested definitions inside a
larger container, so they don't register their own UID.

## What "spawn" actually means

`oCEntitySpawner` (UID `0x17bcd54b`, size `0x60`) is the root spawn
primitive. Specialized spawners are *component-shaped* — they own an
`oCEntitySpawner` instance as an inner field. Confirmed for
`oCDtEntityCpntHeroSpawner` (`FUN_1402cce30`):

```c
*param_1     = oIEntityCpnt::vftable;
param_1[3]   = oe::EntityCpntValueSignal<bool>::vftable;
param_1[7]   = oe::EntityCpntValueSignal<bool>::vftable;
*param_1     = oCDtEntityCpntHeroSpawner::vftable;
param_1[0xd] = oCSpawner::vftable;        // → upgrades to oCEntitySpawner below
param_1[0xd] = oCEntitySpawner::vftable;
```

Layout per spawner-shaped component:

| Offset | Purpose |
|---|---|
| `+0x00` | derived `oIEntityCpnt` vftable |
| `+0x18` (param_1[3]) | "is active" bool signal |
| `+0x38` (param_1[7]) | "spawned at least once" bool signal |
| `+0x68` (param_1[0xd]) | embedded `oCEntitySpawner` instance |

So "spawning" is **not** `new Boss()` — it's:

1. Lookup target type in its library (`oCTLibrary<X>::Find(name)` —
   indirect via vftable slot).
2. Allocate an entity (size from registry slot).
3. Call ctor thunk → fills vftable chain.
4. Run deserialization factory against the library's stored byte
   record → populates fields.
5. Attach the resulting component to a parent entity in the scene
   graph.
6. Fire the `EntityCpntValueSignal<bool>` signals to wake listeners.

## Reward / item drop pipeline

`oCDtRewardDefinition` (`0x176f164e`, size `0x298`, factory
`FUN_14031a040`, library `0x141412e00`) is the data class for every
droppable reward type. The runtime walker is
`_InitAllRewards` = `FUN_1401e6030` (7351 bytes) — string
`"_InitAllRewards"` is stored at `0x140ef1a30` and used as a log tag.
Key strings it formats:

```
"Seed : {}"
"{} ({} reward spawners)"
"Reward type {}"
"Reward definition"
"Reward type item"
```

The function iterates over a list at `param_1 + 0x1d8`, pulls each
reward entry, queries its embedded spawner via a vftable dispatch
`(**(*plVar25 + 0x38))(plVar25, &local_288)`, and ends up building a
per-reward spawner table. The reward-selector component itself is
`oCDtRewardEntitySelectorToSpawnEntityCpntSettings` (factory
`FUN_1401e3e90`) — a thin wrapper around
`oIEntitySelectorToSpawnEntityCpntSettings` plus an
`oCCustomFlagList` for tags.

So "add a new item that can drop" requires:

1. A new `oCDtRewardDefinition` instance in
   `oCTLibrary<oCDtRewardDefinition>` (singleton `0x141412e00`).
2. A `oCDtRewardEntitySelectorToSpawnEntityCpntSettings` referencing
   it on whichever entity should drop it (boss kill, chest, etc.).
3. The selector's `oCCustomFlagList` tags must match the
   loot-table filter the dropper queries.

## Magical objects (in-run items)

Distinct from rewards — these are the *visible* magical pickup
entities. The component chain:

| Class | UID | Factory | Notes |
|---|---|---|---|
| `oCDtEntityCpntMagicalObject` | — | — | runtime entity component (ctor `FUN_1401e0e10`, 721 B) |
| `oCDtEntityCpntMagicalObjectsDropSettings` | `0x168afca6` | `FUN_1402d2290` | drop-table config, size `0xa50` |
| `oCDtEntityCpntMagicalObjectsDrop` | — | — | drop runtime — ctor at `FUN_140253e40` etc. |

The runtime component declares three `EntityCpntValueSignal<int>` at
offsets `+0x1f8`, `+0x218`, `+0x238` (param_1[0x3f/0x43/0x47]) —
likely rarity / count / level. The settings struct's `0xa50` size
suggests a sizeable drop table (dozens of weighted entries).

## Heroes

`oCDtHeroDefinition` has no registered UID — it is contained in a
parent record, and only its library singleton is observable. The
ctor `FUN_1403143b0` (1339 B) builds the inheritance chain:

```
oISerializable  →  oIResource  →  oCDtDefinition  →  oCDtHeroDefinition
```

It also writes two copies of `&DAT_140eb46d0` (a global empty-string
sentinel) at multiple member offsets — these are the named slots
(power IDs, talent IDs, melody IDs, animation IDs) waiting to be
populated by the asset loader. Each named slot is shaped:

```
ptr<char[]> name = &DAT_140eb46d0   // empty-string default
u32 hash = 0x80000000               // sentinel "unresolved"
u32 _pad = 0
```

The dtor `FUN_140314930` (1020 B) clears parallel pointer arrays at
`+0x114`, `+0x116`, `+0x118` (lengths at `+0x115`, `+0x117`, `+0x119`)
— these are the variable-length collections that get populated from
the asset bytes (likely lists of attached entities / powers /
talents).

To add a hero you either:

- Construct a new `oCDtHeroDefinition` post-ctor and inject into
  `oCTLibrary<oCDtHeroDefinition>` (host-side, before any code path
  iterates the library); or
- Subclass and register your own UID, then ship the asset record so
  the loader pulls it in via the normal path.

## Enemies & bosses

`oCDtEnemyDefinition` is fully registered: UID `0x176debb7`, size
`0x350`, factory `FUN_14030a190`, library `0x1414118c0`. Camp
machinery:

| 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 |

Bosses are not a separate class — they are enemies tagged via the
flag-list selector, gated by `oCDtBossTimerUiControllerEntityCpnt`
(string `"BossTimer update"` at `0x140f08a88`, ctor at `FUN_140368970`).

## Reproduction recipe

To regenerate or update the tables above after a game patch:

```bash
cd docs/_re/out
python3 - <<'PY'
import os, re, subprocess, json
r = subprocess.run(['grep','-rl','--include=*.c','-F','FUN_1404f3bb0','decompiled_all/'],
                   capture_output=True, text=True, timeout=120)
files = r.stdout.strip().splitlines()
recs = []
for f in files:
    body = open(f, errors='ignore').read()
    names = re.findall(r'"((?:oC|oS|oI|oe)[A-Z][A-Za-z0-9_<>:]+)"', body)
    uids  = re.findall(r'local_\w+\s*=\s*(0x[0-9a-f]{6,8})\b', body)
    fact  = re.search(r'FUN_1404f3c70\s*\([^,]+,[^,]+,(FUN_[0-9a-f]+)\s*\)', body)
    size  = re.search(r'\*plVar2\s*\+\s*0xd8\)\)\(plVar2,(0x[0-9a-f]+),', body)
    if names:
        recs.append({'fn': os.path.basename(f).split('__')[0],
                     'class': names[0],
                     'uid': uids[0] if uids else None,
                     'size': size.group(1) if size else None,
                     'factory': fact.group(1) if fact else None})
recs.sort(key=lambda r: r['class'])
json.dump(recs, open('class_registry.json','w'), indent=1)
print(len(recs), '→ class_registry.json')
PY
```

Library singletons can be re-extracted with:

```bash
grep -rh --include='*.c' -oE '_?DAT_[0-9a-f]+ = oCTLibrary<[^>]+>::vftable' decompiled_all/ \
  | sort -u
```

## MCP-confirmed engine internals (live RE)

The headless data above has been refined against a live Ghidra MCP
session against the same binary. Renamed functions in the Ghidra DB:

| Address | Renamed | Role |
|---|---|---|
| `0x1404f3bb0` | `oCMetaClass_FindByKey` | scan registry list for matching 32-byte key |
| `0x1401a6c20` | `oCMetaClass_Alloc` | malloc 0x90-byte oCMetaClass instance, install vftable |
| `0x140277790` | `Register_oCDtEntityCpntMagicalObjectsDropSettings` | sample registrar (kept as anchor) |
| `0x1404a3ad0` | `Register_oIBinarySerializationAccess` | binary deserializer interface registrar |
| `0x140488f50` | `LoadUsedRscList_or_Archive` | parses `UsedRscList.ot` manifest + Archive.ini |
| `0x140289b30` | `LevelGs_StateLoadingResource_Load` | master level-load orchestrator (14 stages) |
| `0x1401e6030` | `InitAllRewards` | builds per-reward spawner table from `MapSceneContext + 0x1d8` |

### Registry key is 32 bytes, not 4

The "UID" you see in registrars (e.g. `0x168afca6`) is the **first
4 bytes of a 32-byte key**. `oCMetaClass_FindByKey` compares all 32
bytes against an `oCMetaClass` vftable callout (`(**(*plVar2 + 0x20))`)
that emits the key on demand. The trailing bytes are zeros for nearly
every class today, but assume the full 32-byte slot when injecting.

### Three parallel registry arrays at `0x14140ded0..ee0`

| Global | Contents |
|---|---|
| `DAT_14140ded0` | `oCMetaClass*` list (one per registered type) |
| `DAT_14140ded8` | matching dtor/destroy thunks |
| `DAT_14140dee0` | matching schema-declarer callbacks (the third arg to `FUN_1404f3c70`) |

Each array stores `{ptr=elems, count, _, capacity}`. The schema
callback (e.g. `FUN_1402d2290` for `MagicalObjectsDropSettings`) is
**not** a deserializer — it sets the human-readable name + declares
the field schema. Actual binary deserialization happens through
`oIBinarySerializationAccess`-derived classes; the field schema is
consulted at read time.

### Schema-declarer pattern (confirmed)

```c
// FUN_1402d2290 — body of MagicalObjectsDropSettings schema callback
local_18 = "Magical Object Drops";          // user-facing display name
(**(*param_1 + 0x18))(param_1, &local_18);  // MetaClass::SetDisplayName
*(uint *)param_1[0x11] = 0xc0001;           // flags
FUN_1401c8b40();                            // register field group 1
FUN_1404f5700();                            // register field group 2
FUN_140215b10(param_1 + 6, ...);            // append to child list
```

### Level-load pipeline (`LevelGs_StateLoadingResource_Load`)

Confirmed stage table at `*(LevelCtx + 0x2b0)`:

| Stage | Label | Notes |
| --- | --- | --- |
| 0 | `LoadAndGetRandomHeroEntity` / `LoadAndGetPlayedHeroEntity` | loops `Map+0x720..0x728` random heroes + `Map+0x738..0x748` played heroes |
| 1 | `DayNightCycle InitCycle` | |
| 2 | `Barks manager loading` | |
| **3** | **`Enemies settings loading`** | walks `oCDtEnemyDefinition` list at `LevelCtx+0x198`, filters by tier (`uStack_5ac`), seed (`fStack_5a8`), and tag list (`oCCustomFlagFilter`, `EnemyDefInternal::SearchFilter`) |
| 4 | `MapDefinition loading` | |
| 5 | `TileDefinition loading` | iterates `Map+0x3c8..0x3d0` tile defs |
| 6 | `AddMasterLevel` | |
| 7 | `Update partitioning boundings` | |
| 8 | `Rebuild terrain` | |
| **9** | **`MapSceneContext OnLevelStart`** | calls `InitAllRewards(SceneContext)` and `FUN_1401e7e20(SceneContext)` |
| **10** | **`Generate rewards`** | fires `oCGameNamedEvent` keyed by `PTR_DAT_1412c0998` |
| 11 | `Rebuild navmesh` | |
| **12** | **`Generate enemy camps`** | fires `oCGameNamedEvent` keyed by `PTR_DAT_1412c09e0` |
| 13 | `Register game objects to sectorization` | |

### **The mod hook surface**

Stages 10 and 12 are **`oCGameNamedEvent` dispatches**, not direct
factory calls. That is the practical injection point:

- An entity listening for the "Generate rewards" event can spawn
  *additional* `oCDtRewardDefinition`-based entities into the level
  without patching `LevelGs_StateLoadingResource_Load`.
- Same for "Generate enemy camps" → custom camp spawns.
- For stage 3 (Enemies settings loading), the filter consults
  `EnemyDefInternal::SearchFilter` and `oCCustomFlagFilter`. Adding
  tags to a custom `oCDtEnemyDefinition` (UID `0x176debb7`,
  size `0x350`, library `0x1414118c0`) is sufficient to include it.

This finally explains why prior asset edits failed in isolation: the
*record* needs to exist in `oCTLibrary<oCDtEnemyDefinition>` AND the
camp's `EnemyCampEntitySelector` filter has to match its tags. Editing
one without the other no-ops silently.

### Hero library — still partially unknown

`oCTLibrary<oCDtHeroDefinition>` is referenced only by its dtor
(`FUN_14032deb0`). The init must happen via a runtime service
locator rather than a static global. `oCDtHeroDefinition` itself
**has no registered UID** — confirmed: its name string at
`0x140eddd78` only appears inside `Register_SkillProfileDataSettings`
(`FUN_140192330`, UID `0x186adbdf`) as a referenced field type. So
heroes are not standalone serializable records; they live as
typed-field children of larger settings classes.

## `oCTLibrary<T>` vftable ABI (= `oIResourceManager`)

Resolved against `oCTLibrary<oCDtRewardDefinition>` vftable @ `0x140f028b8`
and cross-checked against `oCTLibrary<oCDtEnemyDefinition>` vftable @
`0x140f022d0`. The library is a templated `oIResourceManager`: base
implements two shared slots, per-class slots override type info and
free-list pooling.

| Slot | Offset | Kind | Reward impl | Enemy impl | Renamed to |
|---|---|---|---|---|---|
| 0 | `+0x00` | per-class | `0x14032e120` | `0x14030c350` | `oCTLibrary_<T>__scalar_dtor` |
| 1 | `+0x08` | **base shared** | `0x14048baf0` | `0x14048baf0` | `oIResourceManager__detach_entry` |
| 2 | `+0x10` | per-class | `0x1401e3c80` | `0x1401db7e0` | `oCTLibrary_<T>__get_class_meta` |
| 3 | `+0x18` | **base shared** | `0x14048be40` | `0x14048be40` | `oIResourceManager__find_or_load_by_path` |
| 4 | `+0x20` | per-class | `0x14030be90` | — | `oCTLibrary_<T>__get_class_name_ref` |
| 5 | `+0x28` | per-class | `0x14032eb10` | — | `oCTLibrary_<T>__acquire_entry` |
| 6 | `+0x30` | per-class | `0x14030c770` | — | `oCTLibrary_<T>__release_entry` |
| 7 | `+0x38` | RTTI | — | — | end of primary vftable |

Base init / cleanup: `FUN_14048b230` / `FUN_14048b4a0` — renamed
`oIResourceManager__base_init` / `__base_cleanup`. Per-class
static-init thunks renamed: reward `0x14004adc0`
(`oCTLibrary_RewardDefinition__static_init`), enemy `0x140048e10`
(`oCTLibrary_EnemyDefinition__static_init`).

### Slot 3 = the by-name lookup (`Find(name)`)

`oIResourceManager::FindOrLoad(this, oCResourcePath*, flags, out_ref, extra)`
takes a path shaped `{ char* name, u32 hash, char* parent }`:

- If the path matches a 4-byte token at `DAT_140f1dab4` (likely an
  extension magic — TPI / TPDL), allocates a fresh entry via slot 5
  (`acquire_entry`), links it into the active list at `+0x140/+0x148`
  under the `+0x118` critical section, then ref-counts it into
  `*out_ref`.
- Otherwise calls `FUN_14048b600` (sibling lookup by parent path) and
  falls through to `FUN_14048d780` to materialize the resource.

Adding a `oCDtRewardDefinition` named `rwd_custom_sword` therefore
reduces to: construct an `oCResourcePath` with `name =
"rwd_custom_sword"` and the right parent, invoke
`(*reward_lib->vftable[3])(reward_lib, &path, flags, &out_ref, ...)`
— the base implementation allocates, links, and hands back a
ref-counted pointer.

### Library object layout (offsets used by base slots)

| Offset | Field |
|---|---|
| `+0x118` | active-list critical section |
| `+0x140` | active count |
| `+0x148` | active list tail |
| `+0x150` | active list head |
| `+0x158` | recent count |
| `+0x160` | recent list head |
| `+0x168` | recent list tail |
| `+0x170` | free-list head (slots 5/6) |
| `+0x180` | free-list critical section |

## Spawn primitive (confirmed)

See [`SPAWNING.md`](/reverse-engineering/spawning/) — `Spawn(this, position, &oCEntitySpawnData)`
is `vftable[3]` (byte `+0x18`) on the scene context's inline
`oCEntitySpawnerGo` dispatcher. Used by `SpawnAllObjects`
(`FUN_140254280`) and `SpawnAllMelodies` (`FUN_140255a90`); generic
across kinds. Sub-component lookup post-spawn is `FUN_1406ca380(go, meta)`.

## Still to be confirmed

- `oCGameNamedEvent` listener API — once we know how to register a
  listener, the "Generate rewards" / "Generate enemy camps" injection
  pattern is fully unlocked.
- `oIBinarySerializationAccess` runtime read path — UID
  `0x1c5258`, size 8, MetaClass singleton `DAT_1414494f0`. The path
  from raw cooked bytes to per-field reads via the schema declared in
  the schema callback is still uncharted.
- Hero library singleton address (see above).
- Reward weighting inside the 7 KB `InitAllRewards` body — header is
  understood (per-reward spawner table iteration), the inner
  weighting model is not.

---

# Multiplayer

> Disconnect, reconnect, and why a match closes when one player quits.

Source: https://docs.rsmm.me/reverse-engineering/multiplayer/

First-pass RE of why a Ravenswatch co-op match collapses when a player leaves,
and what is actually patchable. Source: live GhidraMCP session against the
shipped `Ravenswatch.exe` (addresses are image VAs, base `0x140000000`).

## Stack

Netcode is **Stormancer** (hosted P2P relay backend) layered over **Steam** +
**EOS**. Evidence: RTTI/strings `P2PStormancerConnection`, `oCStormancerSceneContext`,
`GameSession_Impl`, `PartyService::handleMemberDisconnected`,
`EP2PConnectionState`, `EOS_CET_Reconnection`, `SteamServersDisconnected_t`.
Implication: anything we change is client-side only; the Stormancer backend is
authoritative for session/party ownership, which bounds what a loader can do.

## There IS a built-in mid-match reconnection system

Ravenswatch already pauses the match on a drop and resumes on reconnect:

- Net messages `oCDtNetMsgMultiplayerReconnectPause` / `...Unpause`.
- UI `GameUis\Common_Ui\Reconnect_Notification.entity.ot`.
- `NetMsgReconnectOption`, `EOS: Next reconnection attempt in {} seconds`.

So a *transient* drop of a **non-host** peer is meant to be survivable. The pain
is (a) the reconnect window is short and (b) the **host** leaving is fatal.

## The per-peer connection state machine — `FUN_1402afaa0`

Ticks every peer in the global player array and drives `EP2PConnectionState`:

- Player array: base `DAT_141438fc0`, **stride 0x60**, count `DAT_141439140`.
  (A parallel pointer table `DAT_141439010`, stride 0xc qwords, indexes the same
  peers.)
- Per-peer connection-state enum at **`peer+0xCC`**: `3` = connected (skipped),
  others = `eConnecting/eInterrupted/eClosed/eClosing`.
- Per-peer timestamps: `peer+0xD0` (state-change time), `peer+0xD8` (reconnect
  window start). Elapsed seconds = `(QueryPerformanceCounter - ts) / DAT_14143b9c8`
  (perf freq).

### The timeout constants (baked config bytes — the levers)

Four single-byte values in `.data`, **only read here**, statically initialized
(no writer xref → compile-time constants). Defaults read straight from the
shipped exe:

| Addr | Default | Meaning (seconds) | Effect when elapsed ≥ value |
| --- | --- | --- | --- |
| `0x1412e5ed2` | **15** | interrupted → disconnect delay | peer goes `eInterrupted -> disconnect` |
| `0x1412e5ed5` | **5** | max **connecting** time | calls peer vtbl `+0x28` (stop) |
| `0x1412e5ed4` | **4** | reconnect-UI threshold | sets the "show reconnect notification" flag |
| **`0x1412e5ed3`** | **60** | **max reconnection time** | logs `"... -> stop - max reconnection time attempt"` → **`FUN_1402b4450(peer_idx)`** |

So a dropped non-host peer currently gets a **60-second** rejoin window (match
paused) before it is kicked. They are `uint8` seconds → max 255.

`FUN_1402b4450` = **remove that one peer** from the array (swap-with-last via
`FUN_1402b7000`, free via `FUN_1402b54b0`, `DAT_141439140--`). It does **not**
close the match — the remaining players continue. So extending `0x1412e5ed3`
lengthens the rejoin window for a dropped **non-host** peer; it never has to be
kicked if it returns in time.

## Why the WHOLE match still dies: host leave (no migration)

Two distinct flow-state keys exist:

- `Session_Disconnected_Go_To_Lobby` (140f0f318)
- `Session_Disconnected_From_Host_Go_To_Lobby` (140f0f3b8)

Neither has a direct string xref (they're flow-state keys resolved by
hash/table, not LEA). The second is the killer: when the **host** (Stormancer
session owner) leaves, there is no host-migration path, so every client is sent
to lobby. The reconnect state machine above only saves **non-host** peers.
**This is almost certainly what players hit** — the lobby host quitting.

## Verdict / feasibility

1. **Extend the rejoin window for non-host drops/quits — EASY, low risk.**
   Loader byte-patch `0x1412e5ed3` (and likely `_ed2`/`_ed5`) to a larger
   second count (bytes, so ≤255). Pure data write at a fixed RVA after module
   base — no detour needed. Net effect: a dropped player has up to ~minutes
   (match paused) to rejoin before being kicked. Open: confirm a clean "Quit to
   menu" routes a non-host through this reconnect path vs. a graceful-leave path
   that skips it (TODO: trace `PartyService::handleMemberDisconnected`).

2. **Survive the HOST leaving — HARD, maybe impossible client-side.**
   Needs host migration (elect a new Stormancer session owner). Stormancer is a
   hosted backend; ownership is likely server-enforced, so a client-only loader
   patch probably can't re-own the scene. Intercepting
   `Session_Disconnected_From_Host_Go_To_Lobby` to *not* go to lobby would leave
   clients in a dead scene. Requires deeper trace of `GameSession_Impl` /
   `oCStormancerSceneContext` ownership before any verdict.

3. **"Rejoin a match you intentionally left" — partially built-in, not full.**
   The reconnect/pause path covers returning within the window. A true late
   re-join of a match you cleanly left needs full state resync (run seed, entity
   state, progress) that the late-join path may never serialize. Unconfirmed.

## Confirmed addresses (rebase if the game patches)

| Symbol | VA | Role |
| --- | --- | --- |
| `FUN_1402afaa0` | `0x1402afaa0` | per-peer P2P connection-state tick |
| `FUN_1402b4450` | `0x1402b4450` | remove one peer from the session array |
| `DAT_1412e5ed3` | `0x1412e5ed3` | **max reconnection time (s)** — primary lever |
| `DAT_1412e5ed2/4/5` | `0x1412e5ed2/4/5` | interrupt-drop / UI / max-connect timeouts |
| `DAT_141438fc0` | `0x141438fc0` | player array base (stride 0x60) |
| `DAT_141439140` | `0x141439140` | player count |
| peer `+0xCC` | — | connection-state enum (3 = connected) |

## Shipped: reconnect-window extension (loader)

`src/loader/src/hook_netcode.cpp` (`install_netcode_patches`, wired in
`dllmain.cpp`) rebases `0x1412e5ed3` onto the live module and overwrites the
max-reconnection window. **Verify-then-patch**: it checks all four defaults
(`15/60/4/5`) are present first, so a game update that relocates `.data` is
detected and skipped rather than corrupting a random byte.

Arm it (opt-in, like the other engine hooks):

- env `RSMM_RECONNECT_SECONDS=1..255` (the new window), or
- touch `mods/.rsmm_extend_reconnect` (uses default 250 s).

**What this fixes:** a **non-host** peer that drops (crash / network blip) now
has up to ~4 min — match paused — for its client to auto-reconnect
(Stormancer/EOS already retry: `"Next reconnection attempt in {} seconds"`),
instead of being kicked at 60 s. That is genuine rejoin-after-drop.

**What it does NOT fix (still open):**

- **Host leaving** → `Session_Host_Abandon` /
  `Session_Disconnected_From_Host_Go_To_Lobby`. No *built-in* migration, and the
  window doesn't apply. The game is host-mastered: clients receive the session
  *from the host* (`StateWaitingP2PSessionFromHost`, `Can't find host info`,
  `Is Session Host`) and entity authority is host-owned (`Peer spawned … not
  master … Host or HostUnique`, `Host … replicates it to every other peer`).
  This is the common "whole match closes" complaint. **Whether it can be fixed
  client-side is re-assessed below** — short answer: hard but plausible, because
  the transport is a P2P *mesh* (connectivity survives) and authority is
  client-enforced, not server-validated.
- **Full quit → relaunch → rejoin.** A clean quit tears down the client's
  session token, so a relaunched process has nothing to reconnect to. Extending
  the window can't help; this needs a re-join-by-invite/late-join path that the
  game may not expose.
- The party layer (`PartyService`, member list at `party+0x158`,
  `FUN_1408ddae0` removes a member) is separate from the GameSession peer array.

## Host migration: hard but PLAUSIBLE (topology re-assessment)

Chasing the `HostAddress`/`HostPort` thread changed the earlier "impossible"
verdict. Findings:

- Transport is **RakNet** (full stack: `RakPeer`, `NatTypeDetectionClient`,
  `RakNet Startup: Port opened`). `HostAddress`/`HostPort` (default 60000) and
  `ReplicationInterval`/`TimeOut` are real `oe::UIntGameOption`s registered in
  `FUN_140414e80`.
- `-p2papi=` (parsed in `FUN_1401d16c0`) selects the signaling provider:
  `"stormancer"` or `"eos"` (string at `0x140f10528`), setting `DAT_1414371b8`.
  Both are matchmaking/NAT signaling over the *same* RakNet transport — there is
  **no** LAN/direct-IP provider that bypasses the backend.
- **Topology is a full P2P MESH, not a host-star relay**:
  `StateEstablishingP2PConnections`, `All P2P connections established`,
  `Sending ID_ALL_P2P_CONNECTIONS_ESTABLISHED to [peers]`, per-peer
  `Connecting to peer - GUID`. Every peer connects to every other peer.

Consequence: when the host leaves, **the remaining peers stay connected to each
other** — connectivity survives; only *authority* is lost. The backend is
matchmaking/signaling, not an authoritative server, and gameplay authority is
enforced **client-side** via `m_eMastership` (`oSCpntNetworkMastership::EType`,
Host/HostUnique) plus the session-host state machine (`FUN_14085b9d0`,
`Is Session Host`). `network.session.host` is telemetry, not the gate.

So host migration is a **hard, multi-week loader project**, not an architectural
wall. Sketch:

1. Hook host-abandon → suppress `..._Go_To_Lobby`, pause (reuse ReconnectPause).
2. Elect new host locally on every peer (deterministic, e.g. lowest peer GUID) —
   no negotiation; the mesh already agrees on the peer set.
3. On the elected peer: drive the session-host state (`FUN_14085b9d0` state →
   host) and begin mastering.
4. Flip `m_eMastership` of Host/HostUnique entities to the new host on all peers
   and force the replication tick to re-evaluate authority.
5. Resume — mesh is already connected, no reconnect needed.

### Unknowns #1 and #2 — RESOLVED (encouraging)

Per-entity replication setup = `FUN_140720c10` (logs the "not master" warning).
Authority is decided **once at replication-registration**, not per-frame:

```
role    = *(netmgr+0xf8)            // 1 = client/non-master
amOwner = entity->vtbl[0xd8]()      // local ownership check
if (!amOwner && role != 1) { ...replica path (mastership_query==0 -> "not master") }
else if (role != 2)        { FUN_140723a20(param_1);  // MASTER path: replicate-out }
```

- **#1 (runtime vs spawn mastership): spawn/registration-time.** A replica does
  not become master just by flipping `m_eMastership` mid-run. Migration must
  **re-register each entity's replication context** on the new host — flip the
  role field `netmgr+0xf8` to the master value and re-run the setup
  (`FUN_140720c10` / `FUN_140723a20`) per entity. Heavy but mechanical; the
  functions exist and are callable.
- **#2 (packet-origin validation): not a hard wall.** The transport is SLikeNet
  **ReplicaManager3** (`oCSLNetReplicationManagerSceneContext`), which is
  topology-agnostic: it deserializes a replica by id from whatever connection
  sends it; authority is the per-replica *master flag*, not a host-GUID lock. So
  once a peer legitimately becomes master (role flip + re-register), other peers'
  ReplicaManager3 will accept its updates. The gate is the game role field (#1).

Net: the core build problem is **re-registering replication as the new master**
(role flip + per-entity re-setup) under a host election, not a transport wall.

### Minimum-viable experiment (cheapest proof, before the full build)

Two clients. Force a role flip on the *client* and see if it can master an
entity the host owns:

1. Resolve `netmgr` (the object whose `+0xf8` is the role) and confirm host
   value vs client value (1) by reading it on each side mid-match.
2. On the client, after spawn, set `netmgr+0xf8` to the master value and
   re-invoke `FUN_140720c10`/`FUN_140723a20` for ONE simple replicated entity.
3. Observe on the host whether that entity now accepts the client's serialized
   state (ReplicaManager3 deserialize). Pass → migration is buildable; the rest
   is host election + doing this for all entities + teardown suppression.

Needs a loader call-gate to invoke those functions (the `rsmm.fn_call` surface
already exists) + 2 live clients. This isolates the whole risk in one test.

**Scaffolding shipped:** `rsmm.peek(addr[,size])` / `rsmm.poke(addr,val[,size])`
(page-state-guarded raw memory access, `src/loader/src/script_lua.cpp`) + the
`mods/NetcodeMigrationExperiment/` mod, which hooks `FUN_140720c10`, reads
`role = *(netmgr+0xf8)`, and logs it host-vs-client (Phase 1, read-only), with a
gated Phase 2 that flips the role. Inert until its flags are set. Run procedure
in that mod's `README.md`. This is the runnable form of the MVP above.

### Remaining unknowns (lower priority, after the MVP)

- **HostUnique** entities (host-only existence): re-master vs respawn on the new
  host.
- **Backend enforcement**: does eos/stormancer tear the session down when the
  *registered* host's signaling drops (`Session_Host_Abandon` pushed from the
  backend), regardless of client-side state? If yes, the teardown-suppression
  step must also absorb that backend event.
- **Role field source**: confirm what normally writes `netmgr+0xf8` (tie it to
  the session-host state in `FUN_14085b9d0`) so the flip is set the same way the
  game would.

Verdict: feasible to attempt, but needs the four unknowns resolved in Ghidra and
a **3+ live-client test harness** (cannot be validated from this repo). It is a
real project, not a quick patch.

## Next steps

- Read the default byte values at `0x1412e5ed2..5` (current window length).
- Trace `PartyService::handleMemberDisconnected` + the graceful-leave path to
  confirm which quits enter the reconnect machine.
- Trace the host-leave → `Session_Disconnected_From_Host_Go_To_Lobby` caller to
  scope host-migration feasibility (likely a dead end, but worth confirming).

---

# Cooked-format RE notes

> Field notes on Ravenswatch's cooked asset format, from live reverse engineering.

Source: https://docs.rsmm.me/reverse-engineering/notes/

Working notes for the modding pipeline (uncook ↔ cook). Living document — not a
spec. Update as schemas are filled in.

## Status

| Stage | Class / piece | Status | Owner file |
|-------|---------------|--------|-----------|
| 1 | Corpus dump (25 classes / 21k files) | done | `data/cooked_classes.json` |
| 2 | vtable + Serialize VA per class | done | `data/cooked_class_map.json` |
| 3 | Container codec (parse + emit, round-trip) | done | `src/rsmm/engine/cooked.py`, `tests/test_cooked_roundtrip.py` (450/450) |
| 4 | `oCTexture` schema (v1.14) | pending | — |
| 5a | `oCGeometry` container fields (v1.2) | done (this doc) | — |
| 5b | `oCMesh` submesh payload (was assumed `oCSubMesh`) | done (this doc) | — |
| 5c | `oCMeshBuffer` outer + unique-buffer path (v1.4) | done (this doc) | — |
| 5c.i | Per-stream `oSTriangleMesh`/`oCVec3VertexLayer` data layout | partial (this doc) | — |
| 5d | Per-instance / bone matrix list at +0x98 | partial (this doc) | — |
| 5e | `oCSkeleton` sub-object at +0x80 (was assumed index buffer) | pending | — |
| 6+ | Encoders & glTF bridge | partial (provisional decoder writable; encoder TBD until 5c.i closes) | — |

## Container codec

Both Type A (`.yqz/.gen`, `.tpi/.dxt`, `.zux/.nrm`) and Type B (stream
containers like `oCGameStream`) round-trip byte-stable. See module docstring
in `src/rsmm/engine/cooked.py`. Sections in the codec are raw payload blobs —
no per-class interpretation.

Asset containers carry **no CRC32**. CRC32 is `.ob` save-file only (see
ravensmith for that variant; not implemented here).

## Stream-vtable convention (confirmed across all 25 classes)

Param 2 of every `Serialize(this, stream)` call is a stream object whose
vtable indices are stable engine-wide:

| Slot | Method | Purpose |
|------|--------|---------|
| `+0x10` | begin-section helper | nested BEGIN/END section bracket on disk |
| `+0x20` | `is_reading()` → char | branch reader vs writer (0 = reading) |
| `+0x60` | string | u32 length + UTF-8 bytes (no NUL terminator) |
| `+0x70` | u8 / bool | 1 byte |
| `+0x78` | f32 | 4-byte IEEE 754 |
| `+0x90` | u32 / i32 | 4 bytes |
| `+0xa0` | embedded sub-object | nested Serialize() of an oC* class |

Helper functions called by Serialize bodies:

- `FUN_1404fbea0(stream, scratch, class_uid)` — version-gate helper. Returns
  a small struct; `*(u32 *)(ret + 4)` = saved schema version. Used as
  `if version < N: read_default_else_skip; else: read_from_stream` per field
  for migration.
- `FUN_1401c8720(stream, this_ptr)` — TResourcePtr / smart-ptr serialize.
- `FUN_14010c960`, `FUN_140312360`, `FUN_140115cb0`, `FUN_1402068e0` —
  string construct / append / move helpers.

## Class taxonomy (from manifest)

| Class | UID | Cur. version | Body size range | Use |
|-------|-----|--------------|-----------------|-----|
| `oCTexture` | 0x000016f6 | 1.14 | 46 B → 17.6 MB | All textures (.tpi/.zux/.yqz) |
| `oCGeometry` | 0x000016b8 | 1.2 | 200 B → 4.1 MB | 3D meshes |
| `oCMaterial` | 0x000016be | 1.28 | 159 B → 364 B | Materials |
| `oCAnimation` | 0x0000159d | 1.5 | 198 B → 35 KB | Animations |
| `oCCollisionMesh` | 0x0030986b | 1.3 | 1 KB → 32 KB | Collision |
| `oCEntitySettingsResource` | 0x16f5f7a3 | 1.0 | 49 B → 5 KB | Entity defs |
| `oCScheduledVfxSettings` | 0x0052992b | 1.2 | 22 B → 74 B | VFX timelines |
| `oCGameStream` | 0x014c31bf | 1.1 | 24 B → 22 KB | Level streams |
| `oCDt*Definition` (10 kinds) | various | various | small | Game data |

Full table + sample paths in `data/cooked_classes.json`. Vtable + Serialize
addresses in `data/cooked_class_map.json`.

## `oCGeometry` (v1.2) — partial schema

Decompile of `FUN_14064b0c0` (Serialize). Cooked file has TWO sections (one
from `oIResource::Serialize` parent + one from this).

### Section 0 — `oIResource::Serialize` output

4 bytes. Always observed as `00 00 00 00` in sampled v1.2 files. Likely a
resource-flags u32. Schema TBD (decompile of `oIResource::Serialize` at
vtable[3] of `oIResource`'s vtable, derivable from the same RTTI scan).

### Section 1 — `oCGeometry::Serialize` output

```
1. SubObject "bone/instance vector" at this+0x98
   - Read by FUN_14065a7c0(stream, this+0x98)
   - Layout:
       u32 zero_or_flags        (always 0 observed)
       u32 count                (or 0xAABB1111 marker for legacy schema)
       count * Element {
           f32 matrix[16]       (4x4 row-major transform, 64 B)
           lstring name_a       (u32 len + bytes, e.g. "Empty", "L_Locator")
           lstring name_b       (u32 len + bytes, often empty)
       }
   - When `count == 0xAABB1111`, a versioned header follows
     (string + 3 u32s) before the actual count.

2. u32 submesh_count       at this+0x90

3. u8 has_index_buffer     (computed write-side from this+0x80 non-null
                            AND *(this+0x80 +0xa0) != 0)

4. submesh_count * SubObject<oCSubMesh>  → vector at this+0x88
   (sub-object schema: TBD — see Stage 5b)

5. if has_index_buffer:
       SubObject<IndexBuffer>            → stored at this+0x80
       (schema: TBD — see Stage 5c)

6. version-gate (v >= 1):
       AABB { f32 xMin, yMin, zMin, xMax, yMax, zMax }   at this+0x68
       (confirmed via FUN_1404d4a60 = 6 consecutive f32 reads)

7. version-gate (v >= 2):
       struct { u32 = 0x01010000, u32 = 0x01010000, u8 = 1 }
       at local stack — looks discarded? May be migration flag set.
```

### Observed tiny-mesh payload (section 1, 208 B)

`LMN_RrlhSwli_Msqv_Grbgiruv.hap.Kqrxqius.yqz` (342 B file, decoded name has
"Grbgiruv" → "Locators" — locator group, hence no submeshes/indices):

```
u32 leading_zero        = 0
u32 element_count       = 2
Element 0:
  matrix4x4 (64 B)      = mostly identity-ish with translation
  lstring "Empty"       (4+5)
  lstring ""            (4+0)
Element 1:
  matrix4x4 (64 B)
  lstring "Empty.001"   (4+9)
  lstring ""            (4+0)
[trailing bytes]        — 5b 5c 5d ... 01 01 00 00 01 01 01
                          (AABB tail + v>=2 trailing struct, mostly zero
                          since this asset has no submesh data)
```

This confirms the bone/instance vector model. Larger meshes will have
submesh sub-objects + index buffer payload after the element vector.

## Sub-mesh class identification (Stage 5b — name correction)

The class embedded inside `oCGeometry` at offset `+0x88` (the submesh
std::vector) is **NOT** `oCSubMesh`. It is **`oCMesh`** (RTTI mangle
`.?AVoCMesh@@`, class UID `0x000016c0`).

Discovery: at the factory call in `oCGeometry::Serialize`,
`FUN_14049f0e0(&DAT_1414657e0, &DAT_14143ca10, ...)` invokes the resource
manager pinned to a `oCTLibrary<oCMesh>` instance. Verified by static
initializer at `0x140098620`:

```c
_DAT_1414657e0 = oCTLibrary<class_oCMesh>::vftable;
```

The second arg `&DAT_14143ca10` is NOT a class name — it is a small struct
of two `std::string`s holding the literal text `">DYN"` (an "anonymous /
dynamic resource" sentinel — see `FUN_14049f0e0` early branch:
`if (length == 4 && memcmp(name, ">DYN", 4) == 0) ...`).

RTTI search confirms there is no `oCSubMesh`, `oCSubmesh`,
`oCMeshSection`, or `oCGeometrySubMesh` symbol in the binary.

Related sub-object classes discovered while tracing this:

| Class | UID | Cur. version | Manager VA | Serialize VA | Role |
|-------|-----|--------------|------------|--------------|------|
| `oCMesh` | `0x000016c0` | 1.2 | `0x1414657e0` | `0x14064fdc0` | One per submesh inside `oCGeometry+0x88` |
| `oCMeshBuffer` | `0x000016c1` | 1.4 | `0x141465c80` | `0x140650a80` | Vertex+index buffer inside `oCMesh+0x70` |
| `oCMaterial` | `0x000016be` | 1.28 | `0x141465e30` | `0x14064c200` | Material at `oCMesh+0x68` (already resolved) |
| `oCSkeleton` | TBD | TBD | `0x14144af10` | `0x1405b4c40` | Sub-object at `oCGeometry+0x80` (was previously assumed to be an index buffer — wrong) |

All four were appended to `data/cooked_class_map.json`.

The `oCGeometry+0x80` correction matters: it is not an index buffer; the
mesh's index data lives inside `oCMeshBuffer`. The `+0x80` slot is the
mesh's optional skeleton (rig).

## `oCMesh` (v1.2) — schema

Decompile of `FUN_14064fdc0` (Serialize). One `oCMesh` instance per submesh
of the parent `oCGeometry`. Version-gate UID `0x16c0` is used as the
identity for `FUN_1404fbea0` lookups.

In-memory fields touched by Serialize:

| Offset | Meaning |
|--------|---------|
| `+0x68` | `TResourcePtr<oCMaterial>` (or owned `oCMaterial` if unique) |
| `+0x70` | `TResourcePtr<oCMeshBuffer>` (the actual vertex / index data) |
| `+0x78` | `std::string` — appears in v >= 2 only (name? optional tag?) |

Wire layout (writer / reader symmetric), in stream order:

```
1. bool material_is_default            (vtbl +0x70 — 1 byte)
     write-side computed as:
       material_is_default = ((*(this+0x68)) == NULL ||
                              (*(*(this+0x68)) + 0x48) == NULL)

2. branch on material_is_default:
   - true (no material / default):
       material is the engine default; nothing extra written.
   - false:
       branch on material's lifecycle:
       - shared resource ref (refcount > 1):
           TResourcePtr<oCMaterial> {
              lstring class_or_type_name
              lstring resource_path_or_id
           }                              (FUN_1401c8720 — 2x vtbl +0x60)
       - unique / inline (refcount == 1):
           SubObject<oCMaterial>          (vtbl +0xa0)
       - many-material edge-case:
           SubObject written into a chained binary stream via
           FUN_1404fd1c0 (oCBinarySaver + oCMemoryBinaryStream).
           Rarely seen — schema TBD.

3. SubObject<oCMeshBuffer>               (vtbl +0xa0)
     The vertex / index buffer for this submesh.

4. version-gate (v >= 2):
       lstring tag_or_name                (vtbl +0x60 at this+0x78)
     For v1.2 files this field is always present (current shipped
     version is 1.2 across all observed corpus).
```

Cross-checks against a real sample (see "Sample" below) suggest the
material/meshbuffer ordering is: material subobject bracket first,
meshbuffer subobject bracket second.

## Stream-vtable convention update (verified during Stage 5c)

While tracing `oCMeshBuffer::Serialize` and the named-instance reader
`FUN_1404cb570` against a real sample, two additional vtable slots and one
side-effect were nailed down:

| Slot | Method | On-disk emission (binary stream) |
|------|--------|----------------------------------|
| `+0x38` | schema annotation (takes a string like `"typeof(oCTVector<t_Object>)"`) | **0 bytes** — annotation only |
| `+0x40` | blob read/write (`(stream, data_ptr, byte_count, "Bytes")`) | **`u32 byte_count`** prefix, then `byte_count` raw bytes |
| `+0x60` | `lstring` (length-prefixed UTF-8 string) | `u32 len`, then `len` bytes (no NUL) |
| `+0x68` | `u8` (separate from the bool slot at `+0x70`; used for typed flags/modes) | 1 byte |

This rewrites the prior assumption that `+0x40` was a raw `count*N` blob
with no header. The byte-prefix from `+0x40` is what shows up as the second
`u32` we kept seeing inside vertex-stream payloads (= `count * stride`).

## `DAT_1412efa50` — engine default-buffer signature

A 64-byte (16-float) block at `0x1412efa50` in `Ravenswatch.exe`. Reading
the bytes via `pefile`:

```
1.0  0.0  0.0  0.0
0.0  1.0  0.0  0.0
0.0  0.0  1.0  0.0
0.0  0.0  0.0  1.0
```

**It is the 4x4 identity matrix.** `oCMeshBuffer::Serialize` uses
`memcmp(&DAT_1412efa50, *(this+0x78)+0x10, 0x40)` to test whether this
buffer's stored transform equals the engine's identity-default. If yes
(plus `*(this+0x80) == 1`), the buffer is treated as shared-default and
`unique_flag` is written as `0`; otherwise `unique_flag = 1` and a full
unique buffer is written.

## `oCMeshBuffer::Serialize` (v1.4) — full outer schema

Decompile of `FUN_140650a80`. Confidence: **high** for the outer envelope;
**medium-low** for the per-stream payload (see Stage 5c.i below).

### Parent prelude (written by the dispatch wrapper, not by `FUN_140650a80`)

```
u32 oIResource flags / reserved      (4 B)   — empirically 6 for our sample;
                                                value semantics still TBD
```

### Self body (`FUN_140650a80`)

```
1. u8  unique_flag                          (vtbl +0x70)
     write-side computed as:
       if (*(this+0x80) == 0) OR
          (*(this+0x80) == 1 AND
           memcmp(*(this+0x78)+0x10, IDENTITY_4x4, 64) == 0)
         unique_flag = 0
       else
         unique_flag = 1

2. version-gate (v < 4 — legacy path; not emitted by current shipping files):
     - acquire default oSTriangleMesh at this+0x68 via FUN_1404d22b0
       (= FUN_1404d7cc0 alloc + FUN_1404d2150 push with identity matrix)
     - read named-instance via FUN_1404cb570(*(this+0x68), stream, "<no name>")
   v >= 4 — current 1.4 path:
   if unique_flag == 0:
       ensure default mesh struct exists at this+0x68 (FUN_1404d7cc0
       allocates a stub `oSTriangleMesh`, FUN_1404d2150 pushes it with an
       identity per-draw matrix taken from DAT_1412efa50)
       read named-instance via FUN_1404cb570(*(this+0x68), stream, "<no name>")
   if unique_flag == 1:
       read full unique buffer via FUN_1404d1e30(this+0x68, stream)

3. AABB (v >= 1):
     FUN_1404d4a60(stream, this+0x90) — 6 consecutive f32 reads
     { f32 xMin, yMin, zMin, xMax, yMax, zMax }

4. f32 (v == 2 ONLY): vtbl+0x78(stream, local, 0) — value discarded on read.
   Absent for v >= 3 files.

5. f32 (v >= 3): vtbl+0x78(stream, this+0xc8, 0) — stored at this+0xc8
   (semantically a "level-of-detail factor" or "shadow-bias"-style scalar — TBD).
```

The `"<no name>"` literal is the **call-site argument** to `FUN_1404cb570`;
it is NOT written to disk by `FUN_1404cb570` itself. The named-instance
reader uses it as a default annotation label for error messages and in
text-stream mode only.

## `FUN_1404d1e30` (unique-buffer reader) — schema

Decompile reads:

```
u32 leading_flag = 1            (always 1 on disk — set by writer as a literal)
u32 stream_count                (number of vertex-stream sub-objects)
stream_count * SubObject<oCTStream>   (each via FUN_1404cb570(stream_obj, "<no name>"))

u32 draw_count                  (number of per-draw entries)
draw_count * {
    u32 stream_index            (index into the stream array above)
    f32 matrix[16]              (4x4 transform — 64 B)
}
```

The on-disk per-draw struct is `4 + 64 = 68 bytes`. In memory the layout is
0x50 (80 bytes) because the runtime caches the resolved `stream_ptr` at
+0x00 and stores the stream_index at a +0x04 cursor. On disk, only the
stream_index (u32) and matrix (16 f32) are serialized — total 68 B per draw.

## `FUN_1404cb570` — the named-instance reader

This is **not** `oCVec3VertexLayer::Serialize`. It is a generic serializer
for "stream / triangle-mesh" objects whose schema version is its OWN field
(`local_res10[0]`), independent of the surrounding class's version.

The current shipped version (set by the writer as `dword ptr [RBP + 0x6f], 0x7`)
is **7**. The third argument (a C-string like `"<no name>"`) is a label only,
not emitted to disk by this function.

### Layout for `ver == 7`, uncompressed mode (`*(param_1 + 0x49) == 0`)

```
u32 ver = 7                            (vtbl +0x90, always emits 7 on save)
u8  comp_mode at +0x49                 (vtbl +0x68)
                                         0 = uncompressed
                                         1 = quantized-20B-per-vertex
                                             (via FUN_1404c3440)
                                         2 = quantized-18B-per-vertex
                                             (via FUN_1404c3dc0)
[ comp_mode == 0 (uncompressed path): ]
  vtbl +0x38("typeof(oCTVector<t_Object>)")   — annotation, 0 bytes
  u32 count                            (= *(param_1 + 0x10); element count)
  u32 byte_size                        (= count * 0x30 — emitted by vtbl +0x40
                                         as its blob length prefix)
  byte_size bytes of element data      (stride 0x30 = 48 B per element;
                                         element layout TBD — see Stage 5c.i)

  Then a trailing tail:
  lstring annotation                   (vtbl +0x60 of an empty/symbolic string,
                                         observed empty in sample)
  (v >= 2) vector<ptr> at +0x38        (via FUN_14020d700; element stride 8 B
                                         = ptrs, each ptr serialized via
                                         vtbl +0xa8 = sub-object)
  (v == 4 only) 16 f32                 (a 4x4 matrix; absent for v == 7)
```

### Layout for older versions

- `ver == 1`: full default-case branch — includes tangent / binormal
  side-channel allocation (`FUN_1404c4f10`, `PTR_s_tangent_1412ef988`,
  `PTR_s_binormal_1412ef978`) and a sub-resource named "skinning"
  (`PTR_s_skinning_1412ef958`). This is where the `"tangent"` /
  `"binormal"` strings come from in older content. Not used by v1.4 files.
- `ver == 2`: just `FUN_1404d62e0` (vector of 0x30-byte elements with the
  same BEGIN-style versioning header as `oCTVector<t_Object>`).
- `ver in [3,4,5,6,7]`: the modern path described above. v < 5 still uses
  `FUN_1404d62e0`; v >= 5 switches to the typeof+u32+byte-blob form.

### Quantized vertex paths (`comp_mode == 1` or `2`)

These take a `local_res18` parameter passed down from the caller (`*(param_1 + 0x10)`).
For oCMeshBuffer's default-buffer call, the caller passes an `oSTriangleMesh`
where +0x10 holds the vertex count, so `local_res18` ends up being count.

- **mode 1** (`FUN_1404c3440`) — 20 bytes per vertex:
  - 3 * u16 quantized position (using mins/maxes from a header bbox)
  - 3 * u16 quantized normal (Lambert-style packing into 6 bytes)
  - 1 * u32 packed tangent + extras (`FUN_140516d70` produces it from f32x4)
  - On-disk header: 3 + 3 + 3 + 3 + 3 f32 (5 vec3 mins/maxes — 60 B), then
    count * 20 B = data.
- **mode 2** (`FUN_1404c3dc0`) — 18 bytes per vertex:
  - same as mode 1 but normal/tangent packed differently (octahedral?)
  - on-disk header: 3+3 f32 bbox + 2 f32 quant scales + extra u8 byte
    descriptors + 3+3+3 f32 mins/maxes (~72 B), then count * 18 B = data.

These quantized paths are produced by the engine cooker when the source
mesh has vertex data — they're the format used by skinned / static
geometry. The decoder needs to dequantize back to f32 for round-trip.

## Stage 5c.i — per-stream element layout (still partial)

The 48-byte element written by FUN_1404cb570's uncompressed path is the
in-memory "vertex" struct held by an `oSTriangleMesh` (or similar). 48 B
matches:
- `12 B position (f32x3)`
- `12 B normal   (f32x3)`
- `8  B uv0      (f32x2)`
- `4  B color    (u8x4)`
- `12 B tangent  (f32x3)`
  → 48 B total

…but the exact field order, signedness, and whether tangent is packed has
not been independently verified by reading f32 values out of the sample
yet. The sample's `oCMeshBuffer` is the default-buffer path with a stub
`oSTriangleMesh` (8 triangles, 24 indices, identity matrix) and shows
small per-vertex floats that *look* like a 48-byte format but could also
be the v=7 default with an inner array of indices + tail of vertices.
Marking as TBD — Stage 5c.i.

## `oCVec3VertexLayer` (v1.2) — schema

Decompile of `FUN_1404ddd80` (the self body). Parent serialize is
`oIVertexLayer::Serialize` at `FUN_1404ddb70`, which only writes one field:

### `oIVertexLayer::Serialize` (v1.0)

```
lstring name      (vtbl +0x60 at this+8 — the layer's textual name,
                   e.g. "binormal", "tangent", "position", "normal", ...)
```

### `oCVec3VertexLayer::Serialize` (v1.2, self body)

UID for `FUN_1404fbea0` version-gate lookup is `0xd43924b`.

```
[ v < 2 (legacy) ]:
  FUN_14012afd0(stream, this+0x18)
    — reads a length-prefixed std::vector<oCVec3>:
      u32 count
      count * { f32 x, f32 y, f32 z }    (12 B each)

[ v >= 2 (current) ]:
  u8 comp_mode at this+0x28              (vtbl +0x68)
       0 = uncompressed / fall through
       1 = quantized 8 B per vertex
       2 = empty (skip — schema returns 1, no data)

  comp_mode == 1:
    u32 count at this+0x20               (vtbl +0x90)
    FUN_1404d4550(this+0x18, count, 1)   — resize array to count
    FUN_1404b3d40(stream, this+0x18)     — read quantized stream:
      f32 bbox xMin
      f32 bbox xMax
      f32 bbox yMin
      f32 bbox yMax
      f32 bbox zMin
      f32 bbox zMax
      count * { u16 qx, u16 qy, u16 qz }  (6 B per vertex)
      (dequantization: f = qx / 65534.0 * (xMax - xMin) + xMin)

  comp_mode == 2:
    (no data — returns success immediately; in-memory vector left empty)

  comp_mode == 0:
    (v < 2 only) FUN_14012afd0  — legacy vec3 list (per above)
    vtbl +0x38("typeof(oCTVector<t_Object>)")  — 0 bytes
    u32 count at this+0x20                     (vtbl +0x90)
    resize array to count                       (FUN_140cb5f70 zero-fill)
    vtbl +0x40 blob:
      u32 byte_size = count * 12
      count * { f32 x, f32 y, f32 z }
```

The `name` lstring written by the oIVertexLayer parent identifies the
semantic ("binormal", "tangent", "position", "normal", "uv0", "color", ...).

### Sample verification (`binormal` side-channel, section 1 of our sample, 313 B)

Confirmed byte-stable parse:

```
0000: u32 oIResource prelude    = 7
0004: u32 lstring name len      = 8
0008: 8 bytes "binormal"
0010: u8  comp_mode             = 0    (uncompressed)
0011: u32 count                 = 24   (vertex count, at +0x20)
0015: u32 byte_size             = 288  (= 24 * 12, vtbl +0x40 blob prefix)
0019: 288 bytes = 24 * vec3(f32)
      vertex[0]  = (0.0, 1.6e-07, 1.0)
      vertex[1]  = (0.0, 1.6e-07, 1.0)
      ... (4 verts of same)
      vertex[4]  = (-1.0, 0.0, 0.0)
      ... (a few unit-vector reorderings — looks consistent with per-face
            tangent-space binormals of a unit cube's 24 corner vertices)
```

Total: `0x19 + 288 = 0x139 = 313 B` ✓.

Section 2 (`tangent`) follows the identical schema — 312 B total because
"tangent" is 7 chars not 8.

## `oIVertexLayer` (v1.0) — schema

```
lstring name      (vtbl +0x60 at this+8)
```

Trivially short; the bulk of the data lives in derived classes
(`oCVec3VertexLayer`, `oCVec2VertexLayer`, `oCVec4VertexLayer`,
`oCFloatVertexLayer`, `oCSkinning8VertexLayer`, `oCSkinning16VertexLayer`).

### Discovered VAs (Stage 5b/5c)

| Class | UID | Cur. version | Serialize VA | Parent |
|-------|-----|--------------|--------------|--------|
| `oIVertexLayer` | `0xd3e6496` | 1.0 | `0x1404ddb70` | `oISerializable` |
| `oCVec3VertexLayer` | `0xd43924b` | 1.2 | `0x1404ddd80` | `oIVertexLayer` |
| `oCVec2VertexLayer` | TBD | TBD | TBD | `oIVertexLayer` |
| `oCVec4VertexLayer` | TBD | TBD | TBD | `oIVertexLayer` |
| `oCFloatVertexLayer` | TBD | TBD | TBD | `oIVertexLayer` |
| `oCSkinning8VertexLayer` | TBD | TBD | TBD | `oIVertexLayer` |
| `oCSkinning16VertexLayer` | TBD | TBD | TBD | `oIVertexLayer` |
| `oSTriangleMesh` (internal) | n/a | n/a | n/a (uses `FUN_1404cb570`) | — |

The skinning / vec2 / vec4 / float layer classes share the same
parent-then-self pattern; their bodies are simpler variants of
`FUN_1404ddd80` with different element sizes (likely 8, 16, 4 B
respectively). Decompile pending.

## `oCSkeleton` (?) — TBD (Stage 5e)

Sub-object at `oCGeometry+0x80`. Was previously believed to be an "index
buffer" — that was wrong. Schema is fully TBD. Serialize VA = `0x1405b4c40`,
vtable VA = `0x140f53fc0`. Class UID still TBD (not seen in any cooked
class table yet — likely only present in skinned-mesh `.yqz` files).

## Sample dump (worked example)

A full byte-level walkthrough of one cooked `oCGeometry` file. Collapsed by
default — expand for the raw class table, section map, and annotated buffer.

<details>
<summary>Sample dump: <code>3N/NqbglSwaq_1p1.hap.Kqrxqius.yqz</code> (2550 B, v1.2 oCGeometry)</summary>

Class table (from cooked container):

```
oCGeometry         id=0x16b8  v=1.2  parent=oIResource
oIResource         id=0x17b6  v=1.1  parent=oISerializable
oISerializable     id=0x1da16c v=1.0 parent=0xffffffff
oCMesh             id=0x16c0  v=1.2  parent=oIResource
oCMaterial         id=0x16be  v=1.28 parent=oIResource
oCShaderParamSet   id=0x2630f82 v=1.0 parent=oISerializable
oCMeshBuffer       id=0x16c1  v=1.4  parent=oIResource
oCVec3VertexLayer  id=0xd43924b v=1.2 parent=oIVertexLayer
oIVertexLayer      id=0xd3e6496 v=1.0 parent=oISerializable
```

Top-level cooked container sections (Type B, four sections):

| idx | bytes | content |
|-----|-------|---------|
| 0 | 12 | u32(2), u32(7), u32(7) — TBD (likely an `oIResource` parent header) |
| 1 | 313 | `oCVec3VertexLayer` "binormal" payload (vertex stream side-channel) |
| 2 | 312 | `oCVec3VertexLayer` "tangent" payload |
| 3 | 1573 | `oCGeometry` main body (bone vector + 1 submesh sub-object) |

Section 3 internal bracket map (BEGIN = `0xAABB1111`, END = `0xAABB2222`,
both written aligned by the engine's `+0x10`/`+0x18` stream helpers when
a subobject `+0xa0` write is in progress):

```
off    event       depth
----   ---------   -----
0      raw         —      u32(0), u32(0), u32(1), u8(0)   (oCGeometry self prelude, 13 B)
13     BEGIN       1      open oCMesh submesh subobject
  17     raw       —      u32(3), u8(1)                   (oCMesh prelude: TBD interpretation)
  22     BEGIN     2      open material subobject
    26     raw     —      u32(4), u32(0)
    34     BEGIN   3      (empty inner — schema TBD)
    38     raw     —      u32(5), u32(0)
    46     END     3
    50..132 ~80 B  —      material payload (oCMaterial + oCShaderParamSet)
  133    END       2      close material
  137    BEGIN     2      open oCMeshBuffer subobject
    141..1515 ~1374 B raw  vertex / index buffer (sample analysis below)
  1516   END       2      close oCMeshBuffer
1532   END         1      close oCMesh submesh
1532..1572 ~40 B —        oCGeometry trailing fields (AABB f32x6 + v>=2 trailing struct)
```

Annotated oCMeshBuffer payload (`offset 141..1515`, 1375 B inside section 3):

```
+0000: 06 00 00 00   u32  oIResource prelude  (= 6; flag semantics TBD)
+0004: 00            u8   unique_flag = 0  → default-buffer path
+0005: 07 00 00 00   u32  FUN_1404cb570 ver = 7  (current shipped)
+0009: 00            u8   comp_mode = 0   → uncompressed path
+000a: 18 00 00 00   u32  count = 24       (= *(stream + 0x10);
                                              for an oSTriangleMesh this
                                              field is "triangle/index count")
+000e: 0c 00 00 00   u32  byte_size = 12   (vtbl +0x40 blob length prefix)
                          ⚠ but count * 0x30 = 1152, not 12. The 12 here
                          does NOT match the asm-derived `count * 48` byte
                          size. Either:
                            (a) the asm-stride 0x30 is wrong for the
                                default-buffer-path's oSTriangleMesh;
                            (b) the vtbl +0x40 prefix is in elements not
                                bytes, with stride being implicit;
                            (c) there is an intermediate header u32 here
                                I'm misreading.
                          Marking as Stage 5c.i TBD pending more samples.
+0012..0x027  24 * u32   small ints 0,1,2,2,1,3,4,5,6,5,4,7,8,9,a,9,8,b,
                         c,d,e,d,c,f
                         → looks like 24 triangle-list indices (8 tris)
                         → if true, these are 24 * 4 = 96 bytes, but the
                           "byte_size = 12" doesn't match either reading.
+0072..       12 * (f32 x, f32 y, f32 z)  candidate vertex positions
                                          for the 8-triangle indexed mesh
... trailing tail with more f32s and the lstring annotation that closes
    FUN_1404cb570
+0530 (1328 bytes in): final two f32 = 0x3f800000 0x3f800000 (1.0, 1.0)
+1373..1374: 00 00  (likely the empty trailing lstring annotation
                    + the vtbl +0x60 NUL terminator behavior)
```

The exact stride and byte layout of the per-element vertex / triangle data
inside FUN_1404cb570's uncompressed-mode blob is the remaining unsolved
piece for closing the encoder. The decoder can still extract positions
(starting from the post-index region) and indices empirically — see
`docs/MODDING.md` once the helper is shipped.

The triangle-list indices `0,1,2,2,1,3,4,5,6,5,4,7,8,9,a,9,8,b,c,d,e,d,c,f`
form a sensible quad-strip pattern for the 6 faces of a cube
(each face = 2 triangles sharing an edge → 8 triangles × 3 indices = 24).

</details>

## Outstanding sub-class schemas (Stage 5b / 5c / 5d / 5e)

Done in this update:
- `oCMesh` (v1.2) schema — field-by-field above. (Stage 5b done)
- `oCMeshBuffer` (v1.4) outer envelope — `FUN_140650a80` fully decompiled
  and matched against sample. (Stage 5c done)
- `FUN_1404d1e30` unique-buffer reader — fully decompiled. (Stage 5c done)
- `FUN_1404cb570` named-instance reader — schema mapped per version stamp
  (1..7), including the three compression modes for v >= 3.
- `oCVec3VertexLayer` (v1.2) + `oIVertexLayer` (v1.0) — schemas added.
- `DAT_1412efa50` is the 4x4 identity matrix used as the engine's
  default-buffer signature.
- Stream-vtable convention table updated: `+0x40` blob writes are
  length-prefixed.

Still TBD:

- **`oIResource::Serialize`** — the universal parent prelude. Section 0 of
  our sample is `u32(2), u32(7), u32(7)` (12 B), and the meshbuffer
  payload starts with `u32(6)`. These look like a `(major, minor, hash)`
  triple but the writer code has not been decompiled yet. Decompile of
  `oIResource::Serialize` (vtable[3] of `oIResource`'s vftable, derivable
  from the same RTTI scan that resolved everything else).
- **Stage 5c.i — per-stream element layout inside `FUN_1404cb570`'s
  uncompressed mode** — the asm consistently computes `byte_size = count
  * 0x30`, but the sample shows what reads as `count = 24, byte_size =
  12` plus a stream of u32 indices afterward. Either the stride is
  context-dependent (oSTriangleMesh stores 12-byte stride after all,
  with 0x30 being a memory-side packing) or there's an intermediate
  header u32 we're misreading. Cross-validation with a larger sample
  (e.g. a 50 KB+ `oCGeometry` with multiple submeshes) should
  disambiguate.
- **`oCSkeleton` payload at `oCGeometry+0x80`** — schema is fully TBD.
  Only present for skinned meshes (skeleton-bound; this sample does not
  have one). Serialize VA = `0x1405b4c40`.
- **Trailing struct `{u32=0, u32=0x01010000, u32=0x01010000, u8=1}`** in
  oCGeometry — confirmed byte layout from sample (13 B total at end of
  section 3, after the AABB). Semantic of those constants is still TBD;
  they look like a "version-tag triple + flag" but their writer hasn't
  been decompiled yet.
- **Many-material edge case in `oCMesh`** — `FUN_1404fd1c0` chains an
  `oCMemoryBinaryStream` for the material write. Schema unknown.
- **Quantized-vertex paths' exact header bytes** — `FUN_1404c3440` (20 B
  per vertex) and `FUN_1404c3dc0` (18 B per vertex) emit non-trivial
  header structs (bboxes, octahedral packing tables). The Ghidra decompile
  was sketched in this work but not byte-validated against a quantized-mode
  sample. Any non-default-buffer mesh in the corpus will exercise these.
- **Semantic of top-level container sections 1+2** ("binormal", "tangent"
  side-channels) — the schema is now solved (they are `oCVec3VertexLayer`
  full Serialize outputs), but the question of WHY they appear as
  top-level sections instead of nested sub-objects of the meshbuffer is
  unresolved. Hypothesis: they are emitted by an `oCBinarySaver`
  pre-pass when the cooker decides this mesh needs auxiliary tangent
  space, with the container writer storing each in its own section so
  they can be streamed lazily (per-batch) at runtime. Decompile of the
  cooker call site for `PTR_s_tangent_1412ef988` / `PTR_s_binormal_1412ef978`
  would confirm.

Each remaining item requires:
1. RTTI scan (already have `python -m rsmm.dev.ghidra_resolve`).
2. Ghidra MCP decompile of vtable[3].
3. Field-by-field validation against a sample payload.

## Tools added in this work

- `src/rsmm/dev/cooked_manifest.py` — corpus scan → class manifest.
- `src/rsmm/dev/ghidra_resolve.py` — PE RTTI scan → vtable + Serialize VAs.
- `src/rsmm/engine/cooked.py` — container codec (parse + emit).
- `tests/test_cooked_roundtrip.py` — byte-stable round-trip across .yqz /
  .tpi / .zux (450 files sampled per run).

## Stage 5c.i — FUN_1404cb570 per-element stride (SOLVED)

Inner reader `FUN_1404d7d30` (called by ver<5 path `FUN_1404d62e0`) issues
12 consecutive stream `+0x78` (f32) reads per element: 8 inline + 4 via
`FUN_140126e40`. Per-element stride = **48 bytes (0x30)** = 12 f32:

| Offset | Field        | Type      |
|--------|--------------|-----------|
| 0x00   | position     | vec3 f32  |
| 0x0c   | normal       | vec3 f32  |
| 0x18   | uv0          | vec2 f32  |
| 0x20   | tangent      | vec3 f32  |
| 0x2c   | handedness   | f32       |

For ver>=5 uncompressed path, the same 0x30 stride is emitted as one
`vtbl+0x40` length-prefixed blob (`u32 byte_size = count*0x30`). Confirmed
against two real samples.

Earlier `count=24, byte_size=12` misread was a different path: ver>=7
`FUN_1404cb570` has two data sections — a u32 count at `*(this+0x10)`,
then dispatch on count to `FUN_1404d5b30` (u8 indices), `FUN_1404d5ce0`
(u16 indices), or a `count*0xc` vec3 blob.

## Stage 5d — oIResource prelude (PARTIAL)

`oIResource::Serialize` at `0x1400c2240` is a no-op stub (`return 1`); it
writes zero bytes. The leading section in every cooked file is actually
container-level metadata emitted by `oCBinarySaver`, not by oIResource.
Layout is 3–5 u32 fields whose count correlates with class-graph
complexity (more nested sub-objects ⇒ more fields). Per-field semantics
need a separate decompile of the cooker pre-pass (not the runtime
deserializer). Round-trip passthrough is already byte-stable via the
existing container codec, so no schema change is required to ship apply
pipeline — only inspection clarity.

## Stage 5e — oCSkeleton (SOLVED — decode side)

- Class UID: `0x1617`
- Current saved version: `1.1`
- `oCSkeleton::Serialize` at `0x1405b4c40` calls `FUN_1405cb350` to read
  the bone vector at `this+0x98`.
- Per-bone: **`oCBone::Serialize`** (UID `0x1614`, v1.1), 304 (0x130)
  bytes in-memory, dispatched as embedded sub-objects via stream slot
  `+0xa0`.
- Bone bind-pose translation: `+0x118` (3 floats) within bone struct.
- AABB at oCSkeleton `+0xa8..+0xbc` (6 floats xMin/yMin/zMin/xMax/yMax/zMax),
  version-gated for saved-version > 0.
- Each per-bone payload is its own BEGIN/END-bracketed sub-object — the
  existing container codec already frames it correctly without any
  changes.

Encode side (cooker quantization pipelines `FUN_1404c3440` mode-1 20B/vertex
and `FUN_1404c3dc0` mode-2 18B/vertex) remains TBD; static-mesh decode →
GLB lands in this phase, decode-only.

## Stage 7 — oCAnimation (v1.5) corpus validation

Round-trip verified on real `.yqz` cooked animations. Schema in
`src/rsmm/engine/cooked_schemas/animation.py` parses the full layout:

- `oIResource` 4-byte parent prelude (section 0)
- `oCAnimation` body (section 1):
  - `u32 res_prelude` (dispatch-wrapper preface; 0 in corpus)
  - lstring `name`
  - `u32 track_count` (or BEGIN typeof header path if first u32 = 0xAABB1111)
  - track_count × oCAnimationTrack sub-objects (BEGIN/END framed)
  - `f32 frame_step` (= 1 / frame_rate)
  - 6 × f32 AABB (via `FUN_1404d4a60`)
  - `FUN_1405b31d0` trailing struct at ver=5:
    - `u32 sub_ver` (= 5)
    - 5 × f32, 3 × f32 (via `FUN_140126ec0`), 4 × u8, u8 (v≥2), f32 (v≥3),
      u32 (v≥5) — typically the frame_rate (e.g. 30)

Per oCAnimationTrack (v1.7) — bone keyframe block:

- `u32 res_prelude` + `u32 leading_u32` + lstring bone_name
- 6 parallel streams alternating (times_u32_count + values_blob6) for
  Translation / Rotation / Scale axes
- Times: `u32 wire` per entry (holds a quantized u16 timestamp; remaps
  to seconds via `t * duration / 65535.0`)
- Values: `u32 size=6 + 6 bytes` per entry
  - T / S: 3 × signed i16, fixed-point `value = i16 / 1024` (NOT the
    per-anim AABB range — that earlier note was wrong). From the quantizer
    `FUN_1404ad910`: `q = round(clamp(value, -32, 31) * DAT_140fc6a74)`
    with `DAT_140fc6a74 = 1024.0`.
  - R: 48-bit smallest-three quaternion packing (from `FUN_1404ad540`)
- Trailing `f32 duration` (== animation duration in v1.7)

### Keyframe dequantization constants (SOLVED — decode side)

All read from `Ravenswatch.exe` .rdata and validated against the corpus:

- **Time**: `t = u16 / 65535 * duration` seconds (`DAT_140fc6ab0 = 65535`).
- **Translation / Scale**: `value = signed_i16 / 1024` (`DAT_140fc6a74 =
  1024`, clamp `[-32, 31]`). 1024 == 1.0. The earlier `/32767` guess
  collapsed every scale to ~0.03, which is why preview rigs rendered
  invisible.
- **Rotation** (smallest-three, `FUN_1404ad540`):
  - 48-bit field: `bits[46:45]` = largest-axis index, then three signed
    15-bit component fields `[44:30] [29:15] [14:0]` in axis order
    (largest axis omitted).
  - `component = signed15(field) / (sqrt(2) * 16383)`
    (`DAT_140fc6860 = 2.0`, `DAT_140fc6a98 = 16383`).
  - Omitted largest axis = `+sqrt(1 - a^2 - b^2 - c^2)` (encoder
    sign-flips so the largest is positive).
  - Validated **100% unit-norm across ~1.1M shipped keyframes**; identity
    blob `00 00 00 00 00 20` decodes to `(0, 0, 0, 1)`.

The decoder now emits a genuinely viewable `.glb`: one node per bone seeded
with its keyframe-0 rest pose, a shared octahedron "joint marker" mesh so
the bones are visible, and animation samplers/channels with the corrected
TRS curves.

Round-trip strategy: `decode()` produces a viewer-loadable `.glb` whose
JSON `extras.rsmm.raw_payload_b64` carries the original cooked section
bytes; `encode()` reads them back. Byte-stable provided the `.glb` was
authored by `decode()` (re-quantizing arbitrary glTF still requires the
forward packing path — decode is exact, re-cook goes via raw_payload_b64).

Corpus validation: **2240 / 2240** shipped `.yqz` animations round-trip
byte-stably (full coverage).

## Stage 8 — oCGlobalEntityValueSettings (v1.1) — SOLVED (decode + encode)

Schema in `src/rsmm/engine/cooked_schemas/global_values.py`. Decompile of
`FUN_1406de4e0` (Serialize) + byte validation against the full corpus.

Body wire order (after the 4-byte oIResource prelude section):

```
u32 res_prelude (= 0)
lstring name                 (the global value's key)
lstring string2              (a category tag — "Hero", "New Game Plus", ...)
SubObject<oCEntityValueUnion>  (BEGIN/END framed)
u8 flag_be, u8 flag_bc, u8 flag_bf   (3 trailing flag bytes)
```

`oCEntityValueUnion` (uid `0xd97f3e3`, v1.6):

```
u32 union_ver (= 3)
u32 type   0=float, 1=int, 2=bool, 3=vector3
u32 pad    (= 0)
value:  type0 f32 | type1 i32 | type2 u8 | type3 3×f32
```

All 204 shipped files share one container framing template (variant A,
hdr_a 0x10, flags 0x1, extra 1, type_tag 0x31, fixed 4-class table), so
`encode_container` rebuilds the container deterministically — the JSON is
fully self-describing (no opaque passthrough) and **byte-stable
round-trips 204 / 204**, with field edits flowing through to re-cooked
bytes. `scripts/extract_uncooked.py` mirrors these to
`data/uncooked/**/*.globalvalue.json`.

## Stage 11 — VFX / GameStream / CollisionMesh (asset-ref passthrough)

`src/rsmm/engine/cooked_schemas/asset_refs.py` — one generic
`AssetRefsHandler` for classes whose deep recursive schema isn't fully typed
but whose moddable payload is a set of embedded asset paths:

- `oCScheduledVfxSettings` (2368/2368) — the deferred recursive
  particle/`oIRsSettingsGroup` system; exposes the `Materials\\*.mat.ot`
  refs the effect uses.
- `oCGameStream` (390/390) — level object streams.
- `oCCollisionMesh` (16/16) — collision geometry.
- `oCMaterial` (2873/2873, v1.28) — exposes the albedo / MRA / normal
  texture refs (`Textures\\*.tga|.png`) + shader ref (`*.px.ot`) the
  material points at, so a material can be repointed / reskinned. The
  variable `oCShaderParamSet` (named param values — colors, floats) stays
  in the opaque literal stream; typing it later just moves those bytes into
  named fields. `material.py` no longer registers a stub — it defers here.

Decode splits the concatenated section bytes into verbatim literal chunks +
length-prefixed strings that look like asset refs (path separator or known
extension), exposing the refs as an editable `asset_refs` list. Encode
re-interleaves and re-splits by stored section lengths, mapping each ref's
length delta to the section that held it (`ref_offsets` / `ref_orig_lens`).
**Byte-stable round-trip; ref edits (e.g. repoint a VFX at a different
material) verified.** The recursive trees themselves stay in the verbatim
literals — same trade as the entity-settings component tree.

With this every root cooked class in the shipped corpus (all 25) has a
registered schema: full decode for textures / geometry / animation /
material / global-values / definitions, and byte-stable + editable-ref
coverage for the deep nested settings/stream classes.

## Stage 10 — oCEntitySettingsResource (byte-stable + editable path)

`src/rsmm/engine/cooked_schemas/entity_settings.py`. Serialize
`FUN_1406e5af0` is trivial (one `oCEntitySettings` sub-object at +0x98);
the real content is the nested component tree. The family is heterogeneous
(~62% "spawnable" entities carrying a 16-byte GUID + type string + a
`*.entity.ot` path; the rest component-only) and frequently splits
sub-objects across many container sections (2–689; strings can straddle a
boundary).

Handler strategy: parse the **concatenated** section bytes; locate the
spawnable block structurally via the `u32(16) + 16-byte guid + u32(1)`
anchor (works regardless of the variable type string), then expose
`entity_type` / `entity_path` as editable with the surrounding bytes kept
as `_pre_hex` / `_post_hex`. The container framing + section lengths are
stored in `_container`; on encode the concatenation is re-split by those
lengths with any length delta from an edited path absorbed into the section
containing the edit point. Component-only files (no anchor) are pure
byte-stable passthrough (`_pre_hex` = whole stream).

**4699 / 4700 byte-stable** (the one failure is a malformed container the
codec itself rejects — `class_count=205`); **2279** expose an editable
entity path. Path-length edits verified to re-split correctly. The deep
component-value tree (`oCEntityCpntValueSettings` / `oCEntityValueUnion`)
is left in the opaque region — same call as the deferred VFX tree.

## Stage 9 — oCDt*Definition data tables (framework + first class)

`src/rsmm/engine/cooked_schemas/definitions.py`. All `*Definition` leaf
classes derive from a shared `oCDtDefinition` base (`FUN_14030f880`, uid
`0x1768ce8e`) whose serialized body is two version-gated `u8` flags; each
leaf appends its own fields. The module is a registry of per-class
`_DefSpec`s (body decode/encode + container framing template), all served by
one generic `DefinitionHandler` that produces byte-stable editable JSON and
rebuilds the container deterministically. `scripts/extract_uncooked.py` has
a generic `*Definition.gen → <stem>.json` branch driven by the registry.

For classes whose container class table varies between files (an optional
sub-object class appears only when a nested vector is non-empty), the spec
sets `embed_container=True` and the framing + class table round-trips
through a `_container` block in the JSON instead of a fixed template.

Implemented:

- **oCDtEnemyTribeDefinition** (v1.1) — Serialize `FUN_14031b080`: base +
  empty `vector<TResourcePtr>` (`FUN_140337a10` @+0x2a0) + `u8` @+0x2b0 +
  `SubObject<oCCustomFlagList>` (u32 list_ver, u32 count, count × lstring =
  the tribe flag names). **25/25 byte-stable.**
- **oCDtEnemyDefinition** (v1.6) — Serialize `FUN_140319b30`: base +
  `TResourcePtr entity_ref` (settings-class + entity path) + `oCCustomFlagList`
  (combat/role flags) + `f32 spawn_weight` + `TResourcePtr tribe_ref` +
  trailing version-gated scalars / sub-object vectors preserved verbatim as
  an opaque `_tail_hex`. Exposes the high-value editable surface (which
  entity, tribe membership, combat tags, spawn weight) without fully typing
  every v1.0–1.6 migration field. `embed_container` (class table gains
  `oCDtEnemyDefinitionMaxOccurence` when a tail vector is non-empty).
  **81/81 byte-stable.**

A declarative field-DSL (`_dsl_spec`: ordered `tresptr` / `lstr` / `f32` /
`u32` / `u8` / `flaglist` fields, then opaque `_tail_hex`) covers the
simpler classes in one line each. `embed_container` stores every section
but the last verbatim (`lead_sections_hex`) so multi-section files
(sub-objects split into their own sections) round-trip:

- **oCDtDreamShardDefinition** (v1.0, 4/4) — entity_ref
- **oCDtEnemyCampDifficultyDefinition** (v1.1, 6/6) — field_a + 2 f32
- **oCDtEnemyCampTierDefinition** (v1.0, 4/4) — 2 f32 + field_a
- **oCDtIngredientDefinition** (v1.3, 6/6) — icon_ref + name
- **oCDtMapDefinition** (v1.3, 4/4) — level_ref + field_a + tribe_ref
- **MelodyDefinition** (v1.5, 12/12) — field_a + entity_ref

Remaining classes added the same way (leading editable refs typed via the
DSL, everything past the first unknown sub-reader preserved in `_tail_hex`):

- **oCDtTileDefinition** (v1.8, 237/237) — entity_ref
- **AchievementDefinition** (v1.3, 45/45) — guid (blob16) + field_a + 2 u8 + name
- **GameModifierDefinition** (v1.2, 22/22) — icon_ref + field_a + text_ref
- **oCDtHeroDefinition** (v1.27, 12/12) — base + opaque tail
- **oCDtRewardDefinition** (v1.2, 9/9) — base + opaque tail
- **ChallengeDefinition** (v1.1, 5/5) — field_a + text_ref
- **GameModeDefaultDefinition** (v1.1, 1/1) — field_a
- **VersionDefinition** (v1.6, 1/1) — base + opaque tail

**ALL 16 definition classes done: 474/474 byte-stable.** Classes whose body
past the typed prefix isn't field-decoded yet still round-trip exactly via
`_tail_hex`; deepening any of them later just means moving bytes out of the
tail into named DSL fields.

Adding a leaf class = decompile its Serialize (VAs resolved in
`data/cooked_class_map.json`), model the body against samples until 100%
byte-stable across that class's corpus, add a `_DefSpec`. Remaining leaf
classes + their Serialize VAs: oCDtEnemyDefinition `0x140319b30` (v1.6),
oCDtTileDefinition `0x140323d90` (v1.8), AchievementDefinition `0x1403115a0`
(v1.3), GameModifierDefinition `0x140325810` (v1.2), oCDtHeroDefinition
`0x1400c9b70` (v1.27), MelodyDefinition `0x1400c8750` (v1.5),
oCDtRewardDefinition `0x140323bc0` (v1.2, uses `FUN_14020d700` vector),
oCDtEnemyCampDifficultyDefinition `0x140311e90`, + the smaller ones.

### Still undecoded data classes (candidates for the same treatment)

| Class | count | version | notes |
|-------|------:|---------|-------|
| `oCEntitySettingsResource` | 4699 | 1.0 | GUID + entity path + nested `oCEntityCpntValueSettings` / `oCEntityCpntPicker` / `oCEntityValueUnion` component tree — deeply nested |
| `oCScheduledVfxSettings` | 2368 | 1.2 | VFX timelines |
| `oCGameStream` | 390 | 1.1 | level streams |
| `oCDtTileDefinition` | 237 | 1.8 | data-table definitions (`@dt@oe@@`) |
| `oCDtEnemyDefinition` | 81 | 1.6 | enemy stats |
| `AchievementDefinition` | 45 | 1.3 | |
| `oCDtEnemyTribeDefinition` | 25 | 1.1 | |
| `GameModifierDefinition` | 22 | 1.2 | |
| `oCDtHeroDefinition` | 12 | 1.27 | hero stats (many version-gated fields) |
| `MelodyDefinition` | 12 | 1.5 | |
| `oCCollisionMesh` | 11 | 1.3 | |
| `oCDtRewardDefinition` | 9 | 1.2 | |
| ... | | | + 8 more `*Definition` classes, ≤6 files each |

Each needs its own `Serialize` decompile; the wire format is untyped so
there is no generic shortcut. The shared `oCEntityValueUnion` codec above
is reusable for any of them.

## Stage 4 — oCTexture (v1.14) corpus validation

Round-tripped 4450 of 4451 `.tpi` files in shipped corpus through the
schema in `src/rsmm/engine/cooked_schemas/texture.py` (decode + re-emit
== original bytes).

Format distribution (engine_enum):
- `0x04` BC1: 1995 (~45%)
- `0x05` BC3: 1859 (~42%)
- `0x00` RGBA8 / UNKNOWN: 596 (~13%)

The single failure is `Grgtdzy_Fbuqqz_Ngum-Adllv.cjy.Qqpiwuq.tpi` —
a 3840x2160 BC1 texture using the `.cjy` cipher variant (not the
standard `.jzy`/`.iyg` extension). Its header claims blob_size =
4,147,200 B (= 3840*2160/2 = correct BC1 size for that resolution) but
the section payload is only 2,914,556 B. The actual pixel data is
truncated on disk — likely a streamed/external texture where the
final blob lives in a paired resource the loader fetches lazily. Out
of scope for the in-section schema. Decoder raises
`oCTexture payload truncated at blob read` which is correct behavior.

### DDS source encoder

`TextureHandler.encode_container(dds_bytes)` accepts a `.dds` source
file and produces a full cooked `.tpi` byte string ready to drop into
`<install>/DarkTalesResources/_Cooking/...`.

Path:
1. `dds.read()` parses DDS header (legacy DDS_HEADER + optional DDS_HEADER_DXT10).
2. Fourcc / DXGI value resolved to canonical `dds.FORMATS` entry.
3. Mip chain split: level 0 → `schema.pixels`; levels 1..N → `schema.mips`.
4. Engine pixel-format code looked up from `_DDS_NAME_TO_ENGINE` table.
5. Trailing flag fields (`array_size`, `mip_count_field`, `flag_ed`,
   `flag_ee`, `field_bc`, `flag_eb`, `local_40`, `f32_dc/e0/e4`) set to
   corpus-typical defaults.
6. `_encode_payload` re-emits the section payload.
7. `_build_cooked_container` wraps in variant-B container with the
   appropriate class table (adds `oCTextureMip` entry when mips present).

Cooked-format `array_size` is NOT a DDS array dimension — it's an
engine-internal flag with observed values 0/1/3. The DDS writer always
emits a 1-slice file; `dds_to_schema` re-applies the corpus-typical
flag values on the inverse path (`0` when mip-chain present, `1`
otherwise; rare `=3` case not synthesisable from a normal DDS).

cooked→DDS→cooked round-trip verified semantically (width, height,
format, full mip chain) on random samples. Whole-container byte-identity
not guaranteed because the corpus has both `(0,0)` and `(1,1)` value
patterns for plain 2D single-mip textures and the encoder picks one
canonical pair.

## Stage 5 + Stage 6 — oCGeometry (v1.2) round-trip + GLB preview

Schema lands in `src/rsmm/engine/cooked_schemas/geometry.py`. Cooked
→ GLB → cooked round-trip verified across the **full shipped corpus
(3001 / 3001 `.yqz` geometry files)**.

### Container layout

Variant-B cooked container with N sections:

```
sec[0]: aux header — 12 or 16 B
  u32 side_channel_count
  side_channel_count × u32 versions      (7 or 9 in v1.2 corpus)

sec[1..side_channel_count]: side-channel vertex layers
  u32 schema_version (7 or 9)
  lstring layer_name        ("binormal", "tangent", "tangentSign",
                             "uv2", ...)
  u8 comp_mode (v=9 only)   (= 0 = uncompressed)
  u32 vertex_count
  u32 byte_count
  byte_count bytes          (stride depends on class:
                             oCVec3VertexLayer = count * 12,
                             oCFloatVertexLayer = count * 4,
                             oCVec2VertexLayer = count * 8)

sec[N]: main oCGeometry body
  u32 oIResource prelude    (= 0)
  u32 bone_count
  bone_count × {
    16 × f32 matrix         (64 B row-major)
    lstring name_a
    lstring name_b
  }
  u32 submesh_count
  u8  has_skeleton
  submesh_count × SubObject<oCMesh>
  if has_skeleton: SubObject<oCSkeleton>
  6 × f32 AABB              (xMin yMin zMin xMax yMax zMax)
  (v >= 2) trailing struct  (= 0x01010000, 0x01010000, 1)
```

Submesh sub-objects are NOT walked via BEGIN/END markers — large
float vertex buffers contain false marker matches that defeat depth-
balanced scanning. Instead the AABB is located deterministically by
subtracting the fixed 33-byte tail (24 B AABB + 9 B trailing struct)
from the end of the main-body section.

### Round-trip strategy

`decode_cooked(cooked_bytes)` produces a viewer-loadable `.glb`
embedding:
- **One TRIANGLES mesh per submesh** with real POSITION / NORMAL /
  TEXCOORD_0 + index buffer, decoded by `_parse_meshbuffers` from each
  oCMeshBuffer default-buffer uncompressed stream (vertex stride 48 B —
  Stage 5c.i). Validated across the shipped corpus: every default-buffer
  mesh is `unique_flag==0` / `comp_mode==0`, decoded normals are unit
  length, indices in range. Loads correctly in trimesh / Blender.
- One transform-only node per bone (matrix preserved)
- One LINES mesh visualising the AABB
- Side-channel vec3 layers are emitted as a POINTS preview *only* when no
  decodable submesh exists (they are unit vectors — plotted as positions
  they form a "ball of dots", which was the earlier broken-looking output)
- `extras.rsmm.raw_payload_b64` — concatenated section bytes
- `extras.rsmm.cooked_b64` — full cooked-file bytes

`encode_container(glb_bytes)` extracts `cooked_b64` and returns the
original cooked bytes — byte-identical round-trip.

### Stage 6 hard limit

`encode()` deliberately refuses any `.glb` lacking the rsmm marker.
Cooking arbitrary glTF (a real authoring path) requires reversing the
quantization compressors `FUN_1404c3440` (mode-1 20 B/vertex) and
`FUN_1404c3dc0` (mode-2 18 B/vertex). Both remain unreversed; failing
fast prevents modders from shipping silently-broken meshes.

The current pipeline gives mod authors:
- byte-replace `.yqz` mods (already supported via container codec)
- DDS source texture mods (Stage 4)
- viewable mesh previews via Blender / glTF Viewer (Stage 5)

It does NOT yet give mod authors:
- editable-mesh mods sourced from a freshly-authored `.gltf`
- editable-skeleton mods sourced from glTF skin data
- re-encoded animations from glTF tracks

---

# Pickable talents

> Detecting a level-up card pick via POWER_UP_COLLECT_REQUEST, and the additive magical-object route for a card that replaces nothing.

Source: https://docs.rsmm.me/reverse-engineering/pickable-talents/

:::note
Status: Tier-2 — the detour and Lua API are wired; the picked-card **identity
offset** is pinned empirically (see [Open](#open--confirm-the-identity-offset)).
Backs `R.talent.on_pick` / `R.talent.define{pickable}` in
`src/loader/lib/rsmm.lua` and the `POWER_UP_COLLECT_REQUEST` branch of
`hook_events.cpp`.
:::

## What a "pickable talent" is

A custom-code talent whose effect arms only when the player **chooses its card**
in the level-up book — versus `R.talent.define` without `pickable`, which is an
always-on passive. Choosing a card fires the gameplay-bus event
`POWER_UP_COLLECT_REQUEST` (`oCDtNamedEventPowerUpCollectRequest`), proven live
on the [oCGameNamedEvent bus](/reverse-engineering/event-systems/).

## Pipeline

1. Player picks a card → game dispatches `POWER_UP_COLLECT_REQUEST` at the hero
   dispatcher.
2. `gameplay_dispatch_detour` republishes it to Lua as
   `gameplay:POWER_UP_COLLECT_REQUEST`, attaching the tentative decoded identity
   `ev.card` (`+0x50`/`+0x58` GUID, `"<lo>:<hi>"`) plus a confirm window
   (`ev.p38`..`ev.p58`).
3. `R.talent.on_pick(card, cb)` filters by `card` and runs `cb(ev)` on the main
   thread; `R.talent.define{pickable=true, card=...}` flips a per-talent armed
   flag so its `effect` runs only after the matching pick. Arming resets at
   `GAME_START`.

## Event identity offset

The shared `oCGameNamedEvent` GIVE sibling ctor `NamedEvent_GiveMagicalObject_Ctor`
(`FUN_14030f430`) puts its def GUID at `+0x50`/`+0x58` in a `0x60` object. The
pick event's reward-def GUID is the **prime suspect at the same `+0x50`/`+0x58`**,
so the loader publishes `ev.card` tentatively and string-id matching works today.

Not yet *confirmed*: the pick class registrar (RTTI `oCDtNamedEventPowerUpCollectRequest`
@ `0x140f1d940`, ref'd from undefined code at `0x1402fdb6c`) is unanalysed, and
the pick event may omit the `oCGameNamedEventNetwork` layer GIVE inserts (which
would shift the payload toward `+0x38`).

## Open — confirm the identity offset

Run `mods/TalentPickProbe` (`RSMM_ENABLE_GAMEPLAY_EVENTS=1`), level up, pick
cards. In `mods/_log.txt` the `pickprobe:` lines show `ev.card` + the `p38..p58`
window. The identity is the field that changes with the chosen card and repeats
when the **same** card is picked again. If that field is `p50`/`p58`, `ev.card`
is already correct. The read is bounded to `+0x58`; a smaller no-Network event
reads a few bytes of adjacent mapped heap — benign, never an unmapped fault.

Second thing to confirm: `POWER_UP_COLLECT_REQUEST` fires for **every** power-up
collect (level-up cards *and* world orbs/globes), so per-card targeting needs the
GUID (`ev.card`); `"*"`/no-card arms on ANY power-up.

## Additive pickable — the magical-object route

The cleanest *additive* (replaces-nothing) pickable that works with proven
primitives: a **NEW magical object**. Unlike the hero skill list (fixed 28-row
schema — a 29th [bricks the hero](/reverse-engineering/skills-system/)), the
magical-object / reward pool is **variable-length and additive**:

- Reward definitions are `oCTLibrary<oCDtRewardDefinition>`, file-loaded from
  `*.rewarddef.ot` and registered in `UsedRscList.ot`. Tables are variable-length
  (camp 9 entries, refugee 5) — count is data-driven, not a global constant.
- The custom magical-object pipeline is proven additive end-to-end (a new item
  shows in the compendium and can be granted/picked).

**Binding gap closed.** A custom item's GUID is cook-derived (not recomputable in
Lua), so the loader resolver `resolve_item_guid(id)` (`hook_items.cpp`) +
`R.item.guid(id)` / `R.item.on_guid(id, cb)` resolve it at runtime by scanning
the pool source list for the entry spawned from the item's `EntitySettingsResource*`
(GUID at `def+0x88`/`+0x90`). Demo: `mods/AdditivePickableTalent` — `kind="item"`
emits the card, `init.lua` arms an ownership-gated effect once the GUID resolves.

## See also

- [Event systems](/reverse-engineering/event-systems/) — the gameplay bus this rides.
- [Skills system](/reverse-engineering/skills-system/) — why the herodef route is walled.
- [Custom skills guide](/guides/custom-skills/) — the SDK `skill` kind.

---

# RE pipeline

> How the bulk decompile, symbol, and pattern artifacts are produced.

Source: https://docs.rsmm.me/reverse-engineering/pipeline/

Everything under `docs/_re/` exists so a mod can call any function in
`Ravenswatch.exe` by name. This file documents the toolchain that
produces that capability and how to regenerate after a game patch.

## Inputs

```
~/Documents/Programming/ghidra_11.3_PUBLIC/      Ghidra install
~/.var/app/.../Ravenswatch/Ravenswatch.exe       target binary (~22 MB)
```

## Stages

```
                      ┌──────────────────────────────────┐
   Ravenswatch.exe →  │ Ghidra headless auto-analyzer    │
                      │ (project: docs/_re/project/RSMM) │
                      └──────────────┬───────────────────┘
                                     │
        ┌────────────────────────────┼──────────────────────────┐
        ▼                            ▼                          ▼
docs/_re/scripts/         docs/_re/scripts/         docs/_re/scripts/
dump_symbols_strings.py   decompile_all.py          xrefs_to_addrs.py
   │                            │                          │
   ▼                            ▼                          ▼
out/symbols.json          out/decompiled_all/       out/xref_targets/
out/strings.json          out/functions_index.tsv   out/xref_targets_summary.json
   │
   │  scripts/gen_function_patterns.py
   │  (capstone disasm → mask reloc-sensitive bytes →
   │   extend until pattern is unique-or-indexed)
   ▼
data/function_patterns.json (~20 MB, 53k entries)
   │
   │  shipped alongside winhttp.dll → game install
   ▼
src/loader/src/fn_resolver.cpp  (scans .text at runtime)
src/loader/src/fn_call.cpp      (invokes via Win x64 ABI)
src/loader/src/script_lua.cpp   (rsmm.resolve / rsmm.call bindings)
```

## Artifacts

| Path | Content | Size |
|---|---|---|
| `out/symbols.json` | 54,450 function entries — name, addr, signature, size | 9 MB |
| `out/strings.json` | 10,919 defined strings | 1 MB |
| `out/xrefs.json` | reference graph for hand-tagged hotspots | ~70 KB |
| `out/xref_targets_summary.json` | xrefs to seed/RNG/UI symbols | ~10 KB |
| `out/xref_targets/*.c` | decompiled containing function for each xref | small |
| `out/decompiled_all/<bucket>/*.c` | 46,963 pseudo-C function bodies | 218 MB |
| `out/functions_index.tsv` | flat index of decompile pass | (regen-on-demand) |
| `data/function_patterns.json` | byte-pattern signatures for `rsmm.resolve` | 20 MB |

Functions are bucketed in `decompiled_all/<bucket>/` by the top 4 hex
digits of their entry-point VA so no directory holds more than a
couple thousand `.c` files.

## Scripts

Ghidra Jython scripts (run inside the headless analyzer):

| Script | Purpose | Runtime |
|---|---|---|
| `scripts/dump_symbols_strings.py` | export every function + string to JSON | ~1 min |
| `scripts/decompile_all.py` | pseudo-C per function, bucketed | ~25 min |
| `scripts/decompile_by_addr.py` | decompile one address (debug aid) | seconds |
| `scripts/decompile_targets.py` | hand-curated list of hotspots | seconds |
| `scripts/dump_xrefs.py` | reference graph for tagged sites | <1 min |
| `scripts/xrefs_to.py` | xrefs to one address | seconds |
| `scripts/xrefs_to_addrs.py` | xrefs to a list of address targets | seconds |

Non-Ghidra (host Python) scripts:

| Script | Purpose | Runtime |
|---|---|---|
| `../../scripts/gen_function_patterns.py` | build pattern DB from exe + symbols.json | ~5 min |
| `../../scripts/test_pattern_resolve.py` | validate DB; resolve by name or addr | <30s for one, ~10 min for `--all` |

## Pattern signatures: how they survive patches

Every function's prologue (first 12–128 bytes) is disassembled with
capstone. Operand bytes that encode an address — branch displacements,
RIP-relative `lea`s, `mov mem disp32` — are replaced by `??`
wildcards. What stays is the instruction shape: opcodes, register
encoding, small constants.

When the game ships a patch, addresses shift but the instruction
*shape* mostly survives. `fn_resolver` re-scans `.text` at runtime,
finds the same pattern, and updates the resolved VA without any code
change in the manager.

For non-unique prologues (templated dtors, vtable thunks, tiny
wrappers — about 46% of functions), each entry records a
`match_index` = rank within all matches in `.text`, sorted by VA.
Every pattern is scanned against the whole `.text`, counting matches exactly
as the loader does (every start position, overlapping hits included). A
pattern that matches more than once is lengthened as far as its own function
goes, so it becomes unique where it can and falls back to an index where it
cannot. On the 2026-10-03 build, **100%** of 50,056 entries resolve to their
recorded VA (`scripts/test_pattern_resolve.py --all`). One scanner,
`gen_function_patterns.scan_offsets`, is shared by every pattern script so they
cannot drift from each other or from the loader.

The DB published before this fix indexed only the patterns repeated inside its
own symbol list, and counted non-overlapping matches: about 73% of its generic
entries resolve to the address they were made for. The hand-mapped symbols the
loader uses were unaffected (all 192 `status=ok` symbols verify). Republish to
ship the fixed DB.

Cross-build accuracy (2026-07-09 patch): **77 of 92** hand-named function
symbols re-located automatically by byte pattern; the remaining ones had
prologues that changed too much and were flagged for manual RE (see the
remap pipeline below). The generic ~53k-entry DB regenerates wholesale.

## Rebuild for the installed game

`./rsmm rebuild-fn-patterns` regenerates the DB for the exe you have, adds the
stable named entries, and checks the result: every `status=ok` symbol must land
on a function boundary and every entry must resolve to its recorded address.
The old DB is kept as `*.prev` and put back if any step fails or you interrupt
it. About 2–3 minutes. `--ghidra` re-dumps `symbols.json` first; `--dry-run`
prints the plan. It needs `capstone` and uses the repo's `.venv` if the current
interpreter lacks it. It does not remap `data/symbols.json` after a patch,
rebuild the loader, or publish.

## Regen on a fresh checkout

First run (imports + analyzes the exe; ~10–20 min):

```sh
bash docs/_re/run_analysis.sh        # creates project, auto-analyzes
bash docs/_re/run_dump_symbols.sh    # symbols.json + strings.json
bash docs/_re/run_decompile_all.sh   # full pseudo-C corpus
python3 scripts/gen_function_patterns.py
```

The Ghidra project (`docs/_re/project/RSMM.gpr` + `.rep/`) is
committed. The big derivatives (`out/`, `data/function_patterns.json`)
are local — see `.gitignore`.

## Recovering the symbol map after a game patch

A game patch shifts every address. The generic pattern DB self-heals at
runtime (the scan finds the same byte shape), but two things need active
recovery: `data/symbols.json` (the hand-named semantic addresses that the
loader's typed API, events, and hooks reference) and the semantic pattern
entries the loader resolves by name. This is what the remap pipeline does —
no hand-RE of every address.

Run the stages **in this order** (the old build's `.text` must be dumped
*before* the exe is re-imported, because the project is overwritten):

```sh
# 1. Dump the OLD build's .text from the still-current project (pre-import).
bash docs/_re/scripts/run_dump_text.sh          # -> docs/_re/out/text_section.{bin,json}
#    (or: analyzeHeadless ... -process Ravenswatch.exe -postScript dump_text_section.py)

# 2. Re-import + analyze the NEW exe into a fresh project (RSMM2), dumping
#    symbols, strings, xrefs, .text, and vftables of the new build.
bash docs/_re/run_analysis.sh                    # imports new exe
#    also run ExportVftables.java -> docs/_re/out_new/vftables.jsonl

# 3. Remap function symbols: old prologue pattern -> scan new .text.
python3 scripts/remap_symbols.py --update-symbols

# 4. Rewire va data symbols: vftables by RTTI name, globals by data-ref vote.
python3 scripts/rewire_va_globals.py --remap data/.symbol_remap.json \
    --vftables data/vftables.jsonl docs/_re/out_new/vftables.jsonl --update-symbols

# 5. Downgrade any symbol whose pattern is unbuildable/ambiguous to
#    status=unverified (loader skips these — fails safe vs. calling a wrong
#    address). Then regenerate the DB from the NEW exe and inject the stable
#    semantic-named entries + legacy FUN_ aliases.
python3 scripts/gen_function_patterns.py --symbols docs/_re/out_new/symbols.json
python3 scripts/sync_symbol_patterns.py --legacy-map data/.symbol_remap.json

# 6. Regenerate all six symbol artifacts, verify, rebuild the loader.
./rsmm symbols gen
python3 -m pytest tests/test_symbols.py scripts/test_pattern_resolve.py
bash src/loader/build.sh

# 7. Publish so every user picks it up without an app release.
bash scripts/publish_pattern_db.sh
```

**Why semantic pattern names matter.** The loader bakes pattern *names*
(`Sym::X_Pattern`) at build time. If those were address-derived
(`FUN_140391d30`) every patch would strand shipped DLLs. Instead the DB
carries stable semantic keys (`NamedEvent_Dispatch`, `Foo.parent` for
anchor parents); `sync_symbol_patterns.py` rebuilds them against the new
exe each regen, plus legacy `FUN_<oldaddr>` aliases so already-shipped
DLLs keep resolving.

**Delivery without an app release.** `data/function_patterns.json` is
gitignored (game-derived); it ships as assets on the rolling `pattern-db`
GitHub release (`scripts/publish_pattern_db.sh`). Users pull it with
`rsmm update-data`, which the desktop app runs silently on startup —
so a republished DB reaches every install without a Tauri update. See
`src/rsmm/engine/data_update.py`.

The raw `.text` dumps (`text_section.bin`, `out_new/`) are gitignored —
they are copyrighted game bytes and must never be committed.

## What this enables

See:

- `docs/_re/CALLING_GAME_FUNCTIONS.md` — the runtime API
  (`rsmm.resolve`, `rsmm.call`, memory r/w).
- `docs/_re/SEED_MAPGEN.md` — worked example: the seed surface.
- `mods/ExampleSeedPin/` — minimal mod that pins the run seed.

## What it doesn't enable

- **A general cooked-file re-encoder.** New items, heroes and enemies are
  cooked by the SDK content kinds from a shipped file; building an
  arbitrary class from scratch is still not supported.

---

# Anti-tamper protector

> What Ravenswatch.exe's anti-tamper does and why v1 avoids the runtime path.

Source: https://docs.rsmm.me/reverse-engineering/protector/

Reverse-engineering note. Establishes whether `MinHook` / IAT / VEH-style
hooks on the game's own `.text` survive once the game is running, or
whether the protector installs a runtime integrity monitor that
invalidates them.

## Conclusion

The protector is a **one-shot unpacker stub** in section `.bind`. It
runs before the real entry point, validates the binary, optionally
decrypts a small metadata blob, and returns the real entry-point VA.
After it returns, **the protector code is not reentered**:

- no thread is created from inside the protector (no `CreateThread`,
  no `CreateRemoteThread`, no `NtCreateThreadEx`),
- no exception filter is installed (no `SetUnhandledExceptionFilter`,
  no `AddVectoredExceptionHandler`),
- no `.text` page-protection change is performed *after* the unpack
  (the protector itself does not re-VirtualProtect anything periodically),
- the only post-return tear-down zeroes the protector's own working
  buffers on stack — pure anti-forensics, not anti-hook.

This means **`MinHook` on functions inside `.text` of `Ravenswatch.exe`
works** once the loader's worker thread has settled, which is consistent
with the Phase 3 INTERNALS.md evidence (`FUN_1401145b0` and
`FUN_140487040` were hooked successfully).

The `ROADMAP.md #3` claim that an "anti-tamper integrity check"
crashes every hookpoint is **incorrect**. That observation was about
two specific hooks both of which had unrelated failure modes:

- `CreateFileW` via `MH_CreateHook` on `kernel32.dll` exports —
  Wine's `CreateFileW` is a thin forwarder layered on `NtCreateFile`
  and rewriting its prologue corrupts Wine's TEB-tracked state during
  early Vulkan init. `hook_io.cpp` sidesteps this via IAT patching of
  the game's import slot and works.
- `IDXGISwapChain::Present`-equivalent — Ravenswatch uses Vulkan,
  not D3D, so there is no `IDXGISwapChain` for the engine to use.
  The hook target was looking at the wrong API surface.

## Section layout

```
.text     0x140001000  size 0xe91ab4  EXEC|READ        — game + CRT + engine
.rdata    0x140e93000  size 0x429ace  READ
.data     0x1412bd000  size 0x190540  READ|WRITE
.pdata    0x14144e000  size 0xbdaf8   READ
CPADinfo  0x14150c000  size 0x38      READ|WRITE       — CFG cohort
_RDATA    0x14150d000  size 0xf4      READ
.fptable  0x14150e000  size 0x100     READ|WRITE       — CFG fn-pointer table
.rsrc     0x14150f000  size 0x1e260   READ
.reloc    0x14152e000  size 0x2be78   READ|DISCARDABLE
.bind     0x14155a000  size 0x39048   EXEC|READ        — protector stub
```

The PE entry-point `0x14155a310` lands inside `.bind`. The first
instruction is a `call 0x14155a315` to an immediately adjacent
function (the inner-stub) which saves all 15 GPRs, derives the
self-address (`[rsp+0x78] - 5`) and calls the big protector function
`FUN_14155a3d0` (13,788 bytes) with that self-address in `RCX`.

After `FUN_14155a3d0` returns, the inner-stub writes the return
value into `[rsp+0x78]`, restores GPRs, and a `ret` jumps to that
address. **That is the real game entry point.** It lives in `.text`.

## TLS callbacks

The exe registers two TLS callbacks via the standard
`IMAGE_DIRECTORY_ENTRY_TLS` directory:

| VA            | Symbol             | Purpose                                                    |
|---------------|--------------------|------------------------------------------------------------|
| `0x140c93e2c` | `tls_callback_0`   | MSVC `_Init_thread_callback` — walks a fn-ptr table at `rip+0x209701..0x209712` on `DLL_THREAD_ATTACH` (`edx==2`). |
| `0x140c9457c` | `tls_callback_1`   | MSVC per-thread destructor walker — runs the chained dtor list at `gs:[0x58] + N*8 + 0x20` on `DLL_PROCESS_ATTACH` or `DLL_THREAD_DETACH`. |

Both are stock Microsoft Visual C++ runtime. **Neither is part of the
protector.** No code in either callback touches `.text` or `.bind`.

## Protector flow (decompiled summary)

`FUN_14155a3d0(self_va)`:

1. Reads a small metadata header (`local_378`) somewhere
   relative to the call site (via `param_1 - 5`).
2. Decrypts the header with a rolling XOR loop:
   ```
   key = local_378[0]
   for i in 0..0xec/4:
       tmp = buf[i]
       buf[i] ^= key
       key = tmp
   ```
3. Validates a magic at `header[1] == 0xC0DEC0DF` (signed
   `-0x3f213f21`). On mismatch goes to the error sink
   `LAB_14155cfde` which zeroes its scratch buffers and triggers
   `int3` — game dies with a debug-trap.
4. Parses an embedded string table of 0x22 (34) null-terminated
   strings. These are API names (Win32 kernel32 / kernelbase) that
   the protector will resolve dynamically.
5. Resolves `kernel32.dll` itself — but does so **without leaving a
   literal `"kernel32.dll"` string in `.rdata`**. The string is
   assembled on stack:
   ```
   local_a90='k', uStack_a8e='e', uStack_a8c='r', uStack_a8a='n',
   uStack_a88='e', uStack_a86='l', uStack_a84='3', uStack_a82='2',
   uStack_a80='.', uStack_a7e='d',uStack_a7c='l', uStack_a7a='l',
   uStack_a78=0
   ```
   then passed to a previously-resolved `GetModuleHandleA`-style
   pointer.
6. Walks the table of API names and stores each function pointer
   into `local_5xx` slots — this is the protector's private import
   table.
7. Optionally invokes Steam-DRM / packaging integration via
   `CreateFileMappingA` + `MapViewOfFile` (the `(*local_580)(0x100000,
   0, name)` and `(*local_578)(2, 0, name)` calls at lines 1155-1157).
   The mapped region at offsets 0x90..0xb4 is written with a small
   inter-process struct — likely the same kind of handshake that the
   Microsoft Store / Steam wrapper uses to sign per-process state.
   This **does not affect `.text` integrity**.
8. On the success path (line 1104):
   ```
   return local_b70 + local_358;
   ```
   That sum is the real entry-point VA inside `.text`.
9. On any error path the protector ends in `TerminateProcess(-1,
   exit_code)` at line 1260 (`local_5c8` is the resolved
   `TerminateProcess`).

There is no follow-on thread spin-up. There is no `.text` checksum
loop scheduled to run later. The protector vacates the stage.

## Implications for the Hook API

We can build `rsmm.hook(name_or_va, "sig", callback)` on top of
`MinHook` directly against `.text`. The existing fn_resolver
(pattern DB) gives us name -> runtime VA at any time after Wine's ASLR
settles, and MinHook installs a 5- or 14-byte detour at the resolved
VA without triggering any further reaction from the protector.

Constraints to respect:

- **Install hooks after the loader's worker thread has done its
  initial `VirtualQuery` retry loop** (`hook_engine.cpp` already waits
  up to 5s for `.text` to be mapped). The protector finishes before
  the engine's first `oCString` allocation, so by the time the
  loader's `script_emit_event("ready")` fires, the unpacker is gone.
- **Avoid Wine syscall-forwarder targets**: `kernel32!CreateFileW`,
  `kernelbase!NtOpenFile`, etc. Use IAT patching (already in
  `hook_io.cpp`) when you need to filter game I/O.
- The protector's success path returns an `entry_point + offset_const`
  computed from a metadata header that is decrypted at boot. **A game
  patch may shift this constant**, so do not hardcode the real
  entry-point VA anywhere — let the protector compute it and resolve
  hooks by pattern.

## Verification plan

1. Restore a minimal `MinHook` trampoline targeting `FUN_140487040`
   in `hook_engine.cpp` behind an opt-in env var
   (`RSMM_ENABLE_ENGINE_HOOK=1`).
2. Run the game. The hook should fire on the first resource lookup
   without any crash. Compare against the Phase 3 INTERNALS evidence
   (same hookpoint, same captured handles).
3. If clean for one minute of normal play, the hypothesis above is
   confirmed and we lift the gate; `rsmm.hook` proceeds.

---

# Rewards

> What the reward system actually decides (spawned chests, not offered cards), the fully decoded rewarddef grammar, and why a type-count ban is unreliable in-game.

Source: https://docs.rsmm.me/reverse-engineering/rewards/

:::note
Status: cooked grammar fully decoded and deserializer-verified; `reward` SDK kind
ships at confidence `experimental`. Its **ban lever is known-unreliable** — see the
roll-handler section. Class `oCDtRewardDefinition`, glob `*.rewarddef.ot`.
:::

Loader `RewardDef_RegisterAssetLoader` = `FUN_140323b60` (label "Reward
definition"). Codec `cooked_schemas.definitions.RewardDefinitionHandler`
(`rewarddef.json`) — byte-stable round-trip over all 9 retail files
(`test_rewarddef_roundtrip`). Rows fully editable: items, entity refs, tier bands,
flag filters, min/max counts.

## What this system is — and isn't

`Reward_GenerateAndDistribute` runs at level load ("Level load - Generate
rewards") and decides **which reward ENTITY spawns at each reward spawn point** —
chests, astrolabs, dream crystals (`Objects_*\*.entity.ot`).

It does **not** pick the talent/item cards offered when a chest opens or the
player levels up. That draw comes from the magical-object pool (the LiveOps
`versiondef` MO vector — see [Custom items](/guides/custom-items/)). So a
per-item/talent **card** ban lives in the MO pool; this system is the lever for
reward-object **placement**.

## How the roll works

`_InitAllRewards` → `Distribute` → "Fill remaining rewards on random slot".
Seeded ("Seed : {0} ; Base seed {1}") and host-authoritative deterministic
([Multiplayer](/reverse-engineering/multiplayer/)) — a per-peer runtime filter
desyncs MP, so edits must be data-level. After the roll, level load posts a
`GENERATE_REWARDS` `oCGameNamedEvent` via `NamedEvent_Dispatch` and drains the
context queue (`EventQueue_Drain`, ctx+0x1c0).

Candidates are level entities carrying
`oCDtRewardEntitySelectorToSpawnEntityCpnt` ("reward spawners"). Per spawner a
**value** f32 is lazily rolled and cached at spawner+0x68. A spawner matches an
`oCItem` row iff:

1. `oCItem.min <= value <= oCItem.max` (runtime `oCItem+0xb0` / `+0xb4`)
2. `CustomFlagList_ContainsAll(settings+0x100, oCItem+0xc0)` — required flags
3. `!CustomFlagList_ContainsAny(settings+0x100, oCItem+0xd8)` — excluded flags

Flag lists are string sets: `{char* name, u32 len}` entries, 0x18 stride, data at
`+0x8`, count at `+0x10`; compared by length + memcmp. **Every shipping rewarddef
has all flag lists empty** — the mechanism exists but retail data doesn't use it,
so a mod can claim flag names freely.

## Cooked grammar

Recovered from the actual deserializers and byte-verified against the
`Camp_Rewards_Avalon` and Refugees files. Three structural facts apply to **all**
cooked defs:

1. **`AABB1111`/`AABB2222` are section separators** that `cooked.parse` already
   strips — not node open/close inside a payload. Nested sub-objects each get
   their own section; references between them are u32 sub-object ids (order of
   sub-object sections).
2. **Section 0 is a sub-object class directory**: `{u32 count, count × u32
   class-table-index}`, one entry per sub-object section, naming its class.
3. **Field presence is version-gated** per class via the header class table
   (`Serializer_GetClassVersion` by class hash — the codec parses these as
   `classes[].version_*`). A typed codec must gate optional fields the same way.

```
oCDtRewardDefinition (hash 0x176f164e, LAST section):
    u32 res? + u8 base_a + u8 base_b      # oCDtDefinition base (v1+ bools @+0x285/+0x284)
    u32 count, count × u32 sub-object id  # -> the oCType rows (runtime vector @def+0x288)
    v1+: u8                                # unpinned bool

RewardDefInternal::oCType (0x176f4fdc):
    u32 count, count × u32 sub-object id  # -> oCItem rows ({ptrs @+0x8, count @+0x10})
    v1+: u8 use_float; if 0: u32 n (min=max=n) else f32 legacy_weight (1.0)
    v2+: u32 min_count (+0x18), u32 max_count (+0x1c)

RewardDefInternal::oCItem (0x176f5023):
    resource-ref { lstr "EntitySettings", lstr entity path }      # @+0x8
    f32 value_min (+0xb0), f32 value_max (+0xb4)                  # tier band over 0..1 roll
    v1+: inline oCCustomFlagFilter (+0xb8)                        # required @+0xc0, excluded @+0xd8
    v2+: resource-ref (+0x40)   # JSON _ref_b — LOCKED-variant entity on chest rows
    v4+: resource-ref (+0x78)   # JSON _ref_c — empty in retail
    v5+: u32 enum <7            # JSON _kind — 1=chest, 3=astrolab, 4=dream crystal

oCCustomFlagFilter (0x15a9d9bf): inline oCCustomFlagList required (+0x8), excluded (+0x20)
oCCustomFlagList  (0x15a9d9be): u32 count, count × lstr

candidate side — oCDtRewardEntitySelectorToSpawnEntityCpntSettings (0x1740e3e9),
cooked in the reward object's *.entity.ot settings:
    v<3: legacy discarded resource-ref
    v1+: inline oCCustomFlagList @+0x100   # spawner flags, matched vs the oCItem filter
    v2+: u32 enum <4 @+0xf8, v3+: u32 enum <2 @+0xfc   # unpinned (likely value-source mode)
```

The "Reward type {}" debug index is the position in the `oCType` row list; a
"category" is an `oCType` row's `oCItem` set.

## Ban levers (data-level, MP-safe)

- **Ban a reward object** — remove its index from every `oCType` row that lists
  it, or set `value_min > value_max`.
- **Ban a category** — remove/empty an `oCType` row, or zero its min/max counts.
- **Flag-based suppression** — add a flag string to an `oCItem` excluded list;
  only spawners whose settings carry that flag are suppressed. The spawner side
  must be authored too, so this is for mod content, not for banning retail objects.
- **Per-item/talent card ban** — not this system: remove the entry from the
  LiveOps `versiondef` MO vector. That de-registers it from the offer pool but
  also hides it from the compendium.

## SDK kind

`reward` (`sdk/kinds/rewards.py`) takes `base` + `ban` (entity substring → drop
from categories; a locked-variant `_ref_b` match clears the ref, so chests spawn
unlocked only) + `counts` (`{category: [min, max]}`; `[0,0]` bans the category).
It emits an **override at the retail decoded path**, not an additive def.

## Why the type-count ban did NOT work in-game

A playtest shipped a `reward` mod emptying the basic-chest reward type
(min=max=0, items=[]) across all 6 `Camp_Rewards` defs. The output was
byte-correct and installed — **chests still spawned.** Decompiling the roll
handler explains it: there are two independent placement blocks with two def
sources.

- **Block 1 — reward_types-driven, count-gated.** Walks a def's reward_types
  vector at `def+0x288`/`+0x290`. Per type: `min_count @type+0x18`,
  `max_count @type+0x1c`; candidate items from `type+0x08`/`+0x10`; each item has
  an **exclude byte at `item+0x30`** (nonzero ⇒ skipped) and a tag match at
  `item+0xc0`/`+0xd8` vs `spawner+0x100`. Emptying a type does yield 0 spawns
  *here*. But the def list it walks is built from globals — a runtime reward
  registry, not the `Camp_Rewards` file pointer directly.
- **Block 2 — guaranteed/forced, count-BYPASSING.** Uses a different def
  (scene-context `param_1[0x15]` = game-context `+0xa8`) with its own collections
  at `+0xe0`/`+0xf0`/`+0x110` and count loops at `+0x70`/`+0x7c`. It never reads
  reward_types min/max, so a "guaranteed" chest ignores the type-count edit.

:::caution
A count/type edit is **not a reliable ban.** The levers that do bind — item
exclude byte, removing the entity from the pool, the tag filter — bind Block 1
only. Banning a Block-2 guaranteed reward needs the context `+0xa8` def.
:::

## Open

1. Runtime loader dump to close this: hook the roll handler, log the Block-1 def
   list and the context `+0xa8` def, dump each one's `+0x288` reward_types and
   whether the basic-chest type is present or guaranteed. That pins whether the
   failure is a def-identity miss (Block 1) or a Block-2 placement.
2. Prototype versiondef MO-vector entry removal for the card-level ban, and check
   whether the compendium side effect is acceptable.

---

# Seed & map generation

> The run seed and map-generation surface, and how to pin a seed.

Source: https://docs.rsmm.me/reverse-engineering/seed-mapgen/

Reverse-engineered from `Ravenswatch.exe` (build hashed under
`data/exe_catalog.json`). Confirmed via Ghidra xref scan of the seed
strings interned in the read-only data segment. Addresses are
link-time VAs; resolve at runtime via image-base relocation.

## Built-in "Forced seed" exists

The game ships a `oe::UIntGameOption` field literally named `"Forced
seed"`, registered by the global game-options constructor at:

| Item | Address |
|---|---|
| Constructor that wires the field | `0x1401c6d60` |
| String `"Forced seed"` (ro-data)  | `0x140eed8b8` |
| Field ID (u32) at the call site   | `0x1949b098`  |
| Vtable used for the field         | `oe::UIntGameOption::vftable` |
| Companion enable flag             | id `0x1949b099`, `oe::BoolGameOption` |
| Format string `"Forced seed : {}"` | `0x140ef4068` (log line) |

So a "forced seed" code path is already plumbed in the engine — a mod
doesn't have to *invent* a seed hook, only flip the option on and
write the value.

## How to set it (without hooks)

The game's option system reads its initial values from
`DarkTalesResources/ApplicationSettings.ot`, which is plain
oCTextSaver text and already accepted by the `_root/` override
mechanism (`docs/MODDING.md`).

1. Open the game's own `DarkTalesResources/ApplicationSettings.ot` (it ships
   uncooked beside the executable — plain text, no cipher).
2. Find the block with the `Forced seed` option declaration
   (`oCTString` keys are stored verbatim).
3. Set the companion bool (id `0x1949b099`) true and the u32 (id
   `0x1949b098`) to the seed you want.
4. Ship those two as `kind = "ot"` patches rather than a copy of the file —
   see [Editing a plaintext .ot](/guides/modding/#editing-a-plaintext-ot-kind--ot).
   A whole-file override still works (`mods/<id>/assets/_root/DarkTalesResources/ApplicationSettings.ot`)
   but redistributes a game file and reverts whatever the next game patch
   changes elsewhere in it.

Until the settings block is fully decoded, the safer path is the in-
process route below.

## How to set it (Lua / DLL loader)

The loader DLL (`dist/winhttp.dll`) hosts a Lua VM per mod. To set the
forced seed from Lua you need one new `rsmm.*` binding that wraps a
write to the global option table. Skeleton (C++ side, `src/loader/`):

```c
// Resolve the GameOption registry once at boot via pattern signature
// (don't bake the absolute VA — it shifts on every game patch).
auto registry = ResolveGameOptionRegistry();

// Set the u32 field by id.
registry.SetUInt(0x1949b098, mod_seed);
// Flip the enable flag.
registry.SetBool(0x1949b099, true);
```

Expose as `rsmm.set_forced_seed(seed)`. Modder writes:

```lua
rsmm.on_event("ready", function()
    rsmm.set_forced_seed(42)
end)
```

## Other seed-adjacent symbols

| Address | What |
|---|---|
| `0x140f59758` | Field name `"m_uRandomSeed"` (entity persistent data) |
| `0x14073df80` | Function that registers the `m_uRandomSeed` field, class id `0x1bdf6dd3` ("Entity Cpnt Selector Persistent Data") |
| `0x140eef7f0` | String `"Rose seed"` — second seed channel (per-run RNG?) |
| `0x140ef13a8` | String `"CLEAR_ROSE_SEED"` — game event name, fires 48 places |
| `0x140ef1a70` | Format string `"Seed : {}"` |
| `0x140c92ef4` | `_Random_device` (40 bytes) — std::random_device singleton |

Decompiled bodies for every xref of these targets live under
`docs/_re/out/xref_targets/`. Open the `*.c` next to the symbol name
to see how it's used.

## What's still unknown

- The actual map-generation algorithm and where it pulls the seed
  from (per chapter? per map slot?). Need to follow the use of
  `m_uRandomSeed` through `oCEntityCpntSelector*`.
- Whether `Forced seed` overrides every RNG stream or only the
  top-level run seed. `Rose seed` looks like a separate stream so
  there may be more.

Next: trace `oCEntitySettingsResource` for the seed-consuming entity
("Entity Cpnt Selector"). The class registration at `0x14073df80`
gives the body offset (0x48) for the field, which is what an in-place
binary patch on a saved level cooked file would target.

---

# Skills (talents) system

> How a hero's skills are stored, deserialized, and laid out — and why a net-new visible talent is an architectural wall.

Source: https://docs.rsmm.me/reverse-engineering/skills-system/

:::note
Status: reverse-engineered via Ghidra MCP **and** the headless-decompile bypass
against `Ravenswatch.exe` (image base `0x140000000`), 2026-06-15 → 2026-06-17.
In-game these are **Skills**, not "talents" — no `Talent` string exists. This page
is the RE companion to the [Custom skills guide](/guides/custom-skills/).
:::

## TL;DR verdict

| Goal | Verdict | Path |
|---|---|---|
| Relabel / restat an existing skill | **Works, shipped** | Text-bank override (`mode="relabel"`) |
| Add a net-new skill *row* by editing the `.gen` | **Disabled — bricks the hero** | versioned deserializer rejects the extra row |
| Add a net-new skill at runtime (loader) | **Inject works, no crash** | grow the herodef skill vector |
| Make that net-new skill **visible** in the Book grid | **Architectural wall** | grid cell is computed from identity, not stored |

The shippable custom-talent path is **reskin/relabel an existing skill** (proven
live: `AladdinLightningDash`). A genuinely net-new, hero-page-visible talent is
not achievable by data or runtime injection — see [the grid wall](#the-grid-wall).

## System map

| Piece | Identity | Role |
|---|---|---|
| Per-hero skill set | `oCSkillProfileData(Settings)` | the hero's owned skills |
| Storage | `Definitions/Heroes/<Hero>.herodef.ot.DtHeroDefinition.gen` | a counted collection of skill rows |
| Runtime owner | `oCDtEntityCpntSkillController` | owns/upgrades the live skills |
| Hero-page UI | `SkillUiViewerEntityCpnt` / `oCDtEntityCpntSkillUiControllerSettings`, `Menu::SkillMenu` | enumerates + renders the grid |
| Tiers | rarities Common/Rare/Epic/Legendary/Ultimate → frames `HUD_Skill_Frame_01..05` | legendary = top tier |
| Display text | `Text/Hero_<Hero>_Common~GAM.xls.LocalText`, keys `Skill_<Suffix>_Name`/`_Desc` | what the player reads |

All 12 heroes carry **exactly 28** `Skill Controller` rows — names are
hero-specific, the count is invariant.

## Why a `.gen` row-splice bricks the hero

The herodef deserializer is **`FUN_14031e630`** — a strict **versioned, ordered**
field reader, not a "read until terminator" loop:

- Each field is gated by `FUN_1404fbea0(stream, …, 0x1768d0c9)` (the herodef
  type-version hash) compared against rising thresholds, then read into a fixed
  instance offset.
- The skill set is a counted collection, but **there is no plain `u32 == 28` in
  the `.gen` before the rows** (scanned ±0x120 across all heroes). The count lives
  behind a polymorphic header / nested object — position-variable.

So a byte-spliced 29th row desyncs **every subsequent versioned field read** →
the hero fails to load and vanishes from selection. Proven twice, GUID-independent
(remint and source-GUID both brick), so identity is not the cause. The SDK's
`mode="clone"` is hard-disabled for this reason.

## Runtime injection (what works)

The correct layer is the **item-pool pattern** applied to skills: don't touch the
serialized `.gen` — after a herodef deserializes, have the loader grow the runtime
skill vector and append a cloned element.

```mermaid
flowchart LR
    D["herodef deserialize<br/>FUN_14031e630"] --> H["loader detour<br/>hook_skills.cpp"]
    H --> V["skill vector @ herodef+0x8d8<br/>{ptr, u32 count, u32 cap}"]
    V --> C["realloc → 29, deep-clone<br/>SkillProfileDataSettings (0xd0)"]
    C --> R["remint GUIDs, repoint data/count/cap"]
```

Confirmed mechanically on all 12 heroes (no crash):

- **Skill vector = herodef `+0x8d8`** — `{void* data; u32 count; u32 cap}`, a
  pointer array (stride 8), `count == cap == 28` (exact-fit). The deserializer
  fills it via `FUN_14020d700(stream, herodef+0x8d8)`.
- Elements are **`oe::dt::SkillProfileDataSettings*`** — vftable `0x140efd018`,
  ctor `FUN_1400c9210`, size **`0xd0`**.
- Abilities live at herodef **`+0x8e8`** — an inline array, stride `0x240`, 7
  entries. They do **not** reference their talents (probed: zero pointers from any
  ability back into the `+0x8d8` array).

`SkillProfileDataSettings` (0xd0) field map, from runtime byte-diff:

| Offset | Meaning |
|---|---|
| `+0x00` / `+0x08` | vtables |
| `+0x10` | 16-byte **identity GUID** — engine dedups on it; remint or clones collapse |
| `+0x30` | `{ptr,u32,u32}` sub-vector of effect descriptors |
| `+0x40` | 16-byte secondary/skill ref GUID (unique per talent) |
| `+0xc0` | 0/1 flag (correlates with `+0xb8` upgrade-data ptr) — not tier |

The loader hook `hook_skills.cpp` ships this: detours `FUN_14031e630` (added as a
unique masked pattern to `data/function_patterns.json`). **Default read-only** —
logs `[skill-hook] herodef=.. skillvec count=.. cap=..`. Injection is gated behind
`RSMM_ENABLE_SKILL_INJECT` and self-guarded (acts only on `count∈[1,200]` with a
spare slot, so a wrong offset is inert).

## The grid wall

Injecting a 29th skill **does not make it appear** in the hero Book page. The
talent grid is **column = ability category, row = upgrade tier**, and both are
**computed at build time** — there is no `(x, y)` cell stored anywhere injectable:

- No tier/column field in the `0xd0` object (probed `+0x40`/`+0x50`/`+0x60`/`+0x68`
  /`+0x90`/`+0xac`/`+0xc8` across all 28 talents — all constant or shared statics).
- Abilities (`+0x8e8`) don't own talents.
- The `SkillUiViewerEntityCpntSettings` (size `0x388`, ctor `FUN_14043b240`,
  registrar `FUN_1403656f0`, type hash `0x15f63a0f`) holds only `oCEntityCpntPicker`
  sub-objects — refs to *which* controller it drives, **not** a per-cell list.

The column is derived from the skill's **name prefix** — `Skill_Attack_*`,
`Skill_Power_*`, `Skill_Special_*`, `Skill_Defense_*`, `Skill_Ultimate_*`,
`Skill_Passive_*`, `Skill_Dash_*`, `Skill_Trait_*` — resolved via
GUID → global registry (`DAT_1414364e8`, register `FUN_140320540`) → name →
category. A runtime clone inherits its source identity, so it lands on the
source's cell (overlap → invisible).

**Conclusion:** a visible net-new cell would require forging a *complete* new
identity (new GUID + registry registration + a name whose category/tier maps to a
currently-free cell) **and** hooking the grid build method — essentially authoring
a real new skill end-to-end. That is the same wall as the `.gen` clone-insert. The
wall is architectural, not a missing datum.

## Shippable paths

1. **Reskin / relabel an existing skill** — override its `Skill_*_Name`/`_Desc`
   text values, restat with [talent values](/guides/modding/), rewire its effect
   graph by swapping the 16-byte ref GUIDs. Hero-specific, upgradeable, and
   hero-page-visible because it *is* a real row. Live and proven.
2. **Additive pickable card** via the magical-object pool — a custom level-up card
   that isn't tied to the herodef grid at all. Bind behaviour with
   `R.talent.on_pick`.

## Going deeper

- [Custom skills guide](/guides/custom-skills/) — the SDK `skill` kind.
- [Mod hooks](/reverse-engineering/mod-hooks/) — the loader detours and env flags.
- [Ghidra MCP](/reverse-engineering/ghidra-mcp/) — and the headless-decompile bypass used here.

---

# Skins

> The nine hardcoded SkinPack slots, the Steam-ownership grid filter that hides a tenth, and why the cooked asset registry means there is no resolver to hook.

Source: https://docs.rsmm.me/reverse-engineering/skins/

:::note
Status: Tier-1 RE backing `src/loader/src/hook_skins.cpp`. The custom slot ships
(count detour + grid-filter detour). New `Skin` folders remain blocked on the
asset registry. Addresses are preferred-base VAs (image base `0x140000000`).
:::

## Summary

The selectable skin roster is **not data-driven**. There is no per-hero skin list
and no per-hero skin count. Skins are **9 global "SkinPack" slots**
(`oCAdditionalContent` entries) shared by every hero; a hero carries only a
pack-id int at `+0x78`, matched against an entry's `+0x3c` key. The roster is built
once at startup with the count written as the **immediate constant `9`** — so a
10th slot cannot be added by shipping a cooked file. It needs a runtime detour,
which the native loader already makes possible.

Same "no UID, built inline" shape as heroes — see
[Heroes](/reverse-engineering/heroes/).

## The roster builder

`FUN_1401dcae0(ctx)` runs once from the global game-systems bootstrap. It manages
a fixed array on the manager ctx and threads each entry into a global linked list:

```
ctx + 0x13c0   oCAdditionalContent* array  (malloc/realloc'd to 9*0xA0 = 0x5A0)
ctx + 0x13c8   count      <- *** immediate 9 *** (mov dword [rcx+0x13C8], 9)
ctx + 0x13cc   capacity   <- pinned to 9
```

Each entry is `0xA0` bytes. The loop (`i = 0..8`) fills:

| Off | Type | Source array (`.rdata`, stride) | Meaning |
|--------|-------------|---------------------------------|----------------------------|
| +0x00  | vtable      | `oCAdditionalContent::vftable`  | set by ctor |
| +0x08  | ptr         | list: next (old head)           | linked-list field |
| +0x10  | ptr         | list: back-link slot            | written into prev head |
| +0x18  | ptr         | `DAT_141436590` (manager)       | owner |
| +0x30  | u64         | `5`                             | type/state enum (ctor) |
| +0x3c  | i32         | `DAT_140f07b80` (×4)            | **pack key** (`hero+0x78` matches this) |
| +0x48  | i32         | `DAT_140f0d8a0` (×4)            | 1-based index (1..9) |
| +0x50  | std::string | `0x140f08380` (×0x10)           | AC asset id `RW000PSAC000000N` |
| +0x60  | std::string | `0x140f06de0` (×0x10)           | AL asset id `RW000PSAL000000N` |
| +0x70  | std::string | `0x140f0e830` (×0x10)           | base id, `9PM96K8TFJC4`-style |
| +0x90  | std::string | `0x140f0d8e0` (×0x10)           | display name, `"… SkinPack"` |

Shipped names[0..8]: Fairytales / Ravens / Nightmares / Unleashed SkinPack,
Romeo & Juliet HeroPack, Romeo & Juliet SkinPack, Timeless SkinPack, Merlin
HeroPack, Mercenaries SkinPack.

### Per-entry construction (two helpers, reused by the detour)

- `FUN_140214bb0(base, count)` — placement ctor: sets the vtable at `+0x00`,
  `+0x30 = 5`, zeroes the list fields, and initialises the four string members to
  the empty sentinel `{ ptr=&DAT_140ed5a10, lenflags=0x80000000 }`.
- `FUN_1405288b0(dst_slot, src_desc)` — string assign. `src_desc` is a 16-byte
  `{ const char* ptr; u32 lenflags; u32 pad }`. The high bit of `lenflags`
  (`0x80000000`) means **literal / non-owned**: the helper adopts the pointer
  verbatim, so the backing string must outlive the entry. Pass `lenflags = len`
  (no high bit) to force an owned heap copy.

### Global manager list

`DAT_141436590` is a **pointer load** — the global holds
`oIAdditionalContentManager*`. Consumers (skin-grid populate, selection handlers)
walk this list, **not** the fixed array, so a new node only needs to be on the
list.

```
mgr + 0x08   i32 node-count
mgr + 0x10   head
mgr + 0x18   tail
```

Push-front sequence the builder uses — replicate exactly:

```c
e[0x18] = mgr;                              // owner
if (mgr[0x08] == 0) mgr[0x18] = e;          // empty -> tail = e
else                (*mgr[0x10])[0x10] = e; // old_head+0x10 = e
e[0x08] = mgr[0x10];                        // e->next = old head
mgr[0x08] += 1;
mgr[0x10] = e;                              // head = e
```

## Append strategy

POST-detour the roster builder. After the engine builds its 9 entries, allocate
**standalone `0xA0` nodes** — not in the fixed array, so the engine's
realloc/shrink on a re-run can't clobber them — construct each with the placement
ctor, set `+0x3c`/`+0x48`, assign the 4 strings, and push onto the manager list.
Guarded by `std::call_once`. The helpers are pattern-resolved and verified before
call, so the hook degrades to a no-op on a future patch instead of jumping into
moved code. The only hardcoded absolute is `DAT_141436590`, relocated by the live
image base.

## Authoring

```python
from rsmm import sdk
with sdk.Mod("crimson_skins", version="1.0.0", author="me", name="Crimson Skins") as m:
    m.skinpack("Crimson Pack", key=0x900001,
               ac_id="RW000PSAC000000A", al_id="RW000PSAL000000A", base_id="CUSTOM01")
```

`Mod().skinpack(name, key, *, ac_id, al_id, base_id)` writes
`mods/<id>/skinpacks.json`. The loader aggregates that across every **enabled**
mod (plus an optional hand-authored top-level `mods/skinpacks.json`); keys must be
unique across all sources.

## The grid filter — why a new key was invisible

The roster list is built; the *grid* is a separate, filtered copy. The populate
`FUN_1401f0f10(ctx, scene)` walks the manager list and for each node calls the
manager's **vtable[1]** filter:

```
RAX = [mgr];  iVar = (*(int(*)(void*,void*))[RAX+0x8])(mgr, node);
if (iVar == 3) <push node into ctx grid vector>
```

Only nodes scoring `3` become buttons. The grid vector lives on the screen ctx as
a `{ptr; i32 count; u32 cap}` triple at `ctx+0x2f8` / `+0x300` / `+0x304`, grown
through `FUN_140154c20(vec, <unused RDX>, u32 new_cap)` — **the new capacity is
the 3rd integer arg (R8)**; RDX is dead at the call sites.

### Which filter is live

Three instantiable manager variants exist (the base is abstract), vtables
recovered via `ExportVftables.java` → `data/vftables.jsonl`:

| Class | Slot[1] | Behavior |
|-------|---------|----------|
| `oIAdditionalContentManager` `0x140f3e288` | `0x1400c07a0` | `return 0;` — stub, always reject |
| `oCNullAdditionalContentManager` `0x140f3e1e0` | `0x1400c07a0` | same stub (inherited) |
| `oCLocalAdditionalContentManager` `0x140f3e578` | `FUN_140647440` | reads `char**` at `node+0x80`, prepends `\\?\`, `GetFileAttributesW` — file exists → 3 |
| `oCSteamAdditionalContentManager` `0x140f8db00` | `FUN_140a2c600` | reads the u32 key at `node+0x3c`, `ISteamApps::BIsDLCEnabled` — owned → 3 |

A brand-new key fails both: Steam doesn't know the key, and `node+0x80` is NULL on
the local path. **Verified at runtime** (Linux, GE-Proton10-34, Steam build): the
active filter is the Steam one, and a custom node logged `filter=0`.

### The filter detour (default-on)

`hook_skins.cpp` MinHook-detours the grid filter so custom packs pass the gate as
proper buttons. `hook_filter(mgr, node)` returns `3` when the node's key matches a
registered pack and forwards every other node to the original, so vanilla DLC and
skin slots keep their real ownership / file-existence checks.
`RSMM_SKIN_FORCE_SHOW` is retained only as a fallback diagnostic.

**The filter address is read from the live vtable, not pattern-resolved.**
`install_filter_hook(mgr)` reads `*(*(void**)mgr + 8)` — the actual slot the engine
calls — and hooks that. Correct for whichever manager class the build constructs,
and it needs no per-function signature.

:::caution
The `function_patterns.json` entries for `FUN_140a2c600` and `FUN_140647440` are
**stale** — each resolves to a single *wrong* address and the recorded VA isn't
among the matches. Do not `fn_resolve` these two until the patterns are
regenerated; the vtable read sidesteps them entirely.
:::

## Asset naming

The `(hero, pack) → model/material` resolver is un-decompiled, but the cooked-asset
naming it expects is fully enumerable from `data/asset_map.json` (2280 hero-skin
texture entries). Per (hero, skin):

```
3D\Characters\Heroes\<Hero>\Textures\<Skin>\M_<Hero><Skin>.mat.ot.Material.gen
3D\Characters\Heroes\<Hero>\Textures\<Skin>\M_<Hero><Skin>Static.mat.ot.Material.gen
3D\Characters\Heroes\<Hero>\Textures\<Skin>\T_<Hero><Skin>_ALB.tga.Texture.dxt   (albedo)
3D\Characters\Heroes\<Hero>\Textures\<Skin>\T_<Hero><Skin>_EMI.tga.Texture.dxt   (emissive)
3D\Characters\Heroes\<Hero>\Textures\<Skin>\T_<Hero><Skin>_MRA.tga.Texture.dxt   (metal/rough/ao)
3D\Characters\Heroes\<Hero>\Textures\<Skin>\T_<Hero><Skin>_NRM.tga.Texture.nrm   (normal)
```

60 vanilla skin folders exist (Classic, Dark, Raven, Pirate, Dracula, 1001Nights,
Nightmare, Royal, Lich, Djinn, …).

### There is no runtime resolver to hook

After an exhaustive search across all 54,450 decompiled functions and the full
`.text` section:

- **No function** builds cooked asset path strings from AC/AL/Base ID fragments at
  runtime.
- **No function** reads entry offsets `+0x50`/`+0x60`/`+0x70` and builds a path.
- The AC/AL IDs are referenced **only** in the roster builder.

The engine uses a **cooked binary asset registry** — the same one that produces
`data/asset_map.json`. AC/AL/Base IDs are opaque keys into it, resolved at cook
time, not by runtime string concatenation.

So hooking a resolver is neither possible nor necessary. The correct approach is
the one the CLI already uses: on-disk file replacement at the cooked path, scoped
to an existing slot's `Textures/<Skin>/` folder (**not** the hero's default-skin
path, or you mutate the default skin). Custom skins needing brand-new `<Skin>`
folders wait on the asset-registry format being reverse-engineered.

---

# Spawn system

> The spawner-component pipeline behind enemy/pet/prop creation, and the engine call R.spawn is built on.

Source: https://docs.rsmm.me/reverse-engineering/spawn-system/

:::note
Status 2026-09-13: **the instantiator is found** and `R.spawn` is built on it
(`src/loader/lua/rsmm/spawn.lua`); in-game proof is still owed. Every engine
spawner ends in
`EntityStore_CreateEntity(sceneSpawner, settings, &spawnData, nullptr)`: the
template is an `oCEntitySettings` (a resource's embedded one lives at `+0x98`),
whose own spawnable pool constructs the entity. The spawner is the
`oCEntitySpawner` at `+0xa0` of the scene's `oCEntitySceneContext`. The spawn
data holds position (`+0x10`), quaternion (`+0x1c`), scale (`+0x2c`) and parent
(`+0x38`). The full evidence table is in `docs/_re/kinds/spawn-system.md` and
on the `EntityStore_CreateEntity` symbol. The June notes below are kept as
history. Their conclusion, that the instantiator was statically unreachable,
turned out to be wrong.
:::

## Goal

A generic SDK `R.spawn(template, transform)` that instantiates any entity
(rat/pet/enemy/prop) at runtime. The loader already exposes typed FFI by symbol
(`_internal.resolve`/`call`), so the SDK side is light **once the spawn fn + ABI
is known** — the whole cost is the RE.

## Pipeline

Entities are **not** spawned by a global `spawn(template, pos)`. The path is a
generic spawner component that holds a candidate-template list and instantiates
on tick:

1. **Picker** — `Enemy_RuntimeSpawnPicker` (`FUN_140330db0`). Enumerates enemy
   defs from the class registry (`Registry_EnemyDefinition_desc` `0x141470208`),
   filters by tier/flags/tribe, weighted-random picks, then lazily resolves each
   picked def's entity ref via `ResourceRef_Resolve` (`FUN_140491690`) →
   resolved template ptr at `def+0x2b8`.
2. **Spawn-data entry** — an `oCEntitySettingsRootPtr` (0x30 bytes): alloc
   `FUN_140338fa0`, fill `FUN_1406e5ef0` (typed-ref setter — stores the resolved
   template at `entry+0x18`, refcounts it, registers on the template's
   resolve/unresolve notify lists). A live, refcounted, auto-invalidating handle.
3. **Spawner candidate vector** on the component — `spawnerCpnt+0x68` data,
   `+0x70` count, `+0x74` cap (stride 8). The picker push_backs here. The prepare
   step `FUN_140330c30` resizes two parallel arrays at `+0x80`/`+0xa0` and stores
   an RNG seed at `+0xb8`.
4. **Instantiation — NOT located.** A later component virtual consumes
   `+0x68`/`+0x80` and creates live entities at the spawner transform (a 0x40-byte
   4×4 f32 matrix, not bare xyz). This is the remaining RE target.

## Why the instantiator is unreachable

Three Ghidra-MCP passes plus two headless passes converged: the runtime
create-entity routine is **vtable-dispatched** on the runtime component class
(`oCEntityCpntEntitySpawner` / `oCSpawnerGoEntityCollector`), whose metaclass/
vtable registrations sit in code regions Ghidra left **undefined**. The seeds
that looked promising resolved to *Settings* class registrars (reflection
metadata only — no instantiation):

- `0x140228547` → registrar for `oIEntityCollectorSettings` (hash `0x12cccf23`).
- `0x1402fadb9` → registrar for `oIEntityCpntSettings` (hash `0xc608329`).

The `oCEntitySpawnerGo` cluster (`FUN_140745620` build / `FUN_140745200`
activate) is the **editor/preview gizmo layer** — it builds a preview sub-level,
never a gameplay entity. Surgical static RE is exhausted.

## Levers (cheapest first)

- **A. Hijack a live spawner.** Enemy camps already hold configured spawners with
  valid transform/faction/scene context. Append a resolved-template entry to an
  existing spawner's `+0x68` vector, then let its tick instantiate with correct
  context. (Caveat: appending to the *selector*'s `+0x68` and ticking it **frees**
  entries — the live spawner must be the instantiating component, not the selector.)
- **B. Call the instantiator directly.** Needs the create fn + its full context
  ABI RE'd first.
- **C. Cold-construct a spawner.** Most general, most work.

## Recommended next step — dynamic trace

Static RE can't pin the create fn. Detour the selector prepare virtual
`FUN_140330c30` (clean unique pattern, like `hook_skills.cpp`) to capture a live
`spawnerCpnt` + its owning entity at runtime, then trace the subsequent vtable
calls to the actual create call site with real pointers. Needs a loader build +
playtest.

:::tip[Shippable now for the Piper rat-spawn goal]
No spawn primitive needed — tune the vanilla Ghost-Horde talent's two values
(notes, rats) and apply. See [Pickable talents](/reverse-engineering/pickable-talents/).
:::

## Symbols

In `data/symbols.json`: `Enemy_RuntimeSpawnPicker` `FUN_140330db0`,
`Registry_EnemyDefinition_desc` `0x141470208`, the ResourceRef resolve path.
To add once located: the entity factory, `SpawnEntry_Alloc` `FUN_140338fa0`,
`SpawnEntry_SetTemplate` `FUN_1406e5ef0`, `oCEntitySpawner::vftable` `0x140f023f8`.

---

# Spawning

> How the engine creates a single entity at a position — the spawn primitive.

Source: https://docs.rsmm.me/reverse-engineering/spawning/

:::note
Status: confirmed via live Ghidra MCP session against
`Ravenswatch.exe`. Companion to
[`MOD_HOOKS.md`](/reverse-engineering/mod-hooks/) (level-load pipeline + library ABI)
and [`HOOKPOINTS.md`](/reverse-engineering/hookpoints/) (feature → function map).
:::

This page documents **how the engine actually creates one entity at a
position** so the SDK can drop the clone-and-patch-asset-only workflow
in favor of a real "spawn this thing here" call.

## TL;DR

The spawn primitive is a `vftable[3]` call on the scene context's
inline **`oCEntitySpawnerGo`** dispatcher. The signature is:

```c
oCEntity* Spawn(oCEntitySpawnerGo* this,
                void*              position_handle,   // from FUN_140678250
                oCEntitySpawnData* spawn_data);       // transform + flags blob
```

Both `SpawnAllObjects` (magical objects) and `SpawnAllMelodies` call
the **same** virtual through a dispatcher stored inline in the
relevant library/scene-context (object case at `+0x30`, melody case at
`+0x28`). The result is a freshly-constructed entity that can then be
walked via `FUN_1406ca380(entity, oCMetaClass*)` to attach the
type-specific definition pointer.

## The spawn dispatcher

### Function pointer used in the wild

Object loader (`FUN_140254280`, "InitialLoading - MagicalObject SpawnAllObjects"):

```c
(**(code **)(param_1[6]    + 0x18))(param_1 + 6,    uVar7, &spawn_data);
// param_1[6]    == *(qword*)(lib + 0x30)    // dispatcher vftable ptr
// param_1 + 6   == lib + 0x30                // dispatcher 'this'
```

Melody loader (`FUN_140255a90`, "InitialLoading - Melody SpawnAllMelodies"):

```c
(**(code **)(*(longlong *)(param_1 + 0x28) + 0x18))
   ((longlong *)(param_1 + 0x28), uVar7, &spawn_data);
```

In both cases the inline dispatcher is initialized by `FUN_1406e7210`
called near the start of the loader on `scene_context + 0x1a8` — the
scene context owns the dispatcher and the loaders simply bind it to
their library before iterating.

### Layout of the dispatcher object

| Offset | Field | Notes |
|---|---|---|
| `+0x00` | `void** vftable` | first qword; `[3]` (byte `+0x18`) is `Spawn` |
| `+0x190` | `oIEntityCpnt** components` | array head, walked by `FUN_1406ca380` |
| `+0x198` | `u32 component_count` | matching count for the head above |

The MetaClass class-name string is `"oCEntitySpawnerGo"` (string at
`0x140ee43f0`). Its sibling state class is `"oCEntitySpawnerGoState"`
(`0x140ee4598`).

## `oCEntitySpawnData` — transform + flags blob

Constructed inline by every caller before `Spawn`. Size 0x60 bytes
(matches the `oCEntitySpawner` `sizeof` from
[`MOD_HOOKS.md`](/reverse-engineering/mod-hooks/#registry-key-is-32-bytes-not-4)).

| Offset | Field | Value written by loaders |
|---|---|---|
| `+0x00` | `vftable` | `oCEntitySpawnData::vftable` |
| `+0x08..+0x18` | pad / 0 | `0` |
| `+0x18` | `flags` (`u32`) | `_DAT_140fa4470` (default spawn flags) |
| `+0x1c..+0x28` | reserved | `_UNK_140fa4474`, `_UNK_140fa4478` |
| `+0x30..+0x38` | `scale_xy` (`f32 x2`) | `0x3f8000003f800000` = `(1.0f, 1.0f)` |
| `+0x38..+0x3c` | `scale_z` (`f32`) | `0x3f800000` = `1.0f` |
| `+0x40..+0x60` | unused / 0 | `0` |

Anything left zero means "use defaults" — the loaders don't override
position from inside the struct (position comes in via the second
argument, the position handle).

## Position handle — `FUN_140678250`

Signature:

```c
TransformNode* FUN_140678250(void* pool_root /* def + 0x18 or def + 0xb0 */);
```

This is a **pool allocator**: it pops a free `TransformNode` off the
intrusive linked list at `pool_root`, links it into the active list,
and returns the pointer that callers pass straight into `Spawn`.

* The pool root for magical-object spawns is `def + 0x18` (object
  case) or `def + 0xb0` (melody case) — the per-definition spawn
  anchor.
* The returned `TransformNode` holds a placeholder world transform
  (`-1` sentinel in slot `[3]`) that the spawned entity's components
  fill in during construction.

For a custom mod that wants to spawn at an arbitrary world position,
write the world transform into the returned node **before** calling
`Spawn`, or skip `FUN_140678250` entirely and synthesize a transform
node by hand (size + layout still TBD — `# TODO: confirm`).

## Generic by-name lookup — `FUN_140463210`

```c
void* FUN_140463210(void* table, const char** name_token);
//
//   table + 0x80   -> ptr to entry array
//   table + 0x88   -> entry count (u32)
//   entry + 0x50   -> char* name (cstr)
//   name_token[0]  -> char* search name
//   name_token[1]  -> u32 length / hash (only low 31 bits used)
```

Linear scan. Used inside the level-load orchestrator to resolve
`MENU_SPAWNER`, `BOOK_SPAWNER`, etc. by name; the returned entry's
`+0x160` field is the actual spawner instance whose `Spawn` you call.

## Find sub-component by type — `FUN_1406ca380`

```c
oIEntityCpnt* FUN_1406ca380(oCEntitySpawnerGo* go, oCMetaClass* meta);
//
//   walks go[+0x190..+0x198] (u32 count) array of oIEntityCpnt*
//   each entry's vftable[0] returns its meta; vftable[0x58] is
//   MetaClass::IsKindOf(meta).
//   returns first match, or NULL.
```

Called right after `Spawn` to fish out the typed component the loader
wants to wire the def pointer into. Generic — works for **any** kind.

## High-level recipe — spawn one entity from a def

```c
// 1) Resolve the def by name through the library's vftable[3]
//    (oIResourceManager::FindOrLoad — see MOD_HOOKS.md).
oCDtMagicalObject* def = lib_FindOrLoad(magical_obj_lib, "rwd_my_sword");

// 2) Init spawn_data + grab a position handle.
oCEntitySpawnData sd = {};
sd.vftable  = oCEntitySpawnData::vftable;
sd.flags    = _DAT_140fa4470;
sd.scale_x  = sd.scale_y = sd.scale_z = 1.0f;
TransformNode* pos = FUN_140678250(((char*)def) + 0xb0);

// 3) Call Spawn through the scene-context dispatcher
//    (lives inline at scene_ctx+0x1a8's "+0x30" field on the lib).
oCEntitySpawnerGo* go = lib_dispatcher(magical_obj_lib);
oCEntity*          ent = (*((Spawn_t**)go)[3])(go, pos, &sd);

// 4) Bind the def to the typed component on the spawned entity.
oIEntityCpnt* cpnt = FUN_1406ca380(ent, DAT_141447f48 /* obj meta */);
cpnt->m_def = def;
```

Repeat for any other kind by swapping the library, the meta-class
pointer, and the position-pool offset.

## Cross-references — known meta-class pointers

| Kind | MetaClass global | Used in |
|---|---|---|
| `oCDtEntityCpntMagicalObject` | `DAT_141447f48` | `FUN_140254280` (objects) |
| `MelodyDefinition` typed cpnt | `DAT_141448040` | `FUN_140255a90` (melodies) |
| `oIGameUiOwner` (UI spawners) | `DAT_141446f38` | `FUN_14025b9e0` (UI spawn loop) |
| `oCDtRewardDefinition` | `DAT_141447bd0` | reward selector resolve |
| `oCEntitySpawner` registry | `DAT_141446ed8` (UID `0x17bcd54b`, size `0x60`) | spawn primitive class |
| `oCSpawner` registry | `DAT_141447238` (UID `0xc3baa69`, size `0x58`) | base class |

## Named-event surface (alternative path)

The string `"Spawn"` at `0x140ef851c` is a **state name**, not an
event — it's pushed into a `hero.state` metric inside `FUN_140391400`
(state-machine logger). It is **not** a `oCGameNamedEvent` you can
fire to make something spawn.

The real named-event spawn surface is documented in
[`MOD_HOOKS.md` "The mod hook surface"](/reverse-engineering/mod-hooks/#the-mod-hook-surface):

| Event | CRC global | What fires it |
|---|---|---|
| `"Generate rewards"` | `PTR_DAT_1412c0998` | `LevelGs_StateLoadingResource_Load` stage 10 |
| `"Generate enemy camps"` | `PTR_DAT_1412c09e0` | stage 12 |

Listening to these events lets a mod *react* during scene
construction and call the spawn primitive above without patching the
level-load orchestrator.

## What this unlocks for the SDK

Phases 1 & 2 (the existing `_pending_*` manifests):
* still required — the def has to *exist* in its library before
  anyone can spawn it.

Phase 3 (new, now feasible):
* **Runtime spawn API** — once the loader DLL stabilizes, expose
  `rsmm.spawn(def_path, x, y, z)` that resolves the def, allocates a
  `TransformNode`, fills it with the caller's world position, and
  invokes `Spawn` through the scene-context dispatcher.
* **Listener-based content** — a mod can subscribe to
  `"Generate rewards"` / `"Generate enemy camps"` via the
  named-event listener API (once that's mined, see
  [`MOD_HOOKS.md` "Still to be confirmed"](/reverse-engineering/mod-hooks/#still-to-be-confirmed))
  and call `rsmm.spawn(...)` from the listener.

## Still to be confirmed

* `TransformNode` byte layout (size, field offsets for position/rotation/scale).
* `oCEntitySpawnData::vftable` actual address (anchor `0x140fa4470` is
  a *flags* word, not the vftable itself — the vftable address shows
  up in the disassembly literal, needs a Ghidra label).
* The dispatcher's per-library offset table (object lib uses `+0x30`,
  melody lib uses `+0x28`, enemy + reward libs unmined).
* `oCGameNamedEvent` listener registration API (open across
  [`MOD_HOOKS.md` "Still to be confirmed"](/reverse-engineering/mod-hooks/#still-to-be-confirmed)
  and [`HOOKPOINTS.md` recommended first POC](/reverse-engineering/hookpoints/#recommended-first-poc-for-rsmmhook-validation-task-6)).

---

# Stats & XP

> The three surfaces hero stats live on, the CRC-keyed value store's read and write paths, and why a raw write is transient unless it becomes a modifier.

Source: https://docs.rsmm.me/reverse-engineering/stats/

:::note
Status: RE complete; `R.stat` / `R.xp` / `R.combat` ship in
`src/loader/lib/rsmm.lua` and are **in-game proven** (XP grant drives the engine's
own level-up loop; `R.stat.modify` composes and survives recompute).
:::

## The three stat surfaces

Ravenswatch keeps hero stats in three distinct places. "Everything grantable"
means covering all three:

| Surface | What lives there | Grant primitive | SDK |
|---|---|---|---|
| **Plain shard field** | current dream shards (hot path, mirrored to the HUD) | `Hero_ModifyDreamShards(hero, delta, tags)` | `R.shards.get/add/spend/set` |
| **XP component** | level + xp-within-level (own component, curve table) | `Hero_GainExperience(xpComp, xpGain)` | `R.xp.grant` |
| **Generic value store** | everything else: max-health mult, attack power, crit, move speed, cooldown, life-steal, dream shards, xp multipliers, status stacks | modifier / override write | `R.stat.get/set/modify` |

Dream shards are the exception with a plain `f32` at `hero+0x15c8` — see
[Heroes](/reverse-engineering/heroes/). Everything else is keyed in the store.

:::caution[Corrected 2026-09-18]
This field was documented as **HP** for months, and the routine as
`Entity_ModifyHealth`. It is the dream-shard count: the routine fires
`dt_shard_gain` / `dt_shard_loss`, clamps only at 0, and is what the Sandman
spends through. `R.combat.*` and `R.entity.hp/max_hp/hp_frac` still work as
deprecated aliases of `R.shards`.
:::

## Real health

HP lives on the hero's `oCEntityCpntHitPoint`: `component = *(*(hero+0x2f8)+0x78)`,
current HP at `+0xe8`, max at `+0xec`. `*(hero+0x2f8)` is the sibling
`oCDtEntityCpntCharacterController`, not the entity (measured in game); the
component's owner at `+0x8` is the hero's `oCEntity`, `*(hero+0x8)`. The only
writer is `HitPoint_SetHitPoints` (`0x140822db0`). It clamps to `[0, max]`, runs
the death listeners (`+0x108`) when HP crosses 0 and the change listeners
(`+0xf0`) on any change, replicates, and writes `current/max` to the UI bar.
Thirteen gameplay readers walk the same chain; the "Increase damage if
critical health" check and the life-bar listener both divide the pair.

`R.hp.get/max/frac` read it, and `R.hp.set/heal/damage` go through the setter.
Every access re-checks the link: RTTI must name a HitPoint class, and the
component's owner must be the hero's entity. Static RE only (2026-09-18);
the in-game proof is still owed. In co-op HP is host-authoritative, so a
client's write is not expected to stick.

:::caution[Units]
Store values are **display × 100**. To set a displayed number, pass
`display / 100`.
:::

## Dream shards

`Hero_ModifyDreamShards` is the game's own gain(+)/spend(−) routine, resolved by
pattern. Hero-only — it derefs the HUD mirror. See
[Combat & damage](/reverse-engineering/combat-damage/).

## XP / level-up

`Hero_GainExperience(xpComp, xpGain)` adds `*(int*)(xpGain + 0x50)`. It reads the
current level/xp, loops subtracting the per-level threshold and levelling up, then
commits via `XpComponent_SetXp` / `XpComponent_SetLevel`.

- Progress struct: `*(xpComp + 0x108)` → `{[0]=level u32, [4]=xp-in-level u32}`.
- Curve def: `*(xpComp + 0x10)` → `{+0x1d0 has-table, +0x1d8 uint[] thresholds,
  +0x1e0 count/maxLevel}`.
- `XpComponent_SetLevel` fires the `_XP_LEVEL_UP` named event and writes
  custom-flag `0x12e831f2` (= level, f32). `XpComponent_SetXp` writes custom-flag
  `0x12e831f1` (= xp delta). The `level_up_*` analytics are downstream telemetry,
  not the grant.

### Locating `xpComp`

The XP component is a *sibling component* on the hero's `oCEntity`, not a fixed
hero offset:

```
entity = *(heroController + 0x2f8)          # (or hero+0x2f8 itself on some paths)
arr    = *(entity + 0x190); count = *(uint*)(entity + 0x198)
xpComp = arr[i] where *(arr[i]) == XpComponent_vftable (0x140f23200)
invariant: *(xpComp + 8) == entity          # every component's owner back-ptr
# alt: Entity_GetComponentByTester(entity, XpComponent_TypeTester = 0x141476e00)
```

In-game the exact-vftable scan kept missing — the live component's vftable is a
subclass vftable. `grant()` (main thread only; the walk calls each component's
virtual `IsKindOf`) falls back to `Entity_GetComponentByTester`, logs the actual
vftable of the hit, and caches the component per hero so the tick-thread readers
stay pure-memory.

## The generic value store

### Read path

```
ctx   = *(hero + 0x2f8)      # POINTER field — load it, do NOT pass hero+0x2f8 itself
store = *(ctx + 0x4c8)       # EntityValue_Get(ctx, out, key) does this deref

EntityValue_Lookup(store, &out, key):
  1. linear-scan OVERRIDE array  store+0xc0 (count +0xc8, 0x38-byte entries, key @+0x00)
  2. fallback base hash map       store+0x80 (Fibonacci mult 0xde5fb9d2630458e9)
  3. miss => union value 0
```

:::danger
Passing the **field address** `hero+0x2f8` instead of loading the pointer makes
the engine read `*(hero+0x7c0)` — a float — as the store pointer and fault. That
was a real in-run crash (store = `0xbf800000` = `-1.0f`, read at `store+0xc8`).
The engine's own damage-taken caller loads `ctx = *(param_1+0x2f8)` before every
`EntityValue_Get`.
:::

`oCEntityValueUnion` (0x20 bytes, vftable `0x140f95008`): `+0x08` inline sentinel
(`== 4` ⇒ value inline), `+0x10` inline value (f32/int32), `+0x18` type-tag byte
(`0` = int/float). Inside a 0x38 override **entry** the union sits at `entry+0x08`,
so sentinel `entry+0x10`, value `entry+0x18`, tag `entry+0x20`.

### Write path

There is no clean setter export — it's an inlined find-or-create:

```
scan store+0xc0 for key
  found + changed -> write union value (+ u32@entry+0x28, u16@entry+0x2c)
  miss            -> slot = EntityValueOverride_Alloc(store+0xc0, count, 1)
                     EntityValueEntry_Ctor(slot, src)     # auto-increments count at store+0xc8
```

**`store+0xc0` is the computed result cache**, so a raw override write is
**transient**: `EntityValueStore_Recompute` rebuilds it from base + modifiers on
the next dirty event (item pickup, level-up, …). Base values live in the hash map
at `store+0x80`.

Reactive events fire for free — the store's observer lists (`store+0x108`,
`+0x120`, `+0x138`, `+0x150`, `+0x158`) dispatch on any write, so a value change
already emits the reactive gameplay-bus events. There is no separate "set signal"
call.

## Stat key catalog

Keys are **structured base+index ids, not CRC32 of the label** — adjacent stats
differ by 2, and slot families are `base + 2·slotIndex`. Source of truth is
`EntityValueRegistry_RegisterAll` plus siblings `FUN_1401d66a0` (combat/build),
`FUN_1401da350` (session: shards/xp/difficulty), `FUN_1401d9070` (status effects);
each stores its key at `def+0x6c`.

| Stat | Key | Kind |
|---|---|---|
| max health (base "Vitality") | `0x188671a6` | f32 |
| max health % | `0x15c9296d` (default 1.0) | f32 |
| attack power (base) | `0x15a486c4` | f32 |
| attack power per slot | `0x15a5cf40 + 2·slot` (basic `0x15a5cf51`, dash `0x183a609a`) | f32 |
| crit chance (base) | `0x15c7d482` | f32 |
| crit chance per slot | `0x15c7d486 + 2·slot` (basic `0x15c7d484`, dash `0x183a60b6`) | f32 |
| crit damage | `0x15c82d13` | f32 |
| move speed ("Move Speed Ratio") | `0x044dadde` | f32 |
| cooldown reduction (base) | `0x15b45d80` | f32 |
| cooldown reduction per slot | `0x15b45d84 + 2·slot` (basic `0x15b45d82`, dash `0x183a5fc9`) | f32 |
| life steal | `0x15c028c2` | f32 |
| life on hit (base) | `0x1894f1a2` | f32 |
| dream shards (currency count) | `0x171c27b5` | int |
| Global Xp Modifier | `0x187afd1d` | f32 |
| Difficulty Xp Modifier | `0x19bddb2e` | f32 |

Slot index: `primary=0, secondary=1, defensive=2, trait=3, ultimate=4`.
Status-effect family: `0x16ede056 + 2·i` →
Strength/Regen/Haste/Concealed/Resistant/Rooted/Vulnerable/Ignite/Chilled/Poison;
Shield `0x173fcd75`, Bleed `0x173fcdac`, Cursed `0x1a5d3d69`, Marked `0x1a40367d`.
The full modifier/difficulty key table is in
[Game modifiers](/reverse-engineering/game-modifiers/).

**Attack power is a percentage, not a flat bonus.** Every hit is built by the
hit-value constructor (`0x1401ce0b0`) with a damage multiplier of `1.0` at
`hit+0xcc`. The hit resolver then adds the base value (clamped at 0, `0x1403c6e8e`)
and the ability slot's value (`0x1403d6632`), and multiplies the damage by the
sum:

```
damage = base × (1.0 + max(0, attack_power) + attack_power[slot]) × hit+0xd0
```

So `0.5` in the store is **+50% damage**, which the stat screen shows as
`+50`: it is the same ×100 as crit, where `0.15` shows as 15%. `50` in the
store is +5000%, a 100× overdose.

**Not keyed**, so not `R.stat`-settable: raw XP amount (use `R.xp`), armour base
(a hero field, `def+0x6c = 0`), gold (the game has none — only dream shards).

## SDK surface

```lua
R.stat.get("attack_power")          -- read (always safe)
R.stat.names()                      -- known stat names
R.stat.enable_writes()              -- opt in to writes
R.stat.set("move_speed", 1.5)       -- write override cache (TRANSIENT)
R.stat.add("crit_chance", 0.1)      -- current + delta (transient)
R.stat.stick("attack_power", 0.5)   -- durable by re-assertion (+50%)
R.stat.unstick("attack_power")      -- stop pinning
R.stat.modify("attack_power", 0.5)  -- durable engine modifier (+50%, composes)
R.xp.level(); R.xp.xp()             -- read
R.xp.grant(100)                     -- add XP (levels up) — already durable
```

Writes are engine-mutating: **main thread only** (gameplay-event handler or
`R.schedule.next_main`), opt-in via `enable_writes()`, and fail closed on any
implausible pointer. Loader reads/writes are page-guarded, so a wrong deref
no-ops; the residual crash surface is the engine calls, which are gated behind
plausibility checks. Stat modifiers persist in the **run** save, not the profile.

## Making a write durable

`EntityValueStore_Recompute` (`FUN_140749a90`) reseeds each key from its base
value whenever it goes dirty (`store+0x64 & 8`), then folds in every entry of the
**per-key modifier registry** (a SwissTable at `store+0x88`), applying each via a
vcall `(*(modifier+0x18))(modifier, valueUnion)`. So a raw cache poke is discarded.

The engine's own entry point is **`EntityValueStore_ApplyModifierEvent`**
(`FUN_14074b2f0`): it takes a built modifier request, constructs an
`oCEntityValueModifier`, inserts it into the registry, and re-folds the cache.
Combine mode comes from the value def:

| op | fold | meaning |
|----|------|---------|
| 1  | `val += amount * scale` | additive |
| 2  | `val = amount`, base `= base` | set / override |
| 3  | replace modifier with matching source/id | match-replace |
| 4  | keep smallest-delta | min / priority cap |

### Two durable strategies

**1. Re-assertion — `R.stat.stick`.** Keep re-applying the override poke after
each recompute, drift-gated on the main thread. This *pins the final value*; it
does not compose with the game's modifier math, but it is safe — no forged game
objects, no SwissTable surgery, no new native code.

**2. Native modifier event — `R.stat.modify`.** The request is an
`oCGameEventNetworkModifier` named event (vftable `0x140f322d0`), built by
`ModifierEvent_Ctor`. It rides the same named-event bus as `R.give`.

Event layout (0x98 bytes): `+0x00` vftable, `+0x08` state u32 (2 while building,
**0 = ready**), `+0x20` name `oCString {ptr, cap|0x80000000, len}`, `+0x30` name
hash (bus routing only), `+0x38` modifier id (`-1` = fresh; op 3 match-replaces on
it), `+0x50` serial u32, **`+0x54` stat key**, `+0x58` counter, **`+0x60` embedded
`oCEntityValueUnion` carrying the amount**, `+0x80` **duration f32** (`< 0` =
permanent, and also lands the modifier in the store's persistent list; the give
handler uses `5.0`), `+0x84`/`+0x88` multipliers (1.0), `+0x8c` flag u8 (1),
`+0x90` source entity (0 = no lifetime binding; non-zero registers an entity-death
watch at `entity+0x570`).

Consumption: key = `ev+0x54`; the **op and modifier type come from the value DEF**
looked up in the base hashmap `*(store+0x80)` — `def+0x70` = merge op,
`def+0x74` = typed-modifier factory switch (0..6), `def+0x68` = max modifier count
(0 = unlimited). `mod+0x3c` = remaining duration, `mod+0x40` = apply timestamp. In
co-op non-authority the function *relays* the event to the host over the
named-event bus instead of applying locally — free correctness for us.

`R.stat.modify(name, amount[, duration])` forges the event in scratch memory (the
union built through the engine's own ctor → destruct → `_InitAsType` sequence) and
calls `ApplyModifierEvent` directly — no bus, no name hash needed. It composes with
item/talent modifiers and survives recompute. Don't combine it with `stick` on the
same stat.

**Delivery: the modifier travels on the hero's event bus, as `ADD_MODIFIER`.** None of
the 13 vanilla places that build a modifier event call `ApplyModifierEvent`; all of them
dispatch the event on the entity's bus (`NamedEvent_Dispatch`), which routes by the
channel id at `ev+0x30` = `NamedEvent_Id_FromCrc(0, crc32("ADD_MODIFIER"))` = `816961080`,
the same id a vanilla upgrade carries on the same dispatcher `R.give` captures. That is
`R.stat.modify`'s default route, proven in game (2026-09-19): `+1` counts exactly once,
the in-run stat strip follows, and a permanent (`-1`) modifier survives a chapter change
like the game's own upgrades. It needs the hero's dispatcher (the hero must have acted
once) and returns `false` until then. The dispatch reaches `R.on("*")` handlers
**synchronously**, so a mod that calls `modify` from an event handler must latch before
calling; the SDK refuses a nested call (steamroller once recursed 99 deep without it).

`route = "direct"` calls `ApplyModifierEvent` itself (works from the value context alone).
Its defects are why it is not the default: a permanent `-1` is counted **twice** (the
`-1`-only branch at `0x14074ba3c` also records it in the run's persistent store), so on this
route "permanent" is sent as a `1e6` s duration instead, which counts once but is **dropped
at the next chapter**.

**The in-run stat strip reads a cache, not the store.** It shows
`100 × f32[obj+0x308]` for attack (`+0x304` vitality, `+0x30c` armor) with
`obj = *(*g_StatReportRoot + 0x20)`, and the engine refreshes that only when it folds a
modifier itself. So `R.stat.set` / `stick` change damage but leave the strip at its old
value (a pinned 40 showed `0`), while `R.stat.modify` moves both. `R.stat.cached(name)`
reads that cache for diagnostics.

## The registry catalog (mined 2026-09-20)

`tools/mine_stat_keys.py` reads the engine's own registration calls and writes
`data/stat_keys.json`: **221 keyed values**, name and key, which `rsmm symbols
gen` turns into `src/loader/lib/stats_gen.lua` and `R.stat.keys` merges in (the
hand-RE'd names win, and a key already spoken for gains no second name).

Five registration shapes feed one catalog. `Register_A(list, key, &name, desc)`
takes the key in `edx`; three `Register_B` helpers take it in `ecx`; and an
allocator form assigns the name into `def+0x08` and stores the key at
`def+0x6c`, sometimes as an immediate and sometimes through a register. Two
registrations are still unparsed on purpose: their keys are computed in a loop
(`base + 2*i`), which is the status family the SDK already derives by hand.

⚠ **Pair on structure, never on "the nearest string".** A block stages its name
several instructions before the call, and the description and editor-icon path
sit between two registrations, so the naive pairing is off by one *whole*
registration and looks plausible: it put `attack_power` on "Attack power basic"
and armour on a neighbour's key. The miner ties each name to the stack slot the
call actually passes, and checks the staged `0x80000000 | len` against the
string's real length.

What it settled:

* **Armour is registered with key `0`** — a definition, a display name and an
  editor icon, but no id. It is genuinely unaddressable through the store, so no
  `R.stat` call can read or write it; its live value is a plain field at
  `hero+0x31c` (written by `0x1403aab60`, beside the attack cache at `+0x318`).
  Five armour *effects* are keyed and usable: "Armour per missing health"
  (`0x16917db7`), "Armour increase crit damage" (`0x16917ec8`), "Armour into AP"
  (`0x174a0363`), "Armour per ability under cooldown" (`0x170329b8`) and
  "Transform over healing to armour" (`0x170435c4`).
* **Ten of twelve hand-RE'd keys confirmed** by the engine's own labels
  (`0x188671a6` is "Vitality", `0x15c9296d` is "Max health", `0x15b45d80` is
  "CD reduce"). The two that are absent, `xp_multiplier` and
  `difficulty_xp_mult`, are scene-context values and live in `R.game`'s table.
* **Two corrections.** `status_poison` pointed at `0x16ede068`, which the engine
  calls **"Weak"**; real Poison is `0x173fcdaa`, in the shield/bleed family. And
  `status_cursed` is the engine's **"Disease"** — the name stays for the mods
  that use it, with the label recorded.

## Symbols

Read/write primitives: `EntityValueOverride_Alloc`, `EntityValueEntry_Ctor`,
`EntityValueUnion_DefaultCtor` / `_InitAsType` / `_CopyAssign` / `_Compare` /
`_Destruct`, `Hero_GainExperience`, `XpComponent_SetLevel`, `XpComponent_SetXp`,
`Entity_GetComponentByTester`, `Entity_GetComponentFast`, `XpComponent_vftable`,
`XpComponent_TypeTester`.

Durable-modifier path: `EntityValueStore_Recompute`,
`EntityValueStore_ApplyModifierEvent`, `EntityValueStore_InitBaseValues`,
`ModifierEvent_Ctor`, `oCGameEventNetworkModifier_vftable`.

## See also

- [Anatomy of an entity](/reverse-engineering/entity-anatomy/) — what an entity is, and the three places a number can live.

---

# UI & the book menu

> The game's entity-component UI, the fixed five-tab book, the button-press choke point, and the abandoned attempt to build an in-game mod menu out of data plus one detour.

Source: https://docs.rsmm.me/reverse-engineering/ui-menus/

:::caution
**Abandoned, and the tooling is removed (2026-09-23).** The in-game mod menu was
dropped; mods are managed from the desktop app and the CLI. `rsmm menu`,
`rsmm intents`, `R.mods.request` and the menu builders (`mod_menu`, `mods_tab`,
`mods_modal`, `entity_inspect`) no longer exist. This page is kept as a record of
how the game's UI works and what was tried. What survived is generic:
`entity_strings`, `entity_append`, and the class-table helpers now in
`entity_components`.
:::

## What the game's UI actually is

**No middleware.** No Noesis/XAML/Scaleform/HTML strings. The entire UI is the
engine's own **entity-component system**: menus are `*.entity.ot` assets under
`GameUis/`, `Book_Menu/`, `Ui/` composed of widget components and driven by C++
controller components.

(Dear ImGui 1.91.7 *is* compiled in, but only for the hash-gated dev overlay — see
[Dev/debug mode](/reverse-engineering/notes/). Irrelevant here.)

Widget components, generic and reusable from data: `oCEntityCpntGameUi`
(root/canvas), `WindowUi`, `LabelUi`, `PictureUi`, `ButtonUi`, `GaugeUi`, `EditUi`,
`InputUi`, `ScrollPanelUi`, `NavigableZoneUi` / `NavigableListenerUi` (gamepad and
mouse focus), `oe::UiLayouterEntityCpnt`, `oCEntityCpnt3dText`.

## The main menu is the "Book"

- `oCDtEntityCpnt3DBookController(Settings)` — the 3D book.
- `oCDtEntityCpnt3DBookTabController(Settings)` — one per physical tab; its
  settings deserializer reads just **3 sub-object/picker refs**, so tab→page
  wiring is pure data.
- `oCDtEntityCpntBookMenuUiController(Settings)` — orchestrator; ~8 picker refs +
  2 struct readers, version-gated on class hash `0x1768bccf`. No inline page list —
  pages hang off tabs and pickers.
- Page interface `oIDtEntityCpntBookPageUiController`; concrete pages under
  `GameUis/All_Book_Pages/*.entity.ot` (Challenges, Compendium, HeroMeta,
  PlayBookPage, SelectHero, Social, Recap, Credits, BookOptions, TutoCompendium…).
- Reusable blocks: `oe::dt::ButtonListUiControllerEntityCpnt`,
  `MultiChoiceOptionUiControllerEntityCpnt`.

Cross-entity refs are **path strings**, not GUIDs — pages are wired as
`GameUis\All_Book_Pages\Play_Book_Page.entity.ot` plus `[Game Ui] <page>\Game Ui`
picker strings. `[Named Event Sender]` / `[Named Event Listener]` components exist
in page data, so buttons → named events → the loader's existing `R.on("gameplay:*")`
is an interactivity bridge needing no new C++ hook. A `**`-prefixed label renders
literally, so literal labels need no text-bank key. Only the
`EntitySettings/...gen` file exists per entity — the bare `.entity.ot` path is
virtual.

## The five tabs are a compiled-in constant

| Class | Hash | Size | Ctor | Vftable |
| --- | --- | --- | --- | --- |
| `oCDtEntityCpnt3DBookController` | `0x1781bd6c` | `0x230` | `FUN_140307b10` | `0x140f23368` (30 slots) |
| `oCDtEntityCpnt3DBookTabController` | `0x18ababa6` | — | `FUN_140309a60` | descriptor `DAT_141470f20` |
| `oCDtEntityCpntBookMenuUiController` | — | `0x328` | `FUN_1403e0580` | — |

The settings deserializer builds the tab picker array with
`_eh_vector_constructor_iterator_(count=5, size=0x40)` — **count 5 is a compiled-in
constant**. `BookController_ResolveSettings` runs a fixed loop of 5, type-checking
entries as `oCEntityCpntEntitySpawner` → runtime `+0xf8..+0x118`;
`BookController_ResolveTabs` loops the same 5 → runtime `+0x120..+0x148`.

:::caution
**A 6th tab cannot be added by data.** The count is baked into the deserializer,
the settings layout, the runtime layout and every loop. A real MODS tab needs a
loader detour on `BookController_ResolveTabs` to rewire one of the 5 slots.
:::

Clicks on tabs are **not** 3D picking and not `ButtonUi`: `Main_Book_Menu` has a
`Nav_Zone` with 5 navigable elements plus 5 `[Navigable Listener Ui]` components —
the hit areas live on the 2D UI layer, as pure data.

## Button press dispatch

The per-frame task `oCEntityCpntButtonUi - Button input update`
(`UiButton_InputPoll`) iterates live ButtonUi components; each pressed button that
passes its visibility/enable/focus gates goes through a raw input latch and then
**`UiButton_PressCommit`** with the widget desc from `cpnt+0x268` — the single
choke point for every ButtonUi click. PressCommit runs the widget press state
machine (`+0x32c` state, `+0x328` mode) then vcalls slot 2 on `*(widget+0x570)`,
the owning controller's `oINavigableListener`.

Widget offsets pinned from press captures: **`+0x280` = widget name**,
**`+0x1e8` = rendered label**.

`hook_ui.cpp` post-detours PressCommit (gated by `RSMM_ENABLE_UI_HOOK`, surfaced
in the desktop loader-flags panel) and emits `R.on("ui:press")`. Because the page
controller doesn't know cloned buttons, `*(widget+0x570)` may be null — the hook
skips the native commit for listenerless widgets and only emits the event.

:::danger[Sentinel wrap bug — fixed]
The first armed session crashed reading `0xffffffffffffffff`. The old `readable()`
helper looped `for (x = a; x < a + size;)`; for a `-1` sentinel (UI linked lists
use it as a terminator) `a + size` **wraps**, the loop runs zero times, and the
function falls through to `return true`. Fixed by rejecting non-canonical/wrapping
ranges — and this is why all page-state guarding now lives in the one
`mem_safe.h` implementation.
:::

## Building the mod menu

1. **Page and tab are data** — clone an existing book page entity and a tab mesh
   controller entity, register both via `UsedRscList`, repoint the picker refs.
2. **Labels and art** — text-bank append plus texture overrides.
3. **Actions** — the loader hook on button press → `R.on("ui:press")` → Lua.
4. **Mod ops** — Lua toggles Lua-mods live; asset enable/disable/uninstall writes
   an intent file the host CLI consumes (the game runs under Proton, the CLI lives
   on the host, so it can't shell out in process).

### Pieces that were built (removed 2026-09-23 unless noted)

- `engine/entity_strings.py` (kept) — lstr surgery (scan/replace length-prefixed strings
  in section payloads; byte-stable, reversible, typo-guarded). The generic
  clone-and-retarget primitive for all entity work.
- `engine/mod_menu.py` + `rsmm menu build|remove` — repurposes `Tuto_Page_1` as an
  "RSMM Mods" page: label keys swapped to `RSMM_Menu_*` and appended to the text
  bank in all languages with the generated mod list. Emitted as a normal override
  mod; reads pristine bytes from `.rsmm.bak`, so rebuild-after-apply is idempotent.
  The base page and bank are cloned from the **user's** install at build time — no
  game bytes in the repo.
- `engine/entity_inspect.py` + `rsmm menu inspect` — structural entity summary and
  diff.
- **Intent protocol** — `rsmm._internal.intent_write(op, mod_id)` (allowlisted
  enable/disable/uninstall, strict id shape) appends JSONL to
  `<cooking>/.rsmm_intents.jsonl`; Lua gets `R.mods.list()` / `R.mods.request()`;
  the host gets `rsmm intents list|apply|clear`, which re-validates (the file is
  user-writable, so untrusted), applies last-intent-per-mod, and re-runs
  `rsmm apply`. `rsmm watch` auto-consumes.
- **Component-append primitive** (`engine/entity_append.py`, kept) — entity cooked layout
  is section 0 = directory (`u32 count` + count × u32 class index), sections
  1..count = one self-framed component record each (first u32 = class index,
  16-byte instance GUID after the first inner END), last section = trailer.
  `cooked.emit(cooked.parse(x))` is byte-identical on the 188 KB book scene, so
  appending = bump count, append class index, insert record before the trailer —
  the entity-file analog of the versiondef vector append proven for items.

### What failed, and why

- **Social-page donor — scrapped.** The clone rendered its text over *every* page,
  cut and mis-scaled: its native `Dt Social Book Page` controller (which owns
  categories, sub-pages and button spawning) doesn't participate in the slot
  show/hide flow.
- **Appended 6th bookmark — inert.** All 5 page-tab nodes carry the *same*
  position and all 5 bookmark entities are byte-identical except GUID and
  material; the visible vertical spread is computed at runtime **by array index**.
  A 6th bookmark either never spawns or lands exactly under the Tuto one. The
  scene append itself loaded crash-free, so the append primitive is in-game safe —
  it's the index-driven controller that has to change.

### What works

Buttons appended **into** the Tuto frame page. `Tuto_Compendim_Page` decodes to 27
sections including two `oCUIGameButtonDesc` records (`Prev_Button` / `Next_Button`
arrow icons — which is why presses reported `name="OPTION_BUTTON"`). Both records
are self-framed and therefore cloneable:

- **WindowUi record**: name lstr, desc link **by name**, `[Game Ui] <page>\Game Ui`
  parent picker, `[NavigableZone Ui] … \Page Nave Zone` picker (nav registration),
  anchor floats, GUID at the standard record offset.
- **ButtonDesc record**: position as f32 fractions, textures, flip/rotation, hover
  colors. No GUID.

`build_tab_assets` clones the page's own Next pair three times as
`RSMM Btn Next/Prev/Toggle` with descs `RSMM_Next_Mod` / `RSMM_Prev_Mod` /
`RSMM_Toggle_Mod`, appending all six components to the page — same-file clone, so
parent and nav pickers resolve unchanged. No foreign controllers, no new assets, no
`Main_Book_Menu` override.

The end-to-end loop is proven in-game: the page renders, clicks select mods,
queueing writes an intent, `rsmm intents apply` flips the manifest, rebuilds the
page and re-applies.

## Open

- **A true 6th tab** — loader detour on `BookController_ResolveSettings`/`Tabs`
  (symbols and patterns are in place) to trigger and position an appended tab
  spawner, plus a 6th Nav element in `Main_Book_Menu`'s Nav_Zone for the click.
- **Structural entity edits** — whole-file clone plus GUID/text swap is proven;
  adding *new rows* to a versioned record is not. Fallback: a fixed row count with
  pagination in Lua.
- Whether the BookMenu controller tolerates a page swap on one of its 7
  path-string page refs — likely yes, since the refs are plain paths, and it would
  give the mod page a whole tab without touching the 5-slot array.