Narrative Events (Advanced)

narrativeEvents

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.

In the editor

"Multi-turn narrative beats that can be started by triggers"

Editor location: World → Advanced → Narrative Events
Editor type: JSON + ADD ITEM
API endpoint: /sections/narrativeEvents.json/sections/narrativeEvents.md
Size limits: No character-length caps for this section.

json
{
  "narrativeEvents": {
    "<key>": {
      "title": "string",
      "beats": "string",
      "targetTurns": "number",
      "onCompleteEffects": [
        "(recursive)"
      ]
    }
  }
}

Example: a narrative event

json
{
  "wounded_courier": {
    "title": "The Wounded Courier",
    "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.",
    "targetTurns": 3,
    "onCompleteEffects": [
      {
        "type": "quest-init",
        "operator": "set",
        "value": "Deliver the Sealed Letter"
      }
    ]
  }
}

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:

Starting it with a trigger

json
{
  "deliver_letter_intro": {
    "name": "deliver_letter_intro",
    "recurring": false,
    "conditions": [
      {
        "type": "party-location",
        "operator": "equals",
        "value": "The Forest Road"
      }
    ],
    "effects": [
      {
        "type": "narrative-event-start",
        "eventId": "wounded_courier"
      }
    ]
  }
}

Fields

title

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

beats

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.

targetTurns

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.

onCompleteEffects

Optional list of normal trigger effects -- 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.

How narrative events work

A narrative event is a named entry in the narrativeEvents map. Defining one does not start it:

Start -- a trigger fires a narrative-event-start effect naming the event's key.
Run -- while active, the beats steer the storyteller and NPC intents, and the engine watches the story against those same beats.
Complete -- when the engine judges the outcome has happened, the event completes and its onCompleteEffects fire.

Three rules shape how you design them:

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.
They are always non-recurring. A given event runs once per start.
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.

Triggers can gate on an event's progress with the narrative-event-status condition, and a quest can complete when an event completes via completionCondition: { "type": "narrative-event-completed", "eventId": "..." } (see Quests).

What happens in play

Say a scene starts wounded_courier while the party is on the forest road.

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.

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.

Chaining events

Because onCompleteEffects are ordinary trigger effects, an event can start the next one when it finishes:

json
{
  "onCompleteEffects": [
    {
      "type": "narrative-event-start",
      "eventId": "next_scene"
    }
  ]
}

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

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

Authoring tips

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.
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 for that.
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.

Narrative Events (Advanced)

#Schema

#Example: a narrative event

#Starting it with a trigger

#Fields

#title

#beats

#targetTurns

#onCompleteEffects

#How narrative events work

#What happens in play

#Chaining events

#Authoring tips

Schema