Best Practices

This page shows common patterns and examples for organizing your project. You're free to structure your stories however works best for you - these are just suggestions to consider.

Project Organization

Many developers find it helpful to organize their project as their story grows in complexity. Here are some common organizational patterns you might consider.

Folder Structure Example

You can organize your scripts and assets however you like. Here's one example of a folder hierarchy:

MyProject/
├── Content/
│   ├── Chapters/
│   │   ├── Chapter1/
│   │   │   ├── scene1.sfe
│   │   │   ├── scene2.sfe
│   │   │   └── scene3.sfe
│   │   ├── Chapter2/
│   │   │   └── ...
│   ├── Characters/
│   │   ├── player_dialogue.sfe
│   │   ├── npc1_dialogue.sfe
│   │   └── npc2_dialogue.sfe
│   ├── Systems/
│   │   ├── inventory.sfe
│   │   ├── combat.sfe
│   │   └── quests.sfe
│   ├── Images/
│   │   ├── backgrounds/
│   │   ├── characters/
│   │   └── ui/
│   └── global-variables.json
└── MyProject.storyflow

Naming Examples

You can name your files and variables however you prefer. Here are some common patterns:

• Scripts: lowercase with underscores (e.g., chapter1_intro.sfe, merchant_shop.sfe)
• Variables: camelCase (e.g., IntegerplayerHealth, BooleanhasMetMerchant)
• Node Titles: descriptive titles in dialogue nodes (e.g., "Guard: Checkpoint Warning" compared to just "Guard")
• Images: prefix by type (e.g., bg_forest.png, char_hero.png)

Startup Script

Some developers create a dedicated startup script that:

• Initializes global variables
• Sets default background images
• Provides a main menu or chapter select
• Acts as the entry point for testing

Tip

Name your startup script something obvious like main_menu.sfe or start.sfe. Set it as your project's startup script in the project settings.

Node Graph Structure

Well-structured node graphs are easier to understand, debug, and maintain.

Visual Layout Examples

• Left to Right Flow: Some developers arrange nodes from left to right to show story progression
• Vertical Branching: Option branches can be placed vertically (top to bottom) for visual clarity
• Connection Crossings: You can minimize connection crossings by reorganizing nodes
• Grouping: Related logic nodes can be kept close together
• Comment Nodes: Comment nodes can help document complex sections

Modularity with Run Script Nodes

You can break large stories into smaller, reusable scripts. Here are some common approaches:

• Character Interactions: Separate scripts for each major character's dialogue trees
• Reusable Systems: Shop, inventory, or battle systems as standalone scripts
• Chapter/Scene Division: Story split into logical chapters or scenes
• Conditional Events: Scripts for events that can be triggered from multiple places

Example: Shop System

Instead of copying shop dialogue to every merchant, create shop_system.sfe and call it with Run Script nodes. Use global variables to track inventory and gold across all merchants.

Connection Patterns

• One Path Per Option: Each dialogue option typically has exactly one outgoing connection
• Descriptive Titles: Descriptive node titles can help clarify which handle does what
• Dead Ends: Dialogue branches typically reach an End node or return to the main flow
• Testing: The Play feature lets you walk through every possible branch

Variable Management

Proper variable usage is key to creating complex, stateful narratives.

Local vs Global Variables

You can choose the scope for your variables based on how long the data needs to persist:

Local Variables

• Scope: Single script file only
• Lifetime: Reset when script restarts
• When to use: Data that only matters within one conversation, scene, or sequence
• Benefit: Easier to debug, no risk of affecting other scripts

Global Variables

• Scope: Available across all scripts
• Lifetime: Persist throughout the entire story
• When to use: Data that multiple scripts need to read or modify
• Caution: Changes affect the entire project, requires careful management

Variable Naming Examples

• Boolean Flags: You can prefix with "has", "is", or "can" (e.g., BooleanhasKey, BooleanisQuestComplete, BooleancanEnterCastle)
• Counters: Descriptive names (e.g., IntegerenemiesDefeated, IntegergoldAmount, IntegerconversationCount)
• Abbreviations: IntegerplayerHealth compared to IntegerplrHP
• Grouping by Prefix: Related variables can use prefixes (e.g., Booleanquest1Complete, Booleanquest2Complete)

State Management Examples

• Initialize Variables: You can set default values in your startup script or at the beginning of each major chapter
• Track Events: Boolean flags can track significant story moments (e.g., BooleanmetMainVillain, BooleansavedVillage)
• Integer Variables for Counts: Integers can track quantities, scores, or multi-state systems
• Documentation: Some developers keep a list of all global variables and their purposes

Variable Limits

While there's no hard limit on variables, using hundreds of variables can make your project harder to manage. Group related state and reuse variables when possible.

Performance Optimization

Keep your stories running smoothly with these optimization techniques.

Node Graph Efficiency Examples

• Graph Size: Some developers keep individual scripts under 100 nodes for easier navigation
• Boolean Logic: Deep boolean logic chains can be broken into separate nodes if needed
• Script Depth: Scripts calling other scripts more than 3-4 levels deep may slow down (circular dependency limit is 20)
• Reusing Logic: You can create a shared script and call it with Run Script nodes instead of duplicating complex logic

Asset Management Examples

• Image Compression: Compressed PNG or JPG files can help reduce file sizes
• Image Dimensions: Background images up to 1920x1080 work well for HD displays
• Assets Per Script: Loading many unique images in one script can increase load times

Export Optimization Examples

• HTML Exports: You can remove unused images from the Content folder before exporting
• JSON Exports: You can clean up old or test scripts that won't be used in production
• Export Size: Large HTML exports (>50MB) may have slow load times in browsers

Testing & Debugging

Regular testing helps catch bugs early and ensures all story paths work correctly.

Using the Play Feature

• Testing Frequency: You can run your script after adding new branches or logic
• Testing Options: Click through dialogue options to verify connections work
• Variable Changes: The debug panel lets you verify variables update correctly
• Edge Cases: You can test unusual player behavior (skipping dialogue, revisiting areas)

Common Issues and Solutions

Dialogue option doesn't work

Check that the option has an outgoing connection with the correct source handle. Each dialogue option needs a connection from its specific handle to the next node.

Branch always takes same path

Verify the boolean input is connected and the variable is set correctly. Use the Runtime Debugger to check variable values in real-time.

Script doesn't load

Ensure the script file exists in the Content folder and has a .sfe extension. Check for typos in the script path configured in Run Script nodes.

Variables not changing

Check that Set Boolean and Set Integer nodes are connected to execution flow (primary handle), not just data flow (secondary handle).

Circular dependency error

Remove scripts calling themselves directly or indirectly more than 20 levels deep. Refactor your script structure to avoid infinite loops and use End nodes to properly terminate execution.

Debugging Workflow

1. Identify the Problem: Note exactly when and where the issue occurs
2. Check Connections: Verify all edges are connected to the correct handles
3. Trace Execution Flow: Follow the node path from Start to the problem point
4. Inspect Variables: Check if variables have expected values
5. Simplify: Temporarily remove complex logic to isolate the issue
6. Test Incrementally: Add back complexity piece by piece, testing after each change

Debugging Tip

Add comment nodes to mark potential problem areas. During testing, you can use dialogue nodes with debug messages like "DEBUG: Player health is [value]" to track state.

Version Control

Protect your work and enable collaboration with version control best practices.

Using Git

StoryFlow Editor projects work well with Git version control. Here are some common patterns:

• Committing: You can save progress after completing features or fixing bugs
• Commit Messages: Descriptive messages can help track changes (e.g., "Add merchant dialogue for Chapter 2")
• Branching: You can create Git branches for major story additions or experimental changes
• Build Files: Build outputs and temporary files can be added to .gitignore

Backup Examples

• Manual Backups: You can create manual backups before major changes
• Cloud Storage: Cloud services (Google Drive, Dropbox) can provide automatic backups
• Version Naming: If not using Git, you can append dates to backup folders (e.g., MyProject_2024-01-15)
• Testing Backups: Occasionally restore from a backup to verify it works

Collaboration Examples

• Dividing Work: Team members can work on different scripts to minimize conflicts
• Merging: Review changes when merging JSON files (scripts and variables)
• Changelogs: Some teams keep a changelog for major story updates
• Shared Variables: Communicate about global variables to avoid conflicts

Common Pitfalls

Avoid these common mistakes when building interactive stories.

Story Structure Issues

• Forgetting End Nodes: Every story path should reach an End node. Missing End nodes can cause the story to "hang" with no way to progress.
  • Fix: Add End nodes at the conclusion of each story branch
• Disconnected Dialogue Options: Dialogue options without outgoing connections won't work.
  • Fix: Ensure every option has a connection from its source handle
• Orphaned Nodes: Nodes that aren't connected to anything won't be executed.
  • Fix: Delete unused nodes or connect them to the main flow

Variable Mistakes

• Wrong Variable Type: Using a string variable where a boolean is expected.
  • Fix: Match variable types to node requirements (Boolean/Integer)
• Uninitialized Variables: Reading a variable before setting its value.
  • Fix: Set default values in your startup script or beginning of each scene
• Shadowing Global with Local: Creating a local variable with the same name as a global variable.
  • Fix: Use unique names for local variables to avoid confusion

Logic Errors

• Branch Without Input: Branch nodes need a boolean input to decide which path to take.
  • Fix: Connect a boolean value (from Get Boolean, comparison, or logic node) to the branch's input
• Data Flow vs Execution Flow: Connecting data outputs (secondary handles) to execution inputs won't work.
  • Fix: Use primary handles (colored differently) for execution flow
• Complex Boolean Chains: Long chains of And/Or/Not nodes can be confusing and error-prone.
  • Fix: Break complex logic into intermediate variables with Set nodes

Performance Problems

• Huge Single Scripts: Scripts with 200+ nodes become difficult to navigate and edit.
  • Fix: Split large scripts into smaller, focused modules using Run Script nodes
• Circular Script Calls: Scripts calling themselves indirectly can cause infinite loops (limit: 20 levels).
  • Fix: Refactor to avoid circular dependencies or use End nodes to terminate
• Unoptimized Images: Very large image files slow down loading and exports.
  • Fix: Compress images and use appropriate dimensions for your target platform

Still Stuck?

If you're experiencing issues not covered here, join our Discord community for help from the team and other users. Be sure to describe your issue in detail and share screenshots if possible!

Related Topics

→ Your First Project→ Variables→ Content Browser→ Play in Editor

← Previous: Game Engine Integration

Need Help?