Live Sync

Live Sync connects Unity to the StoryFlow Editor via WebSocket, letting you edit your project and see changes reflected in Unity in real time - no manual re-export and re-import after every change.

Overview

Live Sync establishes a WebSocket connection between the Unity Editor and the StoryFlow Editor running on the same machine. When you save changes in the StoryFlow Editor, those changes are automatically pushed to Unity and re-imported, keeping your in-engine project data up to date without any manual steps.

• Real-time synchronization - edit in StoryFlow, see results in Unity immediately
• WebSocket-based communication using ws://localhost:9000 by default
• Automatic re-import of the full project when changes are detected
• All ScriptableObject assets are updated in-place

How It Works

The synchronization process follows a simple sequence:

1. StoryFlow Editor opens a WebSocket server on a configurable port (default: 9000). This server listens for incoming connections from game engine clients.
2. The Unity Live Sync window connects as a WebSocket client. On connection, it sends a handshake message identifying itself as a Unity client with the current plugin version and Unity version.
3. When the editor saves or exports, it sends a project-updated message over the WebSocket. This message includes the project path so Unity knows where the exported files are located.
4. Unity reads from the build directory at {projectPath}/build/ and runs the StoryFlowImporter automatically. This converts all JSON files into Unity ScriptableObject assets.
5. All ScriptableObject assets are updated in-place, preserving existing references. Active StoryFlowComponent instances can pick up the updated project asset immediately.

Setting Up

Getting Live Sync running takes just a few steps. Make sure both the StoryFlow Editor and Unity Editor are open on the same machine.

Step 1: Enable WebSocket Sync in StoryFlow Editor

Open the StoryFlow Editor and go to Settings. Enable WebSocket Sync. The default port is 9000. Change this only if the port is already in use on your machine.

Step 2: Open Live Sync in Unity

In Unity, go to StoryFlow > Live Sync in the menu bar. This opens the Live Sync editor window where you can manage the connection.

Connecting

The Live Sync window provides a straightforward interface for managing the WebSocket connection:

1. Enter the Port (default: 9000). This must match the StoryFlow Editor's WebSocket settings. The host is fixed to localhost.
2. Click Connect. The status indicator changes to show the current connection state.
3. Once connected, the window displays a green Connected status.
4. Click Request Sync to force a full re-import of the project at any time.

From this point on, any changes you save in the StoryFlow Editor are automatically pushed to Unity. You do not need to click Request Sync again unless you want to force a full refresh.

// You can also connect programmatically from an editor script
// by accessing the Live Sync window, though the window UI is
// the recommended approach for most workflows.

Workflow

A typical Live Sync development session looks like this:

1. Open your project in the StoryFlow Editor.
2. Open your Unity project and navigate to StoryFlow > Live Sync.
3. Click Connect and verify the status shows Connected.
4. Click Request Sync to do an initial import and ensure Unity has the latest data.
5. Switch to the StoryFlow Editor. Edit dialogue, add nodes, change variables, or modify characters.
6. Save your project in the editor (Ctrl+S / Cmd+S). The editor exports and sends a sync notification.
7. Switch back to Unity. Your project asset, script assets, and character data have already been updated.
8. Enter Play mode and test your changes immediately.

Configuration

The Live Sync window exposes the following settings:

These settings are stored in the Live Sync window instance. You may need to re-enter them if the window is closed and reopened.

Troubleshooting

Connection Refused

If the Live Sync window reports a connection failure:

• Check the editor is running - The StoryFlow Editor must be open with a project loaded. The WebSocket server only starts when a project is open.
• Check the port matches - Verify that the port in the Live Sync window matches the port in the StoryFlow Editor's WebSocket Sync settings. Both default to 9000.
• Check firewall settings - If you are running on a machine with a firewall, ensure it allows local connections on the configured port. Most firewalls allow localhost traffic by default.
• Check WebSocket Sync is enabled - In the StoryFlow Editor, go to Settings and confirm that WebSocket Sync is toggled on.

No Updates After Saving

If you save in the editor but Unity does not receive updates:

• Verify the connection is active - The status indicator in the Live Sync window should be green. If it shows disconnected, click Connect again.
• Save the project - The sync is triggered by saving. Simply editing nodes without saving will not push an update.
• Check the log panel - The Live Sync window has a log that shows all incoming messages. If no project-updated messages appear, the editor may not be sending sync notifications.

Assets Not Updating

If the import runs but existing assets do not reflect the latest changes:

• Verify the Output Path exists - The Output Path in the Live Sync window must point to a valid folder under your Assets directory. If the folder does not exist, the importer will create it, but ensure the parent directory is correct.
• Check the Unity Console - Look for [StoryFlow] prefixed messages in the Console window. Import errors and warnings are logged there.
• Try a manual Request Sync - Click the Request Sync button to force a full re-import. This re-reads all files from the build directory.