# TrapDef

> Kinbarrow modding reference — content tree `b2f73c2ab65ff925`, version `0.2.0+main.a22009f4c`.

`traps/<id>.srd.ron` — one trap per file; stem == id (the OPEN one-file-per-entity collection, the feats/spells/magic-items precedent). A trap is the SRD "Traps" substrate: a hidden hazard a keen eye DETECTS (a Perception/Investigation check vs `detect_dc`), a deft hand DISARMS (a thieves'-tools check vs `disarm_dc`, the lock-pick precedent), and that otherwise SPRINGS its [`effect`](Self::effect) on whoever triggers it. The composing consumer is the trapped container: a chest a burglar picks without disarming springs the needle on them. The DCs and dice are the SRD's; the primitives (which skill detects, the save/attack shape) are authored. A trap that springs nothing is refused by the validator.

**Note on syntax:** these files are RON, not JSON. The shapes below are exact,
but punctuation follows RON — read a real `data/*.ron` file alongside.

## Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detect_dc` | `uint32` | required | The DC that detection check beats — a u32, so it is ≥ 0 by type. |
| `detect_skill` | `Skill` | required | The skill a searcher rolls to notice the trap — Perception (the passive eye) or Investigation (deducing it from tampering), per the SRD block. |
| `disarm_dc` | `uint32` | required | The DC a thieves'-tools check beats to disarm it (the lock-pick shape). |
| `disarm_trigger_total_lte` | `integer` | optional | Inclusive final check total that springs the trap during a failed disarm. `None` means an ordinary failure leaves it armed but unsprung. |
| `effect` | `TrapEffect` | required | How the sprung trap resolves its payload (a save or an attack roll). |
| `encounter_cr` | `string` | optional | Optional engine calibration on the creature CR ladder. This is absent when a source prints only its own level/threat band and no exact mapping has been authored yet. |
| `id` | `string` | required | Authored id. |
| `name` | `string` | required | Authored name. |
| `source` | `Source` | required | Authored source. |

## Nested shapes

<a id="ability"></a>

### Ability

An open, validated Ability id interned from authored data.

<a id="damage"></a>

### Damage

Feat ids — the SRD's ONE feat, referenced where its grapple-dependent riders read (the Grappler advantage/pin). A damage roll: dice plus the kind they deal. The shared shape every attack, spell effect and trap payload reaches for, which is why it carries no id of its own — it is always a FIELD of the thing that inflicts it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dice` | `string` | required | The damage dice, an `NdM` string (e.g. "1d8"). |
| `kind` | `string` | required | A `tables/damage_kinds.srd.ron` id, boot-resolved. |

<a id="on-save"></a>

### OnSave

What a failed save spares (SRD: "half as much damage on a successful one").

<a id="on-save--half"></a>

#### OnSave::Half

Select the half behavior.

<a id="on-save--nothing"></a>

#### OnSave::Nothing

Select the nothing behavior.

<a id="skill"></a>

### Skill

An open, validated Skill id interned from authored data.

<a id="source"></a>

### Source

Every file's top-level value carries `source`.

<a id="source--srd51"></a>

#### Source::Srd51

SRD 5.1 — retained nonconflicting catalogue material.

<a id="source--srd52"></a>

#### Source::Srd52

SRD 5.2.1 — the 2024-revision System Reference Document, the same CC-BY-4.0 grant as 5.1 and the current rules chassis. Its files carry the `.srd52.ron` suffix so provenance reads off the path; see `data/README.md` for which document rules a given value.

<a id="source--original"></a>

#### Source::Original

Original content authored for this game (not from the SRD).

<a id="source--phb2024"></a>

#### Source::Phb2024

Material transcribed from the 2024 Player's Handbook. This source is not redistributable by this project and belongs in a `phb2024` mod.

<a id="source--dmg2024"></a>

#### Source::Dmg2024

Material transcribed from the 2024 Dungeon Master's Guide. This source is not redistributable by this project and belongs in a `dmg2024` mod.

<a id="source--mm2024"></a>

#### Source::Mm2024

Material transcribed from the 2024 Monster Manual. This source is not redistributable by this project and belongs in an `mm2024` mod.

<a id="source--tce"></a>

#### Source::Tce

Material transcribed from Tasha's Cauldron of Everything. This source is not redistributable by this project and belongs in a `tce` mod.

<a id="source--xge"></a>

#### Source::Xge

Material transcribed from Xanathar's Guide to Everything. This source is not redistributable by this project and belongs in an `xge` mod.

<a id="trap-affliction"></a>

### TrapAffliction

One independently expiring condition in a trap payload. A payload is a vector so coupled conditions remain separate world-ledger handles and can expire or be removed independently without content-specific logic.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `condition` | `string` | required | Authored condition. |
| `duration_secs` | `integer` | optional | Absolute duration in world seconds. `None` deliberately persists until an authored mechanic removes the same world-effect instance. |
| `removal` | `TrapAfflictionRemoval` | optional | Optional whole-Action ability check that can release the victim. A helper may attempt it only when explicitly authored. |

<a id="trap-affliction-removal"></a>

### TrapAfflictionRemoval

Authorable `TrapAfflictionRemoval` data exposed through the modding schema.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ability` | `Ability` | required | Authored ability. |
| `allows_adjacent_helper` | `boolean` | default `false` | Authored allows adjacent helper. |
| `dc` | `uint32` | required | Authored dc. |

<a id="trap-effect"></a>

### TrapEffect

How a sprung trap resolves its payload — the SRD "Traps" section's two shapes: a SAVING THROW everyone caught rolls (a success spares per [`OnSave`]), or an ATTACK ROLL the trap makes against the victim's AC. Either carries a damage roll (reusing the damage seam) and/or an inflicted condition (a `conditions/` id) — the poison needle's poison AND poisoned. A save with neither damage nor condition, or an attack with no damage, springs nothing and is refused by the validator (the ledger-don't-fake rule, the feat/magic-item precedent).

<a id="trap-effect--save"></a>

#### TrapEffect::Save

The caught roll a saving throw of `ability` vs `dc`; a success spares per `on_save` (half the damage, or nothing). Damage and/or a condition land on a FAILURE (a success inflicts no condition, SRD).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ability` | `Ability` | required |  |
| `afflictions` | `TrapAffliction[]` | optional |  |
| `damage` | `Damage` | optional |  |
| `dc` | `uint32` | required |  |
| `on_save` | `OnSave` | required |  |

<a id="trap-effect--attack"></a>

#### TrapEffect::Attack

The trap makes a ranged attack (d20 + `bonus`) vs the victim's AC; a hit deals the damage and inflicts the condition, a miss does nothing. No SRD SAMPLE trap rolls an attack (the device samples all save — needle, darts, statue); this is the substrate for a mod's / the DMG's attack-roll traps.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `afflictions` | `TrapAffliction[]` | optional |  |
| `attacks` | `uint8` | required | Number of independent attack rolls the trap makes when it springs. |
| `bonus` | `int32` | required |  |
| `damage` | `Damage` | required |  |