Beats and story arcs

Instructions alone cannot keep every promise. You can tell the storyteller "the mentor dies in act two", but without something that enforces it, the story might forget, rush it, or never get there. A beat ties a story moment or a lasting change to a condition you can check, such as finding four clues, and an arc chains those changes into stages. That is how key moments land when they should and information surfaces in the right order.

This is the most complex feature set in Imagina, and the one with the steepest learning curve. The page starts with why beats exist and when you need them, then teaches the mechanics. Start simple: one or two beats for the moments that matter most, before you build elaborate structures. This page assumes you know instructions and trackers.

What are beats and story arcs?

A story beat is a conditional story event. You define what must be true for it to fire (its conditions) and what happens when it does (a note to the storyteller, a lasting change to the story's context, and effects on the world's state). The engine checks every turn: are the conditions met? If so, the beat fires, once, unless you make it repeatable.

A story arc is a staged plotline. It chains beats into stages, where each stage's instructions replace the previous stage's, so the storyteller's brief evolves as the story progresses: peace, then invasion, then resistance, then aftermath.

A concrete example: a mystery world where the player investigates a murder. An Evidence tracker counts the clues they collect. A beat fires when Evidence reaches 5. It reveals a secret lore entry with the killer's identity and swaps the "Investigation" instruction block for a "Confrontation" one. Without the beat, the storyteller might reveal the killer too early, too late, or never.

Beats do three jobs, and the rest of this page takes them in turn:

1. Guarantee key moments (the building blocks).
2. Control information so the storyteller cannot spoil what it does not yet know.
3. Enforce cause and effect together with trackers.

When do you need beats?

If your story has moments that must happen at the right time, or information that must be revealed in the right order, you need beats. If the storyteller can handle it through instructions alone, you probably do not.

Genres that benefit:

• Mystery: gated revelations, clue chains, a final reveal that fires only when the player has earned it.
• Quest-driven adventure: act structure, staged objectives, a villain's plan advancing on a timeline.
• Romance progression: relationship milestones that change how a love interest behaves.
• Horror: escalating dread, the moment the threat becomes real, the point of no return.
• Progression, isekai, LitRPG: tier transitions, power shifts, world-state changes at key levels.
• Heist and thriller: planning, execution, and escape phases with distinct tones and rules.

When you can skip them:

• Sandbox: the player sets their own goals and the storyteller responds freely.
• Slice of life: the charm is in the lack of structure. Beats would feel artificial.
• Freeform exploration: if the order of events does not matter, beats add complexity without value.

Beats: the building blocks

Beats live under Advanced → Story Beats. The labels below are the editor's own, so you can match what you read here to what you see on screen.

The parts of a beat

• Id. A stable name, unique within the world. New beats get beat_1, beat_2, and so on. Rename them to something you will recognize, like act1_storm_breaks, because other beats reference them and the Debug panel lists them by id.
• When it fires: Conditions. Every condition must be true for the beat to fire. With no conditions, the beat fires on turn 1.
• What the narrator hears: Describe to AI. An optional one-time note the storyteller sees on the turn an automatic beat fires, then never again. Use it for the moment itself: "The king's expression hardens as he reads the letter. He does not finish it." It supports macros such as the player's name. A beat with a narrative condition is fired by the storyteller while it writes and does not receive this note, so put the essential moment into the condition's description instead.
• What stays: Appends to Dynamic Story Context. Optional text added permanently to the storyteller's context from the next turn onward. Great for act transitions and tone overlays: "The king is dead. The court speaks in whispers now."
• What changes: Engine effects. Optional deterministic changes applied when the beat fires. With no effects, the beat only injects text.
• One-shot. On by default: the beat fires once. Turn it off and set Cooldown turns to let it fire again after a minimum gap.

Conditions you can use

Add as many as you need. They all have to pass together.

• After turn N: eligible once the story reaches that turn.
• Player character is...: only when the player picked one of the listed characters.
• Tracker value...: compare a tracker with equals, does not equal, at least, at most, exists, or missing. This is the most common trigger.
• Random chance per turn: a percentage rolled each turn, only once every other condition already passes.
• After beats fired: after another beat (or any, or all, of a list) has fired. This is how you chain acts.
• Not after beats: only if a listed beat has not fired. Branch exclusion.
• AI-judged narrative moment: the storyteller judges whether the player's action matches a description you write, phrased from the player's perspective: "when the player decides to confess their feelings to Claire." Use it sparingly, and for moments that depend on what the player does rather than on a number.
• Match any of (OR group): a group where any one option passing is enough. The beat's other conditions still apply on top. Groups cannot contain a narrative condition.

Timing. Conditions based on turns, trackers, and other beats are checked by the engine before the storyteller writes the turn, so their effects apply to that same turn. A narrative condition is judged by the storyteller while it writes, so state changes land that turn, and any lasting text or instruction changes apply from the next turn. For automatic beats, persistent context applies from the firing turn.

Effects you can apply

• Set tracker value: write a value to a tracker, creating it if needed. One field takes every form: an absolute value ("6"), a delta ("+5", "-3"), a new current and max for a bar ("12/35"), or a scale step ("Warm"). Create the tracker with the right display type first, because a tracker created by a beat holds plain text.
• Retire tracker: remove a tracker from play.
• Replace additional instruction: swap a named instruction block's content for the rest of the journey.
• Alter character description: permanently change an NPC's or player character's description or physical description, by replacing it or adding on top. Built for transformation arcs. Pair it with a Describe to AI note so the turn narrates the change.
• Set character outfit: dress a character in one of their authored outfits, updating their sprites. The story can dress them again later.
• Change objective: update the journey objective, optionally showing the player a new objective card.
• Change narration style: replace the world's narration instructions from this point on.
• Present choice to player: offer a structured choice with up to six options.
• Request player input: ask the player for free text.
• Reveal lore (secret): reveal a hidden lore entry to the storyteller. See the next section.
• Reveal location: make a hidden seeded location known.
• Move scene to location: move the scene to a seeded location.
• Show scene image: display one of the world's Extra Images with the turn.
• Force AI scene image: generate an illustration on the firing turn, in worlds with turn images on.
• Show character image: display a specific gallery picture of a character with the firing turn. Adult pictures need an adult journey, and in immersive mode a sprite takes the character's spot on stage instead of sitting beside the prose.

Beat groups

At the bottom of the Story Beats section, Beat groups let you group several beats so that only one of them ever fires per journey. When more than one member's conditions pass on the same turn, the engine picks one at random and the others go silent for the rest of the journey. Use it when a single mystery, secret, or starting situation has several variants and you want exactly one to play out: an abandoned house that is haunted, or a research site, or a cult's holding ground, with each new journey revealing one truth. Members of a group cannot use narrative conditions.

Warnings, not walls

The editor checks your wiring as you go: a beat that references a deleted beat, a tracker no character starts with, an instruction block that does not exist, a secret lore entry with no revealing beat. These show as warnings on the beat and never block saving, so you can leave unfinished wiring in a draft and come back to it.

Controlling information

One of the most common frustrations in AI storytelling is the storyteller spoiling its own surprises: naming the killer before the investigation is done, describing a place the player has not found, revealing a twist the player was supposed to uncover. Beats solve this by controlling what the storyteller knows and when.

• Secret lore. A lore entry marked Secret is invisible to the storyteller until a beat with a Reveal lore effect fires. It cannot leak what it cannot see. Once revealed, the entry stays in the storyteller's context for the rest of the journey. Use secrets sparingly, for high-impact, earned reveals, and always pair each one with a revealing beat: the editor warns you until you do. Write the cover story (what everyone believes) as ordinary lore or in the instructions, so the storyteller has something true-enough to narrate before the reveal.
• Hidden locations. A location with Known to the player from the start turned off stays out of the storyteller's catalog until the scene arrives there or a Reveal location beat fires.
• Hidden truths on characters. An NPC's hidden truth is different: the storyteller always knows it and plays the character consistently with it, but keeps it from the player until the story earns the reveal. Use a hidden truth when the character should behave as if the secret is true from turn one, and secret lore when the storyteller itself should not know.
• Replacing an instruction block. The Replace additional instruction effect is how you correct a false belief after a reveal: the "What everyone believes" block becomes the "What is actually true" block.
• Persistent context. Appends to Dynamic Story Context makes a permanent change part of the storyteller's understanding: "the king is dead" for the rest of the journey.
• Narration style changes. A Change narration style effect shifts how the story is written from the firing turn on (from the next turn for a narrative-triggered beat), so the tone turns at the right moment rather than at random.

A worked mystery. The lore entry "Who killed the steward" is marked Secret. An ordinary entry, "The official story", says the steward fell from the tower. An Evidence counter rises as the player finds clues. A beat with the conditions Tracker value: Evidence at least 4 and AI-judged narrative moment: the player confronts Vanda about the missing report carries a Reveal lore effect targeting the secret. Before it fires, the storyteller only has the official story and will deflect speculation with it. After, the truth is canon and the storyteller can play the confrontation with full knowledge. The full walkthrough is in How do I make secret lore entries?.

Cause and effect: beats and trackers together

Trackers are the most common beat trigger and the most common beat effect, and together they form a loop:

1. The player's choices change trackers, through the update instructions you wrote.
2. A beat fires when a tracker reaches a threshold.
3. The beat changes the world: it adjusts another tracker, replaces an instruction block, reveals something.
4. The changed world shapes everything that follows.

Example. In a political drama, the player's choices move a Crown Favor gauge. When it drops below 30, a beat fires. Its Describe to AI note says the king's desperation shows for the first time. Its persistent context says the court has started hedging its bets. Its effects replace the "Court politics" instruction block with one where the nobles plot against the player openly. The player's earlier choices caused all of this. The beat made it reliable.

Patterns worth knowing:

• Chain beats with After beats fired to build acts: beat B fires only after beat A.
• Use a beat with effects and no text to silently set state, such as flipping a hidden flag when the player crosses a line, without a visible story moment.
• Gate a reveal behind a tracker threshold plus Reveal lore. The classic mystery pattern.
• Let a player setting seed a tracker, then branch on it with Tracker value conditions. This is how "which faction did you pick?" becomes different beats.

Story arcs: staged plotlines

Story arcs (beta) live under Advanced → Story Arcs. An arc is a staged plotline in one place: a mystery that opens as trust rises, a corruption that deepens act by act, a romance that moves through phases. Building this by hand means juggling an instruction block, a tracker, and a handful of beats. An arc puts the whole thing behind one card with a tab per stage.

How arcs work:

• An arc is a sequence of stages. Exactly one stage is active at a time, and its text is what the storyteller follows.
• Stage 1 holds the arc's starting instructions, active from the first turn. Every later stage has Advances when conditions, the same conditions beats use. When they pass, that stage's text replaces the arc's instructions for the rest of the journey. Stages always advance in order.
• Every stage after the first (and Stage 1 when it has start conditions) can carry a Transition note, a one-time message to the storyteller on the turn the stage activates, so the shift lands as a story moment rather than a silent gear change.
• The storyteller never sees the instructions of future stages or the shape of the arc. Models that know "this is phase two of four" tend to telegraph the story. If a stage needs pacing, put it in the text: "This is the midpoint of the investigation. Escalate suspicion, but do not name the culprit yet." One caveat: the description of a narrative condition is visible while that stage is eligible, so keep unrevealed twists out of those descriptions.

Write each stage as if it stands alone. A stage's text fully replaces the previous one, so restate what still matters and change what changed.

Starting an arc later. On the Stage 1 tab, turn off Active from the first turn and stage 1 gets its own Starts when conditions. Until they pass, the arc contributes nothing, and the storyteller does not know it exists. This is how you chain arcs: have "Act 1" set a tracker in its final stage, and gate "Act 2" on it. Arcs are otherwise independent, so an investigation, a romance, and a rivalry can run side by side at their own pace.

Under the hood, an arc is a named instruction block (the current stage's text) plus one beat per stage that performs the swap. Those beats stay visible in Story Beats with an arc label, so you can open a stage's beat and hang extra effects on it: a tracker write to make progress visible, a lore reveal, an outfit change. The Lore Map shows each arc as a node wired to its stage beats.

A heist in three stages:

• Stage 1, planning: "The crew is gathering. Every scene should surface one detail about the target, the guards, or a crew member's doubts. Nobody moves on the vault yet."
• Stage 2, execution (Advances when: AI-judged narrative moment, "the player gives the signal to begin the heist", with the transition note "The lights in the gallery go out on schedule."): "The heist is in progress. Real time, short sentences, every turn something goes slightly wrong. The plan from stage one is the reference point for what should be happening."
• Stage 3, escape (Advances when: Tracker value, Alarm equals "raised", or After beats fired, the vault-opened beat): "The crew is out or caught. Aftermath and consequences. Who kept their word, who did not, and what the city knows."

Playtest each transition to check that the new instructions actually change the scene.

Examples

Complete setups you can adapt. Each names the conditions and effects and says what the player experiences.

A mystery's revelation chain

• An Evidence counter rises through update instructions as the player finds clues.
• first_crack fires at Evidence at least 2. Describe to AI: "For the first time, the official story does not fit. Let one detail refuse to line up." No effects.
• killer_revealed fires at Evidence at least 5 and after first_crack. Effects: Reveal lore on the secret entry, Replace additional instruction "Investigation" with confrontation rules.
• endgame fires after killer_revealed and an AI-judged moment, "the player accuses the killer to their face". Effect: Change objective to "Make it stick."

A romance's relationship milestones

• An Affection scale (Cold, Guarded, Warm, Close, Devoted) moves one step per honest moment or broken promise.
• opens_up fires at Affection at least Close. Describe to AI: "She tells the player about the year she does not talk about. Keep it short and let her regret saying it." One-shot.
• all_in fires at Affection equals Devoted. Effects: Reveal lore on her secret, Replace additional instruction "Her rules" with a version where she stops hiding.

A heist's planning, execution, and escape

• The three-stage arc above, with the execution stage gated on the player's intent and the escape stage on the alarm tracker or the vault beat, whichever comes first.

A horror's escalation

• A hidden Dread gauge rises as the player explores.
• first_contact fires at Dread at least 60. Describe to AI: "The thing in the walls touches the player for the first time. One sentence, then silence." Appends to Dynamic Story Context: "The player has been touched. Ordinary objects are no longer safe to describe as ordinary."
• no_return fires at Dread at least 90. Effects: Change narration style to fragmented, unreliable prose. Persistent context: "There is no leaving the house now."

Common mistakes

• Overly broad triggers. A beat fires too early because its conditions are loose. Be precise about what must be true, and combine a tracker gate with a narrative moment when the timing matters.
• Beats that never fire. Conditions too strict, or a tracker threshold the update instructions can never reach. Playtest, and watch the Debug panel to see whether the tracker moves and the beat fires.
• Forgetting the tracker. A beat waits on a threshold, but the tracker's update instructions are vague or missing, so it never moves.
• Arcs that railroad. Stages that advance on a turn count regardless of what the player did. Arcs should respond to choices, not override them. Gate stages on trackers and narrative moments.
• Too many beats. A world with thirty beats is a world where nothing can happen naturally. Use beats for the moments that matter and let the storyteller handle the rest.
• A secret with no revealing beat. It can never surface. The editor warns you, so take the warning seriously.
• Reveals out of nowhere. A beat that fires with no setup feels random. Foreshadow in the instructions and lore ("the king has been watching the player carefully"), so the firing feels earned, and use the Describe to AI note to land the moment.

---

Frequently asked questions