Installation

This guide walks you through installing the StoryFlow plugin in your Godot 4 project.

Requirements

The plugin is pure GDScript and works on all platforms that Godot 4.3+ targets. No additional libraries, SDKs, or GDExtension builds are required.

Install the Plugin

Copy the addons/storyflow/ folder into your Godot project's addons/ directory. If the addons/ directory does not exist yet, create it at the root of your project alongside the project.godot file.

your-project/
├── addons/
│   └── storyflow/              ← place the plugin here
│       ├── core/               (runtime GDScript files)
│       ├── editor/             (import dock, importer, WebSocket sync)
│       ├── icons/              (plugin icon)
│       ├── ui/                 (default dialogue UI scene + scripts)
│       ├── plugin.cfg
│       └── storyflow_plugin.gd
├── scenes/
├── scripts/
└── project.godot

Plugin Structure

The plugin is organized into distinct folders, each serving a specific role:

• core/ - The runtime module that ships with your exported game. Contains StoryFlowManager (autoload singleton), StoryFlowComponent (the node you add to scenes), data resource classes, and the full node execution runtime. All files in this folder are needed at runtime.
• editor/ - Editor-only tools used during development. Handles importing StoryFlow JSON projects, resolving media assets (images, audio), providing the editor dock UI, and the Live Sync WebSocket connection to the StoryFlow Editor. This folder is not needed in exported builds.
• ui/ - A default dialogue UI scene (.tscn) with its accompanying GDScript. You can use this out of the box, customize it, or ignore it entirely and build your own UI.
• icons/ - The plugin icon displayed in the Godot editor's plugin list.
• plugin.cfg - The plugin configuration file that tells Godot about the plugin's name, version, and entry script.
• storyflow_plugin.gd - The plugin's entry point script that registers the autoload, import plugin, and editor dock when the plugin is enabled.

Enable the Plugin

After copying the plugin files into your project, you need to enable it through the Godot editor:

1. Open your project in the Godot editor.
2. Go to Project > Project Settings.
3. Click the Plugins tab at the top of the window.
4. Find StoryFlow in the plugin list.
5. Check the Enable checkbox next to it.

The plugin activates immediately - no editor restart is required.

What Happens on Enable

When you enable the StoryFlow plugin, three things happen automatically:

• StoryFlowRuntime autoload is registered - A singleton named StoryFlowRuntime is added to your project's autoload list. This is the central manager that holds the project data, global variables, runtime character copies, and save/load functionality. You can access it from any script via StoryFlowRuntime.
• StoryFlow import plugin is registered - A custom import plugin is registered that handles .storyflow project files. This allows Godot to recognize and process StoryFlow project files when they are placed in your project.
• StoryFlow editor dock is created - A dock panel appears in the editor that provides tools for importing StoryFlow projects, configuring import settings, and managing the Live Sync connection.

Verify Installation

Once the plugin is enabled, verify that everything is working correctly:

1. Check the Autoload list: Go to Project > Project Settings > Autoload and confirm that StoryFlowRuntime appears in the list and is enabled.
2. Check the editor dock: Look for the StoryFlow dock panel in the editor. It should appear in the bottom panel or as a side dock, depending on your editor layout. This dock provides the import UI and Live Sync controls.
3. Check node availability: Create a new scene, click Add Child Node, and search for "StoryFlowComponent". It should appear in the node list, ready to be added to your scene tree.

To further verify the plugin from GDScript, you can add a quick test in any script:

func _ready():
    # Verify StoryFlowRuntime autoload is accessible
    if StoryFlowRuntime.has_project():
        print("StoryFlow project loaded: ", StoryFlowRuntime.get_project())
    else:
        print("StoryFlow plugin active, no project loaded yet")