ttrpg-engine-dnd 0.1.0-alpha.0

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export type { AbilityScore, AbilityScores, Size, CreatureType, DamageType, Skill, ProficiencyLevel, HitDie, MovementMode, Speed, Sense, Senses, SpellSchool, SpellLevel, CharacterLevel, ExhaustionLevel, Alignment, Currency, CurrencyKey, Recharge, WeaponProperty, WeaponMastery, DiceExpression, } from '../schemas/primitives.js';
+export type { Formula } from '../schemas/formula.js';
+export type { Predicate } from '../schemas/predicate.js';
+export type { Effect, EffectKind, ModifierTarget, RollTarget, } from '../schemas/effects.js';
+export type { Condition, Species, Background, Feat, Class, ClassFeature, Subclass, SpellcastingProgression, LevelEntry, Spell, ItemDefinition, Weapon, Armor, Tool, MagicItem, Consumable, Gear, MonsterStatblock, } from '../schemas/content/index.js';
+export type { Character, HP, DeathSaves, ClassEnrollment, AppliedCondition, ResourceState, ItemInstance, PendingChoice, ChoiceOption, CampaignState, } from '../schemas/runtime/index.js';
+export type { Event, EventType, EventEnvelope, DamageAppliedEvent, DamageComponent, HealedEvent, TempHPGrantedEvent, ConditionAppliedEvent, ConditionRemovedEvent, ExhaustionChangedEvent, DeathSaveRolledEvent, StabilizedEvent, ResourceSpentEvent, ResourceRestoredEvent, HitDieSpentEvent, ShortRestStartedEvent, ShortRestEndedEvent, LongRestStartedEvent, LongRestEndedEvent, CharacterCreatedEvent, } from '../schemas/events/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,KAAK,EACL,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,KAAK,EACL,MAAM,EACN,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EACV,MAAM,EACN,UAAU,EACV,cAAc,EACd,UAAU,GACX,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,SAAS,EACT,OAAO,EACP,UAAU,EACV,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,uBAAuB,EACvB,UAAU,EACV,KAAK,EACL,cAAc,EACd,MAAM,EACN,KAAK,EACL,IAAI,EACJ,SAAS,EACT,UAAU,EACV,IAAI,EACJ,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,SAAS,EACT,EAAE,EACF,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,KAAK,EACL,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SCHEMA_VERSION: 1;
+export type SchemaVersion = typeof SCHEMA_VERSION;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,EAAG,CAAU,CAAC;AAEzC,MAAM,MAAM,aAAa,GAAG,OAAO,cAAc,CAAC"}

package/docs/api-overview.md

@@ -0,0 +1,111 @@
+# API overview
+
+The public surface is everything re-exported from [src/index.ts](../src/index.ts). Anything not exported is internal and may change without notice.
+
+## Engine
+
+```ts
+const engine = createEngine({ contentPacks, rng, handlers? });
+```
+
+Returns an `Engine` with five namespaces:
+
+- `engine.createCampaign({ name })` builds a fresh `Campaign` with an empty state.
+- `engine.apply(state, event)`, `engine.applyAll(state, events)`, `engine.replay(events)`: pure state transitions.
+- `engine.commit(campaign, events)`: append events to a campaign, returning the new campaign.
+- `engine.undo(campaign)`, `engine.redo(campaign)`: move the cursor along the log.
+- `engine.plan.*`: planners that consume RNG and return events to commit. See [planners](#planners).
+- `engine.derive.*`: pure derivations that read state and return typed results. See [derivations](#derivations).
+
+## Planners
+
+Every planner returns `{ events: Event[] }` with the resolution chain baked in (dice rolls included). `apply()` is RNG-free.
+
+**Resting & resources**: `shortRest`, `longRest`, `rest` (generic).
+
+**Combat**: `attack`, `opportunityAttack`, `actionSurge`, `offHandAttack`, `multiattack`, `falling`.
+
+**Encounter lifecycle**: `createEncounter`, `rollInitiative`, `startEncounter`, `beginFirstTurn`, `advanceTurn`, `endEncounter`.
+
+**Movement**: `move`, `dash`, `disengage`.
+
+**Spellcasting**: `castSpell`, `checkConcentration`, `counterspell`, `dispelMagic`, `identify`.
+
+**Checks & saves**: `save`, `abilityCheck`.
+
+**Progression**: `levelUp`, `resolveChoice`.
+
+**Contested actions (Slice 21)**: `grapple`, `shove`, `hide`.
+
+**Weapon mastery (Slice 23)**: `weaponMastery({mastery, attackerId, targetId, weaponInstanceId})`.
+
+**Travel & exploration (Slice 25)**: `forage`, `navigationCheck`.
+
+**NPC mechanics (Slice 26)**: `moraleCheck`, `reactionRoll`.
+
+## Derivations
+
+All read-only.
+
+- `character(state, id)` → `DerivedCharacter` (totalLevel, proficiency bonus, ability modifiers, HP, AC, saves, spell slots, pending choices).
+- `ac(state, id)`, `savingThrow(state, id, ability)`, `attackBonus(state, id, weaponInstanceId)`.
+- `spellSaveDC(state, id, classId)`, `spellAttackBonus(state, id, classId)`, `spellSlots(state, id)`.
+- `abilityModifier(score)`, `proficiencyBonus(level)`: pure helpers.
+
+Stand-alone derivations also exported: `computeAbilityCheck`, `computePassiveScore`, `computeAC`, `buildEffectStack`, plus terrain helpers `terrainAt`, `movementCostFor`, `movementCostAt`, `chebyshevDistanceFeet`, `isInRangeFeet`, `hasLineOfSight`, `hasLineOfEffect`.
+
+## Events
+
+Every state transition is an event. The discriminated union `Event` lives at `EventSchema` (Zod) and `Event` (TypeScript). The full list is at [src/schemas/events/index.ts](../src/schemas/events/index.ts) in the `EVENT_TYPES` constant.
+
+Categories:
+
+- **Combat**: `DamageApplied`, `Healed`, `TempHPGranted`, `ConditionApplied/Removed`, `DeathSaveRolled`, `Stabilized`, `ExhaustionChanged`, `AttackRolled`, `DamageRolled`, `SpellCastDeclared`, `SpellSlotConsumed`, `PactSlotConsumed`, `ConcentrationStarted/Broken`, `TriggerFired`, `ActionEconomyConsumed`, `CombatantMoved`, `Dashed`, `Disengaged`, `SaveRolled`, `AbilityCheckRolled`.
+- **Spellcasting (reactive)**: `SpellCountered`, `SpellDispelled`, `ItemIdentified`.
+- **Weapon mastery**: `WeaponMasteryActivated`.
+- **Encounter**: `EncounterCreated/Started/Ended`, `InitiativeRolled`, `TurnStarted/Ended`, `RoundEnded`.
+- **Resting**: `ShortRestStarted/Ended`, `LongRestStarted/Ended`, `HitDieSpent`, `ResourceSpent/Restored`.
+- **Progression**: `CharacterCreated`, `LevelUpResolved`, `ChoiceRequired/Resolved`, `XPAwarded`, `MilestoneAwarded`.
+- **Inventory**: `ItemAcquired/Equipped/Unequipped/Attuned/Unattuned`, `ItemChargeConsumed`, `ItemRecharged`, `SentientItemConflict`.
+- **Party & treasure**: `PartyCreated`, `PartyMembersChanged`, `CurrencyAcquired/Spent`, `ItemDepositedToParty/WithdrawnFromParty`.
+- **Sessions & journal**: `SessionStarted/Ended`, `JournalEntryAdded`, `InGameTimeAdvanced`.
+- **Locations & terrain**: `LocationCreated`, `DoorAdded`, `DoorStateChanged`, `CharacterLocationChanged`.
+- **Quests**: `QuestStarted`, `ObjectiveProgressed/Completed/Failed`, `QuestCompleted/Failed/Abandoned`, `QuestRewardClaimed`.
+- **Travel**: `TravelLegCompleted`, `NavigationCheckRolled`, `ForagedFor`.
+- **NPC mechanics**: `AttitudeChanged`, `MoraleCheckRolled`, `MoraleBroken`.
+- **Downtime**: `DowntimeActivityResolved`.
+- **Mounts & vehicles**: `Mounted`, `Dismounted`, `VehicleAcquired`, `VehicleBoarded`, `VehicleDeparted`, `VehicleDamaged`, `VehicleRepaired`.
+- **Resurrection & transformation**: `CharacterResurrected`, `PolymorphApplied/Reverted`, `SimulacrumCreated`, `WishGranted`.
+
+## Schemas
+
+Every shape is a Zod schema (parse at boundaries, types via `z.infer`):
+
+- Content: `ContentPackSchema`, `SpeciesSchema`, `BackgroundSchema`, `FeatSchema`, `ClassSchema`, `SubclassSchema`, `ClassFeatureSchema`, `SpellSchema`, `ConditionSchema`, `ItemDefinitionSchema` (and its variants `WeaponSchema`, `ArmorSchema`, `ToolSchema`, `MagicItemSchema`, `ConsumableSchema`, `GearSchema`), `MonsterStatblockSchema`.
+- Runtime: `CharacterSchema`, `ItemInstanceSchema`, `EncounterSchema`, `EffectInstanceSchema`, `PartySchema`, `SessionSchema`, `JournalEntrySchema`, `LocationSchema`, `DoorSchema`, `LocationMapSchema`, `QuestSchema`, `QuestObjectiveSchema`, `VehicleSchema`, `CampaignStateSchema`.
+
+## Content packs
+
+```ts
+const pack = loadContentPack(json);
+const resolved = resolveContent([pack1, pack2]);
+const issues = validateCrossReferences(resolved);
+```
+
+`loadStarterPack()` returns the bundled starter pack. `STARTER_PACK_RAW` exposes the underlying object if you need to inspect or extend it.
+
+## RNG
+
+```ts
+import { defaultRNG, seededRNG, throwOnCallRNG } from 'ttrpg-engine-dnd';
+```
+
+`seededRNG(seed)` for deterministic tests. `throwOnCallRNG()` is the architectural canary: pass it into a replay to prove `apply()` never reaches for randomness.
+
+## IDs
+
+Branded string types per kind. Factories: `newCharacterId`, `newCreatureId`, `newPartyId`, `newEncounterId`, `newCampaignId`, `newSessionId`, `newLocationId`, `newQuestId`, `newJournalEntryId`, `newEventId`, `newChoiceId`, `newEffectInstanceId`, `newAppliedConditionId`, `newItemInstanceId`. Brand casts: `asCharacterId`, `asSpeciesId`, etc.
+
+## Migrations
+
+`migrate(json) → CampaignState` walks the on-disk version forward.

package/docs/concepts.md

@@ -0,0 +1,154 @@
+# Concepts
+
+The mental model behind the engine. About fifteen minutes to read. After this, the planners and reducers will make a lot more sense.
+
+## Events are the truth, state is the projection
+
+Most game engines mutate state in place: an actor's HP field gets decremented, an effect gets appended to a list. The state IS the truth; the history of how it got there is a chat log at best.
+
+This engine inverts that. The truth is an append-only **event log**. The current state is **computed** by folding `apply(state, event) -> state` over the log.
+
+```ts
+campaign.events   // ← the truth: every state change ever recorded
+campaign.state    // ← derived: state == replay(events)
+```
+
+`apply()` is **pure**: same state + same event always produces the same next state. `replay(events)` walks the entire log and reconstructs the state from empty. On every commit the engine asserts `replay(state.events).state` deep-equals `campaign.state` (this invariant is tested in CI on every golden scenario).
+
+What this gives you:
+
+- **Save files are just JSON arrays of events.** `serializeCampaign(c)` writes id + name + schemaVersion + events. State is not stored; it's reconstructed by `loadCampaign(json)`.
+- **Undo / redo are free.** The campaign carries a cursor into the event log. `undo()` decrements it; the state is recomputed from the prefix.
+- **Multiplayer sync is straightforward.** Stream events between clients. As long as the planners on both sides consume the same RNG, they arrive at byte-equivalent state.
+- **Debugging.** "Why is my HP 12?" Filter the event log: every change has a cause. The chat log isn't the only record; the events are.
+- **Branching.** Fork the event list, append hypothetical events, observe the resulting state. Discard the fork. This is how an AI DM could evaluate "what if I cast Fireball here?"
+
+The cost: every state change has to go through an event. Direct mutation of `campaign.state` is forbidden (and TypeScript enforces it: the state shape is frozen by Immer).
+
+## Plan / commit split: RNG capture
+
+The hardest part of event-sourced game engines is randomness. If `apply()` rolls dice during the attack reducer, the same events replay to different states on different machines.
+
+This engine splits the work:
+
+- **`engine.plan.*(intent)`**: consumes RNG. Rolls dice. Returns events with the dice results **baked in**.
+- **`apply()`**: pure. Reads the baked rolls. Never touches RNG.
+
+```ts
+// plan.attack consumes RNG, returns events with d20, damage dice, etc. captured.
+const { events } = engine.plan.attack(state, { attackerId, targetId, weaponInstanceId });
+
+// commit appends events and applies them. apply() never re-rolls.
+campaign = commit(campaign, events);
+```
+
+The architectural invariant: passing `ThrowOnCallRNG()` to `replay()` must not throw on any golden scenario. This is asserted in CI. If a reducer ever reaches for the RNG, the test suite fails.
+
+What this gives you:
+
+- **Deterministic replay across machines.** Two clients playing the same campaign arrive at the same state by streaming events alone.
+- **The events ARE the dice record.** Looking at `AttackRolled` you see `d20: [14, 17], used: 17` and you know the natural-17 came from rolling with advantage.
+- **Easy to test.** A seeded RNG (`seededRNG(42)`) makes a scenario reproducible from end to end.
+
+The cost: dice rolls happen at plan time, not at apply time. You can't roll dice in a reducer.
+
+## Schema-only library: bring your own content
+
+A rules engine that ships content has IP problems and is hard to extend. This engine ships **only schemas + machinery** and a small **starter content pack** (under MIT, drawn from the 2024 SRD shape). Consumers load their own content packs at runtime.
+
+A content pack is a JSON file with this shape:
+
+```ts
+{
+  id: 'my-pack',
+  name: 'My Pack',
+  version: '0.1.0',
+  species: [...],
+  backgrounds: [...],
+  classes: [...],
+  subclasses: [...],
+  feats: [...],
+  spells: [...],
+  items: [...],
+  monsters: [...],
+  conditions: [...],
+}
+```
+
+Each list is validated against its Zod schema (`SpeciesSchema`, `SpellSchema`, etc.). Cross-references are checked (a `background.originFeatId` must point at a real feat).
+
+```ts
+import { loadContentPack, resolveContent, validateCrossReferences } from 'ttrpg-engine-dnd';
+
+const pack = loadContentPack(myJson);             // Zod parse, throws on shape error
+const content = resolveContent([pack, otherPack]); // merge multiple packs
+const issues = validateCrossReferences(content);   // returns Levenshtein-suggested issues
+```
+
+Multiple packs merge with later packs winning on ID conflicts. This is how you layer "core + homebrew" or "core + setting + table-specific."
+
+## Effect primitives plus an escape hatch
+
+5.5e content has a wildly heterogeneous mechanical surface. The Barbarian's Rage is one shape; the Wizard's Mage Armor is another; Wish is its own beast.
+
+The engine expresses **most** features via a fixed vocabulary of about 25 **effect primitives**:
+
+- `AddModifier { target, value, condition? }`: a +1 to AC, a +2 to attack bonus
+- `GrantResource { resourceId, max, recharge }`: Bardic Inspiration, Action Surge, Channel Divinity
+- `OverrideACFormula { base, abilityModifiers, ... }`: Unarmored Defense
+- `OnEvent { trigger, actions, oncePer? }`: Sneak Attack (rider damage on a hit)
+- `GrantResistance / GrantImmunity / GrantVulnerability`: Half-Orc Relentless Endurance, dragon fire immunity
+- `ModifyActionEconomy { op: 'extraAttack' | ... }`: Extra Attack
+- `ModifySpeed { mode, op, value }`: Barbarian Fast Movement
+- `GrantWeaponMastery { masteries, slots }`: Ranger's mastery grant
+- ...and about a dozen more.
+
+Effects live on **classes**, **feats**, **species**, **conditions**, and **items**. The engine's `buildEffectStack(character)` walks every source and assembles a single ordered list. Derivations then read the stack.
+
+For features that genuinely don't fit a primitive (Wild Shape, Polymorph, Simulacrum, Wish), there's an **escape hatch**: dedicated event types (`PolymorphApplied`, `SimulacrumCreated`, `WishGranted`) with their own reducers. Same architectural contract: pure apply, baked rolls, replay-safe.
+
+This split lets data express ~95% of features without code, and code handle the ~5% that data can't.
+
+## PendingChoice: deferred decisions are events too
+
+A character levels up: do they want a feat or ASI? They learn a new spell: which spells does the pack offer at that level?
+
+In an imperative engine these are interactive prompts mid-mutation. Here they're **first-class events**:
+
+```ts
+ChoiceRequired { choiceId, characterId, kind, options }   // engine emits this
+ChoiceResolved { choiceId, selectedOptionIds }            // consumer emits this
+```
+
+The level-up planner emits a `LevelUpResolved` event plus any `ChoiceRequired` for decisions the player owes. The choice sits on `campaign.state.pendingChoices` indefinitely. When the player picks, the consumer emits `ChoiceResolved` and the engine applies the chosen option's effects.
+
+This is how the engine supports "build a UI" without owning the UI: ask the engine what decisions are open, render them, send back the selections.
+
+## Branded IDs
+
+Every entity kind has its own branded string type: `CharacterId`, `EncounterId`, `ItemInstanceId`, `ItemDefinitionId`, etc. They're all `string` at runtime (ULIDs), but the type system stops you from passing a spell ID where a character ID was expected.
+
+```ts
+const c: CharacterId = newCharacterId();
+const i: ItemInstanceId = newItemInstanceId();
+engine.derive.attackBonus(state, c, i);  // typechecks
+engine.derive.attackBonus(state, i, c);  // ❌ type error
+```
+
+When you load IDs from JSON, use the cast helpers: `asCharacterId(s)`, `asSpeciesId(s)`, etc. At parse time the Zod schemas validate that the strings are ULIDs.
+
+## Derivations are pure, memoized per state version
+
+`engine.derive.character(state, id)`, `engine.derive.ac(state, id)`, etc. are **pure functions** of `(state, args)`. No caching, no side effects, no mutation.
+
+Internally the engine memoizes them per `CampaignState.version`. Every commit bumps the version; the next derive call clears the cache. So if you ask for derived AC ten times per frame across twelve combatants, you pay for one computation each, not 120.
+
+This is invisible to callers: the API is just "give me the derived sheet"; performance is handled.
+
+## Where to next
+
+- **Try it**: [examples/00-quickstart](../examples/00-quickstart/) is the smallest working consumer.
+- **Walk through the tutorial**: [docs/getting-started.md](getting-started.md).
+- **Look up an API**: [docs/api-overview.md](api-overview.md).
+- **Common how-to recipes**: [docs/recipes.md](recipes.md).
+- **See it all at once**: the showcase transcript at [tests/golden/transcripts/showcase.transcript.md](../tests/golden/transcripts/showcase.transcript.md).

package/docs/getting-started.md

@@ -0,0 +1,142 @@
+# Getting started
+
+This walkthrough builds your first character, attacks a goblin, saves the campaign, and reloads it. About fifteen minutes from a blank project.
+
+## 1. Install
+
+```sh
+npm install ttrpg-engine-dnd@alpha
+```
+
+Peer dependencies (`zod`, `immer`, `ulid`) install transitively.
+
+## 2. Create an engine with the starter pack
+
+```ts
+import { createEngine, loadStarterPack, seededRNG } from 'ttrpg-engine-dnd';
+
+const engine = createEngine({
+  contentPacks: [loadStarterPack()],
+  rng: seededRNG(42),
+});
+```
+
+The starter pack ships in the package and includes Fighter, Wizard, Rogue, Paladin, and Warlock classes through level 5, Human species, Soldier background, all 15 conditions, common weapons and armor, and a handful of spells. Bring your own content pack when you outgrow it.
+
+## 3. Build a character
+
+```ts
+import { CharacterSchema, newCharacterId, newItemInstanceId, newEventId } from 'ttrpg-engine-dnd';
+import { commit } from 'ttrpg-engine-dnd';
+
+const alyx = CharacterSchema.parse({
+  id: newCharacterId(),
+  name: 'Alyx',
+  speciesId: 'human',
+  backgroundId: 'soldier',
+  classes: [{ classId: 'fighter', level: 3, hitDiceRemaining: 3 }],
+  abilityScores: { STR: 16, DEX: 14, CON: 14, INT: 10, WIS: 12, CHA: 8 },
+  hp: { current: 26, max: 26, temp: 0 },
+  featsTaken: ['savage-attacker'],
+});
+
+const sword = {
+  id: newItemInstanceId(),
+  definitionId: 'longsword',
+  quantity: 1,
+  attuned: false,
+  identifiedByCharacterIds: [],
+};
+
+let campaign = engine.createCampaign({ name: 'demo' });
+campaign = commit(campaign, [
+  { id: newEventId(), at: new Date().toISOString(), type: 'ItemAcquired', instance: sword },
+  { id: newEventId(), at: new Date().toISOString(), type: 'CharacterCreated', snapshot: alyx },
+]);
+```
+
+The engine state is now populated. `commit` is pure: it returns a new `Campaign` with the events appended and the state advanced.
+
+## 4. Derive their sheet
+
+```ts
+const sheet = engine.derive.character(campaign.state, alyx.id);
+const ac = engine.derive.ac(campaign.state, alyx.id);
+const attack = engine.derive.attackBonus(campaign.state, alyx.id, sword.id);
+
+console.log(`AC ${ac.total}, Longsword +${attack.total} to hit`);
+```
+
+Every derivation returns a typed result with a breakdown (each contributing modifier and its source), not just a total.
+
+## 5. Take an attack
+
+Add a goblin, create an encounter, and attack:
+
+```ts
+const goblin = CharacterSchema.parse({
+  id: newCharacterId(),
+  name: 'Goblin',
+  speciesId: 'human',
+  backgroundId: 'soldier',
+  classes: [{ classId: 'fighter', level: 1, hitDiceRemaining: 1 }],
+  abilityScores: { STR: 8, DEX: 14, CON: 10, INT: 10, WIS: 8, CHA: 8 },
+  hp: { current: 7, max: 7, temp: 0 },
+  featsTaken: ['savage-attacker'],
+});
+
+campaign = commit(campaign, [
+  { id: newEventId(), at: new Date().toISOString(), type: 'CharacterCreated', snapshot: goblin },
+]);
+
+const enc = engine.plan.createEncounter(campaign.state, {
+  combatantIds: [alyx.id, goblin.id],
+  name: 'Goblin at the bridge',
+});
+campaign = commit(campaign, enc.events);
+campaign = commit(campaign, engine.plan.rollInitiative(campaign.state, { encounterId: enc.encounterId }).events);
+campaign = commit(campaign, engine.plan.beginFirstTurn(campaign.state, { encounterId: enc.encounterId }).events);
+
+campaign = commit(
+  campaign,
+  engine.plan.attack(campaign.state, {
+    attackerId: alyx.id,
+    targetId: goblin.id,
+    weaponInstanceId: sword.id,
+  }).events,
+);
+
+console.log(`Goblin HP: ${campaign.state.characters[goblin.id]?.hp.current}/7`);
+```
+
+All randomness was consumed inside `engine.plan.attack`. The events it returned have the d20 and damage dice baked in. `apply()` never touches RNG, so the campaign event log replays to byte-equivalent state on any machine.
+
+## 6. Save and load
+
+```ts
+import { replay, EventSchema } from 'ttrpg-engine-dnd';
+
+// Save: events are the durable artifact. State is computed.
+const saved = JSON.stringify({
+  id: campaign.id,
+  name: campaign.name,
+  schemaVersion: campaign.schemaVersion,
+  events: campaign.events,
+});
+
+// Load: parse events, replay, you have the same state.
+const parsed = JSON.parse(saved) as { events: unknown[] };
+const events = parsed.events.map((e) => EventSchema.parse(e));
+const restoredState = replay(events);
+// restoredState deep-equals campaign.state.
+```
+
+This is the practical payoff of event sourcing. Your save file is the truth; the state is derived.
+
+## What's next
+
+- **Understand the mental model**: [docs/concepts.md](concepts.md) explains why the API has the shape it does (events, plan/commit, content packs, effect primitives, PendingChoice).
+- **Common how-tos**: [docs/recipes.md](recipes.md) covers save/undo/redo, branching timelines, adding content and feats, houserules, multiplayer sync, custom planners, and migrations.
+- **Browse the public surface**: [docs/api-overview.md](api-overview.md) lists every public symbol by namespace.
+- **Larger scenarios**: [examples/](../examples/) has three runnable scripts. The showcase transcript at [tests/golden/transcripts/showcase.transcript.md](../tests/golden/transcripts/showcase.transcript.md) walks through a multi-act campaign exercising most of the engine.
+- **Bring your own content**: see [src/schemas/content/](../src/schemas/content/) for the Zod schemas of `Species`, `Background`, `Class`, `Spell`, `Feat`, `ItemDefinition`, `MonsterStatblock`, `Condition`. Load with `loadContentPack(json)` and merge with the starter via `resolveContent([starter, mine])`.