Variables

Variables store data that persists throughout your story. Use them to track player options, inventory, stats, quest progress, and any other state that changes as the narrative unfolds.

Overview

Variables are a core component of StoryFlow's visual scripting system (also referred to as the node editor), allowing you to create dynamic, reactive stories that remember player actions and adapt based on their selections. You can get and set variable values without writing any code, enabling complex interactive narratives with branching paths, conditional dialogue, and stat-based gameplay.

What Variables Enable:

• Track whether the player has completed quests or talked to NPCs
• Store inventory items, health points, gold amounts, and other stats
• Create conditional dialogue that changes based on previous selections
• Build relationship systems, karma meters, and alignment tracking
• Share state between different script files using global variables

Variable Types

StoryFlow Editor supports two variable types: Boolean and Integer. Each type serves different purposes and has different node types for reading and writing values.

Boolean Variables

Visual Indicator: Boolean

Values: true or false

Purpose: Store yes/no, on/off, has/doesn't have states. Booleans are perfect for flags, switches, and binary conditions.

Common Examples:

• Boolean hasKey - Player has obtained the key
• Boolean talkedToGuard - Player has spoken with the guard
• Boolean questCompleted - Quest has been finished
• Boolean doorIsOpen - Door state
• Boolean playerIsAlive - Player alive status
• Boolean acceptedQuest - Player accepted a quest offer

Integer Variables

Visual Indicator: Integer

Values: Whole numbers (positive, negative, or zero)

Purpose: Store numeric data like counts, stats, scores, and quantities. Integers can be used in mathematical calculations and comparisons.

Common Examples:

• Integer playerHealth - Current hit points (e.g., 100)
• Integer goldAmount - Currency quantity (e.g., 500)
• Integer questProgress - Completion percentage (e.g., 3 out of 5)
• Integer relationshipLevel - NPC affection rating (-10 to +10)
• Integer enemiesDefeated - Kill count (e.g., 15)
• Integer daysPassed - In-game time tracking (e.g., 7)

Creating Variables

Variables are created and managed through the Variables Panel on the left side of the editor. The panel shows all variables for the current script file.

To Create a New Variable:

1. Open a script file in the editor (variables belong to scripts)
2. Look at the Variables Panel on the left sidebar
3. Click the Add button (+) at the top of the panel
4. A dropdown appears with two options: Boolean or Integer
5. Select the type you need
6. A new variable appears in the list with a default name (e.g., "NewVar0")
7. Click the variable name to rename it to something descriptive

Variable Panel Features:

• Variable List: Shows all variables for the current script
• Type Indicator: Boolean for boolean, Integer for integer
• Global Marker: icon appears next to global variables
• Count Badge: Header shows total number of variables
• Drag to Canvas: Drag a variable onto the canvas to quickly create Get/Set nodes

Local vs Global Variables

Variables in StoryFlow Editor can have two different scopes: Local (default) or Global. Understanding the difference is crucial for organizing multi-script projects.

Local Variables

Scope: Exist only within the current script file

Storage: Saved inside the .sfe script file

Lifespan: Reset to default values each time the script starts

Use Cases:

• Temporary state within a single scene or dialogue
• Loop counters and intermediate calculations
• Conversation-specific flags (e.g., Boolean askedAboutQuest in a merchant dialogue)
• Local options that don't need to persist (e.g., dialogue option tracking)

Example: A dialogue script for a merchant might have a local Boolean showSecretOption that tracks whether the player asked the right questions in that specific conversation. It doesn't need to be global because it's only relevant to that one dialogue tree.

Global Variables

Scope: Accessible from ALL script files in the project

Storage: Saved in global-variables.json at the project root

Lifespan: Persist across script transitions and play sessions

Visual Indicator: Globe icon next to the variable name

Use Cases:

• Player stats that persist throughout the game (health, gold, experience)
• Quest completion flags accessed from multiple scripts
• Inventory items that affect dialogue across different scenes
• Story progression flags (chapter completed, character met, etc.)
• Game-wide settings and unlocks

Example: A global Integer playerGold can be checked by a merchant script, modified by a quest reward script, and displayed in a status menu script. All scripts see the same value.

Converting to Global

To mark a variable as global:

1. Right-click the variable in the Variables Panel
2. Select "Make Global" from the context menu
3. The variable is now global and will show a globe icon

Using Variables

Once you've created variables, you use them in your story through Get and Set nodes.

Reading Variables (Get Nodes)

Get nodes read the current value of a variable and output it through a data handle.

Creating a Get Node:

• Method 1: Drag a variable from the Variables Panel onto the canvas, then select "Get" from the menu
• Method 2: Right-click the canvas, navigate to the Variables section, and select the Get node for your variable

Common Pattern - Reading for Conditions:

1. Create a Boolean Get node for Boolean hasKey
2. Connect its output (yellow handle) to a Branch node's condition input
3. The Branch will route to True if the player has the key, False otherwise

Writing Variables (Set Nodes)

Set nodes change a variable's value. They have both execution flow and data connections.

Set Node Features:

• Execution Input (top left): When to set the variable
• Value Input (bottom left): What value to set (can be connected or manually entered)
• Execution Output (top right): Continues story flow after setting
• Value Output (bottom right): Pass-through of the new value for chaining

Example - Setting a Boolean:

1. Player clicks dialogue option "Take the key"
2. Option output connects to execution input of Set Boolean node for Boolean hasKey
3. Value input is set to true (checkbox checked)
4. Variable Boolean hasKey is now true
5. Execution continues to next dialogue

Example - Incrementing an Integer:

1. Create Get Integer node for Integer playerGold
2. Create a Plus node
3. Connect Get node output to Plus node top input
4. Set Plus node bottom input to 50 (reward amount)
5. Create Set Integer node for Integer playerGold
6. Connect Plus node output to Set node value input
7. Connect execution flow through the Set node
8. Result: Integer playerGold increases by 50

Conditional Dialogue Options

Dialogue nodes have optional condition inputs for each option. Connect a boolean handle to make an option appear only when the condition is true.

Example - Item-Gated Option:

1. Create a Dialogue node with the option "Unlock the door"
2. Create a Boolean Get node for Boolean hasKey
3. Connect the Get node's output to the option's condition input (yellow handle on left)
4. The "Unlock the door" option only appears if Boolean hasKey is true

Best Practices

Follow these guidelines to use variables effectively in your interactive narratives.

Naming Examples

You're free to name variables however you prefer. Here are some common patterns you might find useful:

• camelCase Example: Boolean hasCompletedQuest or has_completed_quest
• Descriptive Names: Boolean talkedToMerchant compared to Boolean flag1
• Boolean Prefixes: You can start booleans with has, is, can, should
• Integer Examples: Nouns for quantities ( Integer goldAmount , Integer healthPoints )
• Abbreviations: Boolean questCompleted vs Boolean qstCmpltd

Scope Management

• Default to Local: Only make variables global if they need to be shared
• Document Globals: Use Comment nodes to explain what global variables do
• Consistent Naming: Prefix globals with global if needed (e.g., globalPlayerHealth)
• Centralize Updates: Modify important globals in dedicated scripts to avoid conflicts

Initial Values

• Set Defaults: Initialize variables at the start of your project
• Use Start Script: Set global variable defaults in your startup script
• Document Ranges: Comment expected value ranges (e.g., health: 0-100)

Organization

• Group Related Variables: Keep variables for the same system together in the panel
• Clean Up Unused: Delete variables that are no longer needed
• Consistent Patterns: Use similar names for similar concepts (e.g., hasKey, hasSword, hasMap)

Common Patterns

Quest Tracking:

questAccepted, questCompleted
questProgress (e.g., 0-5 objectives)

Inventory System:

hasKey, hasSword, hasPotion
potionCount, goldAmount

Relationship System:

metCharacter, isAlly, isEnemy
relationshipLevel (-10 to +10)

Player Stats:

health (0-100), mana (0-100), level (1-99)