{"tab":"world","section":"narrativeEvents","title":"Narrative Events (Advanced)","summary":"`narrativeEvents` are one-off cues for story moments that play out over one or more turns. Unlike a plain trigger, a narrative event stays active while the engine watches for its intended outcome; when that outcome clearly happens, it completes and can fire normal trigger effects. Use them for briefings, ambushes, staged reveals, boss entrances, short challenges, or any guided scene that needs continuity across turns.","kind":"schema","uiLocation":"World → Advanced → Narrative Events","uiSubtitle":"\"Multi-turn narrative beats that can be started by triggers\"","editor":"JSON + ADD ITEM","related":[{"section":"triggers","note":"`narrative-event-start` begins an event; `narrative-event-status` reads its status"},{"section":"quests","note":"a quest can complete when an event completes via `completionCondition`"}],"wikiUrl":"/world/narrativeEvents","schema":{"_type":"record","domain":"string","codomain":{"_type":"intersection","parts":[{"_type":"required","fields":{"title":"string","beats":"string"}},{"_type":"partial","fields":{"targetTurns":"number","onCompleteEffects":{"_type":"array","of":"(recursive)"}}}]}},"sizeLimits":[],"blocks":[{"type":"example","lang":"json","caption":"Example: a narrative event","code":"{\n  \"wounded_courier\": {\n    \"title\": \"The Wounded Courier\",\n    \"beats\": \"A wounded courier should stagger into the scene and collapse. His wounds are serious enough that he can't get up again on his own, and he is unable to speak more than a gasped syllable at a time. With bloody hand, he should produce a letter and try to hand it to the player. With his dying breaths, he should plead for the letter to be taken to the king before it is too late.\",\n    \"targetTurns\": 3,\n    \"onCompleteEffects\": [\n      {\n        \"type\": \"quest-init\",\n        \"operator\": \"set\",\n        \"value\": \"Deliver the Sealed Letter\"\n      }\n    ]\n  }\n}"},{"type":"prose","md":"The event above does nothing until a trigger starts it. A trigger fires a `narrative-event-start` effect naming the event by its map key:"},{"type":"example","lang":"json","caption":"Starting it with a trigger","code":"{\n  \"deliver_letter_intro\": {\n    \"name\": \"deliver_letter_intro\",\n    \"recurring\": false,\n    \"conditions\": [\n      {\n        \"type\": \"party-location\",\n        \"operator\": \"equals\",\n        \"value\": \"The Forest Road\"\n      }\n    ],\n    \"effects\": [\n      {\n        \"type\": \"narrative-event-start\",\n        \"eventId\": \"wounded_courier\"\n      }\n    ]\n  }\n}"},{"type":"fields","fields":[{"name":"title","tooltip":"Short name for the event; used by the engine to track it, not shown to the storyteller.","required":true,"md":"**Required.** A short name for the event. The engine uses it to track and check the active narrative event; it is **not** exposed to the storyteller or intent functions, so it is a label, not part of the guidance. Triggers reference the event by its outer map key (through `eventId`)."},{"name":"beats","tooltip":"The instruction text that guides the scene and that the engine uses to judge completion.","required":true,"md":"**Required.** The main instruction text. While the event is active the engine gives this to the storyteller and to intent functions, and it uses **this same field** to decide whether the event's intended outcome has happened. Write it as something the AI can plausibly **stage** in the story: who appears, what happens, and what state signals it is done."},{"name":"targetTurns","tooltip":"Optional pacing target in turns; not a hard timer.","md":"Optional number -- a pacing target in turns that tells the storyteller roughly how quickly to move through the event. It is **not a hard timer**; nothing is forced to happen when it expires. Omit it to leave the pace open."},{"name":"onCompleteEffects","tooltip":"Optional trigger effects the engine fires once the event completes.","md":"Optional list of **normal [trigger effects](/mechanics/triggers#reference)** -- `quest-init`, `story`, `write-boolean`, `player-resource`, `narrative-event-start`, and so on. The engine fires them after it decides the event is complete, letting the event hand off into the rest of your world."}]},{"type":"prose","md":"## How narrative events work\n\nA narrative event is a named entry in the `narrativeEvents` map. Defining one does not start it:\n\n- **Start** -- a trigger fires a [`narrative-event-start`](/mechanics/triggers#reference) effect naming the event's key.\n- **Run** -- while active, the `beats` steer the storyteller and NPC intents, and the engine watches the story against those same beats.\n- **Complete** -- when the engine judges the outcome has happened, the event completes and its `onCompleteEffects` fire.\n\nThree rules shape how you design them:\n\n- **Only one narrative event is active at a time.** Design chains and pacing around this; write beats that can play out fully before the next thing must happen.\n- **They are always non-recurring.** A given event runs once per start.\n- **They are rooted in the location where they start, and suspend if the party leaves it.** A suspended event stops steering the scene and its `onCompleteEffects` do not fire. Runtime fields the engine manages (`status`, `turnsActive`, `completedTick`) are not authored by you.\n\nTriggers can gate on an event's progress with the [`narrative-event-status`](/mechanics/triggers#reference) condition, and a quest can complete when an event completes via `completionCondition: { \"type\": \"narrative-event-completed\", \"eventId\": \"...\" }` (see [Quests](/world/quests))."},{"type":"prose","md":"## What happens in play\n\nSay a scene starts `wounded_courier` while the party is on the forest road.\n\n**The player engages.** The courier staggers out, warns of riders, and presses the sealed letter into the player's hands over a couple of turns. The player clearly understands the job -- the engine marks the event complete and fires `onCompleteEffects`, so the quest *Deliver the Sealed Letter* is offered.\n\n**The player refuses or walks away.** If the player leaves the location where the event began, the engine stops steering the scene with it. The event is suspended, no quest starts, and any downstream logic tied to its completion does not run -- the story simply continues from the player's choice."},{"type":"prose","md":"## Chaining events\n\nBecause `onCompleteEffects` are ordinary trigger effects, an event can start the next one when it finishes:\n\n```json\n{\n  \"onCompleteEffects\": [\n    {\n      \"type\": \"narrative-event-start\",\n      \"eventId\": \"next_scene\"\n    }\n  ]\n}\n```\n\nThat lets you chain across mechanics -- trigger to event, event to event, event to quest, quest-progress to event, and so on -- for briefings, staged encounters, multi-step introductions, boss scenes, and quest handoffs. Since only one event runs at a time, sequence them through completion rather than starting several at once.\n\nThe event to quest handoff is especially useful with the current UI, which surfaces the immediate objective above the input bar -- use it to give the player meta-guidance for navigating a chain."},{"type":"prose","md":"## Authoring tips\n\n- **Keep beats concrete and stageable.** Name who appears and what happens; write what the AI can act out in the current scene, not abstract state. The clearer the intended outcome, the more reliably the engine can tell the event is done.\n- **Don't use them for background guidance.** Narrative events are location-rooted, non-recurring, and suspend when the party leaves, so they are wrong for permanent world guidance or general story-state changes -- use a recurring [trigger](/mechanics/triggers) for that.\n- **Guard against accidental suspension.** Chains are brittle: leaving the starting location suspends the event even if the player didn't mean to go anywhere. When it matters, give the storyteller guidance to keep the scene in the current location until the beat resolves."}],"body":"## Example: a narrative event\n\n```json\n{\n  \"wounded_courier\": {\n    \"title\": \"The Wounded Courier\",\n    \"beats\": \"A wounded courier should stagger into the scene and collapse. His wounds are serious enough that he can't get up again on his own, and he is unable to speak more than a gasped syllable at a time. With bloody hand, he should produce a letter and try to hand it to the player. With his dying breaths, he should plead for the letter to be taken to the king before it is too late.\",\n    \"targetTurns\": 3,\n    \"onCompleteEffects\": [\n      {\n        \"type\": \"quest-init\",\n        \"operator\": \"set\",\n        \"value\": \"Deliver the Sealed Letter\"\n      }\n    ]\n  }\n}\n```\n\nThe event above does nothing until a trigger starts it. A trigger fires a `narrative-event-start` effect naming the event by its map key:\n\n## Starting it with a trigger\n\n```json\n{\n  \"deliver_letter_intro\": {\n    \"name\": \"deliver_letter_intro\",\n    \"recurring\": false,\n    \"conditions\": [\n      {\n        \"type\": \"party-location\",\n        \"operator\": \"equals\",\n        \"value\": \"The Forest Road\"\n      }\n    ],\n    \"effects\": [\n      {\n        \"type\": \"narrative-event-start\",\n        \"eventId\": \"wounded_courier\"\n      }\n    ]\n  }\n}\n```\n\n## Fields\n\n### title\n\n**Required.** A short name for the event. The engine uses it to track and check the active narrative event; it is **not** exposed to the storyteller or intent functions, so it is a label, not part of the guidance. Triggers reference the event by its outer map key (through `eventId`).\n\n### beats\n\n**Required.** The main instruction text. While the event is active the engine gives this to the storyteller and to intent functions, and it uses **this same field** to decide whether the event's intended outcome has happened. Write it as something the AI can plausibly **stage** in the story: who appears, what happens, and what state signals it is done.\n\n### targetTurns\n\nOptional number -- a pacing target in turns that tells the storyteller roughly how quickly to move through the event. It is **not a hard timer**; nothing is forced to happen when it expires. Omit it to leave the pace open.\n\n### onCompleteEffects\n\nOptional list of **normal [trigger effects](/mechanics/triggers#reference)** -- `quest-init`, `story`, `write-boolean`, `player-resource`, `narrative-event-start`, and so on. The engine fires them after it decides the event is complete, letting the event hand off into the rest of your world.\n\n## How narrative events work\n\nA narrative event is a named entry in the `narrativeEvents` map. Defining one does not start it:\n\n- **Start** -- a trigger fires a [`narrative-event-start`](/mechanics/triggers#reference) effect naming the event's key.\n- **Run** -- while active, the `beats` steer the storyteller and NPC intents, and the engine watches the story against those same beats.\n- **Complete** -- when the engine judges the outcome has happened, the event completes and its `onCompleteEffects` fire.\n\nThree rules shape how you design them:\n\n- **Only one narrative event is active at a time.** Design chains and pacing around this; write beats that can play out fully before the next thing must happen.\n- **They are always non-recurring.** A given event runs once per start.\n- **They are rooted in the location where they start, and suspend if the party leaves it.** A suspended event stops steering the scene and its `onCompleteEffects` do not fire. Runtime fields the engine manages (`status`, `turnsActive`, `completedTick`) are not authored by you.\n\nTriggers can gate on an event's progress with the [`narrative-event-status`](/mechanics/triggers#reference) condition, and a quest can complete when an event completes via `completionCondition: { \"type\": \"narrative-event-completed\", \"eventId\": \"...\" }` (see [Quests](/world/quests)).\n\n## What happens in play\n\nSay a scene starts `wounded_courier` while the party is on the forest road.\n\n**The player engages.** The courier staggers out, warns of riders, and presses the sealed letter into the player's hands over a couple of turns. The player clearly understands the job -- the engine marks the event complete and fires `onCompleteEffects`, so the quest *Deliver the Sealed Letter* is offered.\n\n**The player refuses or walks away.** If the player leaves the location where the event began, the engine stops steering the scene with it. The event is suspended, no quest starts, and any downstream logic tied to its completion does not run -- the story simply continues from the player's choice.\n\n## Chaining events\n\nBecause `onCompleteEffects` are ordinary trigger effects, an event can start the next one when it finishes:\n\n```json\n{\n  \"onCompleteEffects\": [\n    {\n      \"type\": \"narrative-event-start\",\n      \"eventId\": \"next_scene\"\n    }\n  ]\n}\n```\n\nThat lets you chain across mechanics -- trigger to event, event to event, event to quest, quest-progress to event, and so on -- for briefings, staged encounters, multi-step introductions, boss scenes, and quest handoffs. Since only one event runs at a time, sequence them through completion rather than starting several at once.\n\nThe event to quest handoff is especially useful with the current UI, which surfaces the immediate objective above the input bar -- use it to give the player meta-guidance for navigating a chain.\n\n## Authoring tips\n\n- **Keep beats concrete and stageable.** Name who appears and what happens; write what the AI can act out in the current scene, not abstract state. The clearer the intended outcome, the more reliably the engine can tell the event is done.\n- **Don't use them for background guidance.** Narrative events are location-rooted, non-recurring, and suspend when the party leaves, so they are wrong for permanent world guidance or general story-state changes -- use a recurring [trigger](/mechanics/triggers) for that.\n- **Guard against accidental suspension.** Chains are brittle: leaving the starting location suspends the event even if the player didn't mean to go anywhere. When it matters, give the storyteller guidance to keep the scene in the current location until the beat resolves."}