Storyfall

Triggers

Triggers are global reactive rules that execute actions when game state conditions are met - apply effects, redirect to a scene, or both. They work across your entire story, watching for key moments and responding instantly.

What are Triggers?

Triggers are reactive rules that fire when conditions are satisfied. Unlike conditions on choices, which only control whether a single choice is visible, triggers work across your entire story. After every state change (choice effects and scene-enter effects), all enabled triggers are checked. The first one whose conditions match fires immediately.

When a trigger fires, it can:

  • Apply effects - modify variables, NPC sentiment, or faction reputation.
  • Redirect the player to a specific scene.
  • Do both - apply effects and then redirect.
  • Fire once or repeat every time conditions are met.

A trigger must have at least one effect or a target scene (or both).

Example Use Cases

  • Health reaches zero: Redirect to a “Game Over” scene.
  • Sanity drops below -50: Redirect to a “Madness” scene with a one-time story event.
  • Reputation with a faction reaches 80: Redirect to a “Faction Alliance” scene and set a flag.
  • Health drops below 10: Set lowHealthWarning = true to change UI text (no redirect needed).
  • Gold exceeds 100: Discover the NPC “Merchant Prince” (effects only).

Creating Triggers

To create a trigger:

  1. Go to your story editor.
  2. Click Triggers in the sidebar (or press Ctrl+Shift+G).
  3. Click Add.
  4. Configure your trigger:
    • Name: A descriptive name (e.g. “Sanity Break”). Readers see this as a notification when the trigger fires: “Triggered: Sanity Break”.
    • Redirect to Scene (optional): The scene to redirect to when the trigger fires. Leave empty for effect-only triggers.
    • Conditions: At least one condition is required. The trigger fires when all conditions are met.
    • Effects: Variable or relationship changes applied when the trigger fires. Required if no target scene is set.
    • Enabled: Toggle the trigger on/off without deleting it.
    • Fire Once: When enabled, the trigger only fires once per playthrough.
    • Priority: Higher numbers are evaluated first (default 0).
    • Internal Notes: Writer-only notes not shown to readers.

Conditions

Triggers use the same condition system as choice conditions. You can check:

  • Variables: Compare a variable’s value (e.g. health < 0, has_key = true).
  • NPC Sentiment: Check relationship values (e.g. Guard sentiment >= 50).
  • Faction Reputation: Check faction standings (e.g. Rebels reputation < -30).
  • Discovery State: Check if an NPC or faction has been discovered.

All conditions must be true for the trigger to fire (AND logic). Use condition groups for OR logic between groups.

Effects

Effects are modifications applied when the trigger fires. For redirect triggers, effects are applied before the redirect. For effect-only triggers, effects are the primary action. They work the same as choice effects:

  • Set a variable to a specific value.
  • Add to or subtract from a numeric variable.
  • Toggle a boolean variable.
  • Modify NPC or faction sentiment.
  • Discover or undiscover an NPC or faction.

Priority

When multiple triggers could fire at the same time, priority determines which one wins. Higher priority triggers are evaluated first. If two triggers have the same priority, they are evaluated in alphabetical order.

Set priority to manage conflicts:

  • Default priority is 0.
  • Use positive numbers (e.g. 10, 20) for high-priority triggers.
  • Use negative numbers (e.g. -10) for low-priority fallback triggers.

Fire Once vs. Repeating

  • Fire Once: The trigger fires the first time its conditions are met, then never again for that playthrough. Use this for one-time story events like cutscenes or special encounters.
  • Repeating (default): The trigger fires every time its conditions are met. Use this for persistent rules like “game over when health reaches zero” that should always apply.

Trigger Chaining

Triggers can chain: if a trigger’s effects cause another trigger’s conditions to become true, the second trigger fires immediately. This allows complex cascading reactions. Chains are capped at 10 levels to prevent infinite loops.

Example Chain

  1. Trigger A: “If betrayed_ally = true, set faction_reputation = -100.”
  2. Trigger B: “If faction_reputation < -50, redirect to Exile scene.”
  3. When the player betrays the ally, Trigger A fires first (setting reputation to -100), which then causes Trigger B to fire, ultimately landing the player in the Exile scene.

Disabling Triggers

You can temporarily disable a trigger without deleting it:

  • In the Triggers panel, click the eye icon on any trigger to toggle it on/off.
  • Disabled triggers are skipped during evaluation and shown with a “Disabled” badge.
  • Re-enable them at any time.

Next Steps

  • Variables & Conditions - Learn about the condition and effect system triggers use.
  • Characters - Understand how triggers interact with different character paths.
  • HTML Export - Export stories with triggers as standalone HTML files.