Storyfall

Variables & Conditions

Variables store information during a playthrough. Conditions check those values to show or hide content. Together, they let your story react to reader choices. NPCs and factions are also a type of variable, with a relationship value you can check and modify just like any other.

What are Variables?

Variables are values that track information throughout your story. Think of them as the story’s memory - they remember things like:

  • Player name.
  • Player stats (health, strength, intelligence).
  • Relationships (trust with NPCs, faction reputation).
  • Inventory items.
  • Story flags (has the player visited a location?).
  • Time or progression markers.

Creating Variables

To create a variable:

  1. Go to your story editor.
  2. Click Variables in the sidebar.

Variables panel in the story editor

  1. Click “Add”.
  2. Configure your variable:
    • Name: A unique name (e.g. “Health”).
    • Type: Number, String, or Boolean.
    • Initial Value: Starting value for all playthroughs.
    • Visibility: Show to readers in the Stats page or keep hidden.
    • Party Variable: Share this variable across all players in co-op multiplayer.

Variable Types

Number Variables

Track numeric values like stats, currency, or counters.

health = 100
gold = 50
trust_level = 0

String Variables

Store text like names, locations, or inventory items.

player_name = "Hero"
current_location = "Village"
equipped_weapon = "Iron Sword"

Boolean Variables

Track yes/no states or flags.

met_merchant = false
has_key = true
sided_with_rebels = false

Using Variables in Text

Insert variables directly into your story text:

  1. In the scene editor, click where you want the variable.
  2. Type { or click the variable button in the toolbar.
  3. A dropdown appears showing your variables, NPCs, factions, and characters.

Variable insertion menu opened from the scene editor

  1. Select the one you want to insert.
  2. Choose how it displays: the current value, conditional text (e.g. show different text based on a threshold), or the entity’s avatar.
  3. The variable will appear as a styled badge in your scene text.

Example

You have {gold} gold coins remaining.

When rendered, this becomes:

You have 50 gold coins remaining.

Conditions

Conditions show or hide text based on variable values.

Creating Conditional Text

  1. In the scene editor, type { or click the variable button in the toolbar.
  2. Select a variable, NPC, faction, or character.
  3. Add a condition with an operator and comparison value, followed by the text to display.

The badge shows the condition and text together, e.g. {gold > 10: You are rich.}. Readers only see the text if the condition is met.

Example

Your relationship with Marcus is: {marcus >= 20: Friendly}{marcus < 20: Distant}

When rendered (if Marcus’s sentiment is 20 or higher), this becomes:

Your relationship with Marcus is: Friendly

Condition Operators

  • = - Equals.
  • ≠ - Not equals.
  • > - Greater than.
  • < - Less than.
  • ≥ - Greater than or equal.
  • ≤ - Less than or equal.
  • discovered - NPC or faction has been discovered.
  • not discovered - NPC or faction has not been discovered.

Compound Conditions (AND / OR)

Combine multiple conditions with AND or OR to create complex logic:

{player_health > 75 AND has_sword = true: You confidently draw your sword and prepare for battle.}

{gold >= 100 OR completed_quest = true: The merchant nods respectfully and opens his special inventory.}

To create a compound condition:

  1. Type { and select a variable.
  2. Choose an operator and enter a value.
  3. On the next step, click + AND condition or + OR condition instead of Continue to text.
  4. Select the next variable, operator, and value.
  5. Repeat to add more conditions, then click Continue to text to finish.

AND means all conditions must be true. OR means any one condition can be true. When mixing both, AND is evaluated before OR — so A OR B AND C means A OR (B AND C).

Effects

Effects modify variables when something happens in your story. You can add them to choices or as scene on-entry effects that trigger automatically when a reader enters a scene.

Adding Effects to Choices

  1. Create or edit a choice.
  2. Click the fx button.

Choice effects panel opened from a choice row

  1. Configure the effect:
    • Select the variable to modify.
    • Choose the operation (set, add, subtract).
    • Enter the value.

Example Choice with Effects

Choice: “Buy health potion (50 gold).”

Effects:

  • gold subtract 50.
  • has_health_potion set to true.

Conditional Effects (Functions)

Effects can have their own conditions, so they only fire when a variable, NPC, or faction meets certain criteria. This lets you create effects that respond to the current state of the story.

Adding a Condition to an Effect

  1. Click the fx button on a choice or scene.
  2. Under the IF (optional) header, click ”+ Add condition”.

Conditional effect editor showing the IF section

  1. Choose a variable, NPC, or faction to check.
  2. Select an operator and enter a comparison value.
  3. Under THEN, configure the effect as usual (target, operation, value).

You can add multiple conditions and join them with AND or OR. Conditions joined with AND must all be true. Conditions joined with OR only need one to be true.

Example

Choice: “Search the room”

  • clues add 1 (always fires).
  • IF perception >= 15 THEN found_secret_passage set to true.

Effects with conditions appear in a special card format showing the IF/THEN logic, making them easy to distinguish from simple effects.

Random Effects

Effects support randomized values, letting you create unpredictable outcomes like variable damage, loot drops, and skill checks.

Random Value Types

Instead of entering a static number for an effect’s value, you can use one of these formats:

FormatExampleResult
Range5-15Random integer between 5 and 15.
Dice2d6+3Rolls 2 six-sided dice, adds 3 (result: 5-15).

Dice notation supports modifiers: 1d20-5, 3d8+2, 4d6.

Probability (Chance to Fire)

Each effect can have a probability that determines whether it fires at all:

  • Always (default): The effect always applies.
  • Percentage: A fixed chance, e.g. 70%.
  • Formula: A dynamic chance based on variables, e.g. 0.5 + speech * 0.02 (base 50% + 2% per speech point).

Formulas can reference any variable or NPC sentiment in your story. Missing variables default to 0.

Setting Up Random Effects

  1. Edit a choice and open the Effects section.
  2. Add an effect and click ”+ Advanced”.
  3. Choose a value type: Static, Range, or Dice.
  4. Optionally set a Chance: Always, Percentage, or Formula.

Example: Combat with Variable Damage

Choice: “Attack the dragon”

  • Effect: dragon_health subtract 2d6+3 (5-15 damage).
  • Probability: 70% (chance to hit).

If the probability check fails, the effect is skipped entirely. If it passes, the dice are rolled and the resolved value is applied. Players see the actual result (e.g. “dragon_health -12”), not the formula.

Example: Skill Check

Choice: “Persuade the guard”

  • Effect: guard_convinced set to true.
  • Probability formula: 0.3 + charisma * 0.03.

With charisma at 10, this gives a 60% chance of success.

Example: Relationship System

A simple relationship tracking system:

1. Create an NPC

Create an NPC called “Marcus” with a starting sentiment of 0.

2. Add Effects to Choices

Scene: Meeting Marcus

Choice: “Help Marcus carry supplies” (+10 sentiment).

  • Effect: Marcus add 10.

Choice: “Refuse to help” (-5 sentiment).

  • Effect: Marcus add -5.

3. Use Conditional Text

Later Scene:

{Marcus >= 20: Marcus greets you warmly. "Friend! I'm glad you're here."}

{Marcus < 0: Marcus avoids eye contact. "What do you want?"}

4. Gate Content

Choice: “Ask Marcus for help”

Condition: Marcus >= 15.

If the condition isn’t met, the choice won’t appear or will be disabled.

Common Patterns

Health System

player_health = 100
max_health = 100

Choices can damage or heal, conditions show different text based on health ranges.

Inventory

has_key = false
gold = 50
potion_count = 0

Track items as booleans or quantities.

NPCs (Non-Player Characters)

NPCs are special character entities you can track throughout your story. They work similarly to variables but are designed specifically for tracking characters.

Creating NPCs

NPCs have built-in properties:

  • Name: The character’s name.
  • Description: Who they are.
  • Faction: Optional group affiliation.
  • Sentiment: Relationship value (-100 to 100).
  • Discovered: Whether the reader has met them. NPCs and factions can be discovered through a scene on-entry effect or a choice effect, revealing them to the reader at the right moment in the story.

Using NPCs

NPCs can be used in conditions and effects just like variables:

Condition Example:

{Marcus >= 20: Marcus greets you warmly.}

Effect Example: When creating a choice effect:

  • Target: Marcus (NPC).
  • Operation: Add.
  • Value: 10.

This increases Marcus’s sentiment by 10 points.

Factions

Factions represent groups or organizations in your story. They work like NPCs but represent collective entities.

Creating Factions

Factions have similar properties to NPCs:

  • Name: The faction name.
  • Description: What the faction represents.
  • Sentiment: Reputation value (-100 to 100).
  • Discovered: Whether the reader knows about them.

Using Factions

Factions are useful for tracking reputation with groups:

Condition Example:

{Rebels >= 50: The rebels trust you enough to share their plans.}

Linking NPCs to Factions: When an NPC belongs to a faction, you can use both individual and group reputation in your story logic.

Faction Patterns

Multiple Factions: Create opposing factions where helping one hurts the other:

  • Guild reputation +10.
  • Thieves reputation -5.

Faction Unlocks: Use faction reputation to unlock story content:

{Merchant Guild >= 75: You gain access to the exclusive trading routes.}

Next Steps