Installation
This guide walks you through installing the StoryFlow package in your Unity project.
Requirements
Before You Begin
- Unity 2022.3 LTS or later - The package targets Unity 2022.3+. Earlier versions are not supported.
- Newtonsoft.Json (
com.unity.nuget.newtonsoft-json) - Required for JSON parsing. Must be installed via the Package Manager if not already present (see Dependencies). - TextMeshPro (
com.unity.textmeshpro) - Required for the built-in dialogue UI. Must be installed via the Package Manager if not already present. - A StoryFlow Editor project - You will need at least one script file to test the plugin. You can sync your project to Unity using Live Sync or export it as JSON from the StoryFlow Editor.
The package supports all platforms that Unity 2022.3+ targets, including Windows, macOS, Linux, iOS, Android, and WebGL. No additional third-party libraries or native plugins are required.
Install the Plugin
Copy the StoryFlow plugin folder into your Unity project's Packages/ directory. This is the standard location for local Unity packages.
- Locate the StoryFlow plugin folder (the one containing
package.json,Runtime/, andEditor/). - Copy the entire folder into your Unity project's
Packages/directory. - Open
Packages/manifest.jsonin a text editor and add the following line to the top of the"dependencies"block:
"com.storyflow.unity": "file:storyflow-unity", - Switch back to Unity and wait for the package to be detected and imported.
your-unity-project/
├── Assets/
├── Packages/
│ └── storyflow-unity/ ← place the plugin here
│ ├── package.json
│ ├── Runtime/
│ │ ├── StoryFlow.Runtime.asmdef
│ │ ├── Core/
│ │ ├── Data/
│ │ ├── Execution/
│ │ ├── UI/
│ │ ├── Utilities/
│ │ ├── link.xml
│ │ └── ...
│ ├── Editor/
│ │ ├── StoryFlow.Editor.asmdef
│ │ ├── Import/
│ │ ├── LiveSync/
│ │ └── ...
│ └── Samples~/
│ ├── BasicDialogue/
│ ├── BranchingStory/
│ └── CustomUI/
├── ProjectSettings/
└── ...Do not rename internal folders
Do not rename the Runtime/, Editor/, or Samples~/ folders inside the plugin. The assembly definitions and editor scripts depend on these paths.
Package Structure
The plugin is organized into two assembly definitions, each serving a distinct role:
- Runtime/ - The gameplay assembly (
StoryFlow.Runtime.asmdef) that ships with your built game. ContainsStoryFlowComponent,StoryFlowManager, data assets, and the full node execution runtime. This assembly is included in all build targets. - Editor/ - An editor-only assembly (
StoryFlow.Editor.asmdef) used during development. Handles importing StoryFlow JSON projects, resolving media assets (images, audio), and providing the Live Sync WebSocket connection to the StoryFlow Editor. This assembly is never included in builds. - Samples~/ - Optional sample projects (BasicDialogue, BranchingStory, CustomUI). Copy any sample folder out of
Samples~/and into yourAssets/directory to use it. The~suffix tells Unity to ignore this folder during import.
Assembly References
If you need to reference StoryFlow types from your own assembly definitions, add StoryFlow.Runtime to your assembly's references. Never reference StoryFlow.Editor from runtime code, as it will cause build failures.
Dependencies
The plugin requires two packages to be installed in your project. Install them via Window > Package Manager if they are not already present:
- Newtonsoft.Json (
com.unity.nuget.newtonsoft-json≥ 3.2.1) - Used for JSON parsing during import and save/load. - TextMeshPro (
com.unity.textmeshpro≥ 3.0.6) - Used by the built-in default dialogue UI for text rendering.
If your project already uses either package, there is no conflict - Unity will use the existing installation.
IL2CPP and link.xml
The plugin includes a link.xml file in the Runtime/ directory that prevents the IL2CPP stripping process from removing types required for JSON deserialization at runtime. This ensures the plugin works correctly on all platforms, including iOS and WebGL, without any additional configuration.
Verify Installation
Once the plugin is imported, verify that everything is working correctly:
- Check for compilation errors: Open the Console window (Window > General > Console) and confirm there are no errors related to StoryFlow. If you see errors about missing
Newtonsoft.JsonorTextMeshPro, install the required dependencies. - Check the menu items: Look for StoryFlow in the Unity menu bar. You should see menu items such as StoryFlow > Import Project and StoryFlow > Live Sync.
- Try adding the component: Create or select a GameObject, click Add Component in the Inspector, and search for StoryFlowComponent. If it appears in the list, the runtime assembly is loaded correctly.
Automatic Project Discovery
The StoryFlowManager auto-creates itself at runtime and automatically discovers the StoryFlowProjectAsset in your project - no manual setup is required. The importer creates this asset at your chosen output path (default: Assets/StoryFlow). You do not need to add a StoryFlowManager to your scene or assign the project asset manually.
Ready to Go
Plugin installed and verified? Head over to the Quick Start guide to sync your first StoryFlow project and get dialogue running in your game.