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 a rich set of variable types to handle any narrative need: primitive types for basic data, enums for custom choice sets, asset types for project files, and arrays for collections.

Primitive Types

The four primitive types (Boolean, Integer, Float, and String) are the foundation for storing basic data 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)

Float Variables

Visual Indicator: Float

Values: Decimal numbers (floating-point)

Purpose: Store precise numeric data with fractional components. Floats are perfect for percentages, ratios, multipliers, and any value that requires decimal precision.

Common Examples:

• Float healthPercentage - Health as a percentage (e.g., 0.85 = 85%)
• Float speedMultiplier - Movement speed modifier (e.g., 1.5 = 150% speed)
• Float damageBonus - Additional damage multiplier (e.g., 2.3)
• Float accuracy - Hit chance rating (e.g., 0.92 = 92% accuracy)
• Float temperature - Environmental value (e.g., 98.6)
• Float exchangeRate - Currency conversion (e.g., 1.25)

String Variables

Visual Indicator: String

Values: Text (any characters, letters, numbers, symbols)

Purpose: Store textual data like names, locations, messages, and any information represented as text. Strings enable dynamic dialogue and personalization.

Common Examples:

• String playerName - Character name (e.g., "Alice")
• String currentLocation - Location identifier (e.g., "Village Square")
• String lastChoice - Record of player's selection (e.g., "Accepted Quest")
• String password - Secret code or password (e.g., "Open Sesame")
• String customMessage - Player-created text (e.g., "Hello World")
• String companionName - NPC name (e.g., "Sir Galahad")

Enum Variables

Visual Indicator: Enum

Enum (enumeration) variables let you define a custom set of named values. Unlike strings where any text is valid, enums restrict values to a predefined list you create.

Purpose: Create type-safe choices with a fixed set of options. Perfect for states, categories, and selections that should only be one of several specific values.

Creating Enum Variables:

1. Click the + button in the Variables Panel and select Enum
2. A form appears where you define the enum's options
3. Add options like "Idle", "Walking", "Running", "Attacking"
4. The variable will only accept these exact values

Common Examples:

• Enum playerState - Character state (Idle, Walking, Running, Attacking)
• Enum difficulty - Game difficulty (Easy, Normal, Hard, Nightmare)
• Enum weather - Current weather (Sunny, Cloudy, Rainy, Stormy)
• Enum faction - Player's faction (Alliance, Horde, Neutral)
• Enum questStatus - Quest state (NotStarted, InProgress, Completed, Failed)

Enum Nodes:

• Get Enum: Read the current enum value
• Set Enum: Change the enum to a specific option
• Equal Enum: Compare two enum values
• Switch On Enum: Branch based on the enum value (one output per option)
• Enum to String / String to Enum: Convert between enum and string
• Int to Enum: Convert an integer index to an enum value

Asset Variables

Asset variables store references to project files like images, characters, and audio. Instead of using file paths as strings, asset variables provide type-safe references with visual selectors.

Image Variables

Visual Indicator: Image

Purpose: Store references to image files in your project. Use them to dynamically change backgrounds, character portraits, or UI elements during gameplay.

Common Examples:

• Image currentBackground - Active scene background
• Image selectedPortrait - Character portrait to display
• Image inventoryIcon - Current item's icon

Character Variables

Visual Indicator: Character

Purpose: Store references to character files (.sfc). Use them to dynamically select which character appears in dialogue or whose variables to access.

Common Examples:

• Character currentSpeaker - Active dialogue character
• Character partyMember - Selected companion
• Character targetNPC - NPC being interacted with

Audio Variables

Visual Indicator: Audio

Purpose: Store references to audio files (MP3, WAV). Use them to dynamically change music, sound effects, or voice lines.

Common Examples:

• Audio backgroundMusic - Current music track
• Audio ambientSound - Environmental audio
• Audio voiceLine - Character voice clip

Array Variables

Visual Indicator: Arrays are shown with the base type pill plus a 3x3 grid of circles in the same color. For example, an Integer Array shows: Integer

Array variables store ordered lists of values. You can create arrays of most types: boolean arrays, integer arrays, float arrays, string arrays, and arrays of assets (image, character, audio). Note: Enum arrays are not currently supported.

Purpose: Store collections of related items. Perfect for inventories, party members, quest objectives, dialogue history, and any situation where you need multiple values of the same type.

Creating Array Variables:

1. Click the + button in the Variables Panel
2. Select the base type (e.g., Integer)
3. Check the "Array" checkbox in the creation form
4. The variable becomes an array of that type (e.g., Integer Array)

Common Examples:

• Integer inventory - List of item IDs (Integer Array)
• String visitedLocations - Places the player has been (String Array)
• Character partyMembers - Current party (Character Array)
• Boolean questObjectives - Completion states (Boolean Array)
• Audio playlist - Music tracks to play (Audio Array)

Array Operation Nodes:

• Add to Array: Append an item to the end of the array
• Remove from Array: Remove an item by value or index
• Get Array Element: Read an item at a specific index
• Set Array Element: Change an item at a specific index
• Array Length: Get the number of items in the array
• Clear Array: Remove all items from the array
• Array Contains: Check if an item exists in the array (returns boolean)
• Find in Array: Get the index of an item (-1 if not found)
• Get Random Element: Retrieve a random item from the array

For Each Loop:

The For Each Loop node iterates over all items in an array. It executes connected nodes once for each element, providing access to the current item and its index. Perfect for processing inventories, applying effects to all party members, or checking quest objectives.

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 form appears where you can configure your variable:

• Name: Enter a descriptive name for your variable
• Type: Select from Boolean, Integer, Float, String, Enum, Image, Character, or Audio
• Array: Check this box to create an array of the selected type
• Scope: Choose Local or Global
• Default Value: Set the initial value (type-dependent)
• Enum Options: For enum types, define the available choices

Click Create to add the variable to your script. The new variable appears in the Variables Panel, ready to use.

Variable Panel Features:

• Variable List: Shows all variables for the current script, organized by categories
• Type Indicators: Boolean Integer Float String Enum Image Character Audio
• Global Marker: icon appears next to global variables
• Collapsible Panel: Collapse/expand the panel to save screen space
• Search: Filter variables by name using the search bar
• Count Badge: Header shows total number of variables
• Clickable Values: Click a variable's value to quickly edit it inline
• Drag to Canvas: Drag a variable onto the canvas to create Get/Set nodes
• Edit Panel: Select a variable to edit its properties in the right sidebar panel

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)