Live Sync

Live Sync connects Unity to StoryFlow Editor via WebSocket. Request a sync to export your latest changes and update the imported Unity assets in one step.

Overview

Live Sync connects the Unity Editor to StoryFlow Editor on the same machine. Click Sync in StoryFlow Editor or Request Sync in Unity to export and import your latest changes. Saving a file alone does not send an update.

• Export and import project changes with one sync request
• WebSocket-based communication using ws://localhost:9000 by default
• Automatic re-import after a sync request, rewriting only the files whose source actually changed
• All ScriptableObject assets are updated in-place
• Per-file reporting in the log, so a file that could not be written is named instead of hidden behind a success message

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 you request a sync, StoryFlow Editor saves and exports the project, then sends a project-updated message containing the project path.
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. Existing ScriptableObject assets are updated in place, preserving references. Script changes can affect newly entered dialogue nodes during Play mode. The displayed line and shared runtime defaults do not refresh automatically.

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 your project in StoryFlow Editor, select WebSocket in the Export menu and click Start Server. 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 Tools > StoryFlow > Live Sync in the menu bar. This opens the Live Sync editor window where you can manage the connection. On plugin 1.2.1 and older this menu item sat in a top-level StoryFlow menu.

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 ask the editor for the current project at any time.

After each set of edits, click Sync in StoryFlow Editor or Request Sync in Unity. Wait for the import to finish before testing the updated assets.

// 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 StoryFlow Editor, select WebSocket in the Export menu and click Start Server.
2. Open your Unity project and navigate to Tools > 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 StoryFlow Editor. Edit dialogue, add nodes, change variables or modify characters.
6. Click Sync. This saves your edits, exports the project and sends a sync notification.
7. Switch back to Unity and wait for the import to finish.
8. Enter Play mode and test your changes immediately.

What a Sync Writes

A sync is incremental. Scripts, characters, Data Assets, translations and project data are updated when their source changes. Media is compared before anything is copied, so an unchanged image is not rewritten or reimported. Editing one line of dialogue leaves unrelated output alone.

Reading the Log

Every sync ends with a counted line in the Live Sync log. A clean run starts with Import complete: and carries the project title, its script, character and global variable counts, then the file counts in the form 3 written, 118 up to date, 0 failed. When a file could not be written the line starts with Import finished with and the failure count instead, carries the same counts, and is followed by one indented line per failed file naming the file and the likely cause.

A failure is never fatal to the sync: the importer skips that one file, carries on with the rest and retries it on the next sync. The Unity Console also carries a single error listing every file the run could not write. See Import Issues for what the causes mean and how to clear them.

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.

Data-Only Sync

When the StoryFlow Editor pushes a sync with Data Only enabled, it sends story graphs, variables, characters, Data Assets and localization data. Image and audio files are not copied into the Unity project. The importer reuses previously imported media when possible.

After a full sync imports your image and audio assets, Data Only lets you send further story changes without copying media files on every sync.

How to enable it:

1. Perform at least one full sync so the plugin has imported all media assets into your Unity project under the configured import path (default Assets/StoryFlow/).
2. In StoryFlow Editor's Export menu, select WebSocket and enable Data Only (Skip Assets). This setting applies to all connected clients.
3. Continue editing and request another sync when ready. Project data updates while media files stay untouched.

What happens on the Unity side:

• When the importer looks for a media source file and does not find it on disk, it checks whether the corresponding asset already exists at the expected path.
• If the asset exists, it is referenced in the script's resolved-assets map — no re-import, no warning.
• If the asset does not exist (you added a new image but haven't done a full sync yet), the importer logs a warning and skips that asset. Trigger a full sync to pick it up.

Troubleshooting

Connection Refused

If the Live Sync window reports a connection failure:

• Check the editor is running - StoryFlow Editor must be open with the project you want to sync.
• 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 the server is running - Select WebSocket in StoryFlow Editor's Export menu and click Start Server if it has not started.

No Updates After Syncing

Saving alone does not send an update. Click Sync or Request Sync. If Unity still does not receive the update:

• Verify the connection is active - The status indicator in the Live Sync window should be green. If it shows disconnected, click Connect again.
• Request another sync - Click Sync in StoryFlow Editor or Request Sync in Unity. Confirm that the import completes before testing.
• 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.
• Read the counts in the log - If the sync line reports failures, the assets it names are still stale on disk. Fix the cause (usually a checkout or a read-only file) and sync again.
• Force a full rewrite from the project asset - Request Sync is incremental and will skip an asset whose source has not changed, even when the asset itself is damaged. Select the Project asset in Assets/StoryFlow, open Actions > Re-Import from Source in the Inspector, set the Build Directory and click Re-Import. That is the one path that rewrites every asset and media file past the skip checks.