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., Integer playerHealth , Boolean hasMetMerchant )
• 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

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

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:

Variable Naming Examples

• Boolean Flags: You can prefix with "has", "is", or "can" (e.g., Boolean hasKey , Boolean isQuestComplete , Boolean canEnterCastle )
• Counters: Descriptive names (e.g., Integer enemiesDefeated , Integer goldAmount , Integer conversationCount )
• Abbreviations: Integer playerHealth compared to Integer plrHP
• Grouping by Prefix: Related variables can use prefixes (e.g., Boolean quest1Complete , Boolean quest2Complete )

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., Boolean metMainVillain , Boolean savedVillage )
• 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

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

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

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