How Hot Reload Works with FlowGraphObject in Play Mode

Hot reload with FlowGraphObject tracks runtime instances via a static registry, monitors asset timestamps every 200ms during play mode, and atomically swaps compiled FlowGraph instances without destroying the hosting GameObject.

The Ceres visual scripting framework enables iterative development through hot reload capabilities for FlowGraphObject instances during Unity play mode. When you modify a Flow Graph asset while the game is running, the runtime detects changes and updates active instances without restarting the scene. This mechanism relies on coordinated tracking between FlowGraphObjectBase runtime registration and the FlowGraphHotReloadManager editor system.

The Hot Reload Architecture

Two primary systems coordinate the hot reload workflow. FlowGraphObjectBase maintains a static registry of all active runtime instances and provides container resolution, while FlowGraphHotReloadManager handles editor-side change detection and orchestrates graph replacement.

Runtime Instance Tracking

When a Flow Graph Object first initializes, the IFlowGraphRuntime.Graph getter in FlowGraphObjectBase compiles the graph and registers the instance in the static RuntimeInstances list via RegisterInstance. This registration enables the system to locate specific objects during a reload event.

Container-Based Asset Monitoring

Each instance resolves its owning container through GetContainer, returning either a FlowGraphInstanceObject or the generated FlowGraphObject implementation. The container exposes a saveTimestamp property that FlowGraphHotReloadManager polls to detect modifications.

Step-by-Step Hot Reload Execution

The reload process follows a precise sequence to ensure thread safety and data integrity.

1. Timestamp Snapshot: When play mode starts and hot reload is enabled (FlowGraphHotReloadManager.IsHotReloadEnabled = true), RefreshContainerTimestamps records the current saveTimestamp of every container found via FlowGraphObjectBase.GetAllRuntimeInstances().

2. Periodic Polling: The OnUpdate callback executes approximately every 200ms while the editor is in play mode, throttled to prevent performance overhead.

3. Change Detection: CheckForChanges compares stored timestamps against current container values. When a mismatch occurs, the container enters a HashSet<IFlowGraphContainer> for processing.

4. Targeted Reload: ReloadContainer retrieves only the instances belonging to the changed container using FlowGraphObjectBase.GetRuntimeInstances(container), then invokes ReloadInstance for each.

5. Graph Replacement: ReloadInstance clones the latest FlowGraphData (preventing asset mutation), compiles a new FlowGraph, and swaps it via FlowGraphObjectBase.ReplaceGraph. Existing execution contexts continue on the old graph while new events utilize the fresh instance.

6. Cleanup: When a FlowGraphObject is destroyed, OnDestroy calls ReleaseGraph to unregister the instance from RuntimeInstances and dispose the current graph.

Enabling Hot Reload in Your Project

Activate hot reload functionality through the manager's static property before entering play mode.

// Enable automatic hot reload detection
Ceres.Editor.Graph.Flow.FlowGraphHotReloadManager.IsHotReloadEnabled = true;

Once enabled, the system monitors all FlowGraphObject instances automatically. No additional instrumentation of individual MonoBehaviour scripts is required.

Manual Refresh and Debugging

For batch edits or scenarios requiring immediate synchronization, bypass the 200ms polling interval by calling the refresh method directly.

// Force immediate timestamp check and reload
Ceres.Editor.Graph.Flow.FlowGraphHotReloadManager.RefreshContainerTimestamps();

This method updates the internal timestamp cache and triggers reloads for any containers modified since the last check.

Summary

• FlowGraphObjectBase maintains a static RuntimeInstances registry in Runtime/Flow/FlowGraphObject.cs that tracks every active Flow Graph Object in the scene.
• FlowGraphHotReloadManager in Editor/Flow/HotReload/FlowGraphHotReloadManager.cs polls container saveTimestamp values every 200ms during play mode to detect asset modifications.
• Changed containers trigger targeted reloads that clone FlowGraphData and compile new FlowGraph instances without disrupting running execution contexts.
• The ReplaceGraph method atomically swaps graph references while ReleaseGraph handles cleanup during object destruction.

Frequently Asked Questions

How do I enable hot reload for FlowGraphObject in play mode?

Set FlowGraphHotReloadManager.IsHotReloadEnabled to true before or during play mode. The manager automatically detects modified Flow Graph assets and updates running instances without requiring scene restarts.

What happens to running execution contexts during a hot reload?

Existing execution contexts continue running on the previous graph instance until completion. New events and trigger invocations utilize the freshly compiled graph after FlowGraphObjectBase.ReplaceGraph completes the swap.

Which containers support hot reloading?

Any container implementing IFlowGraphContainer with a valid saveTimestamp property supports hot reloading, including FlowGraphInstanceObject and generated FlowGraphObject implementations.

How can I manually trigger a reload without waiting for the automatic detection?

Invoke FlowGraphHotReloadManager.RefreshContainerTimestamps() to force an immediate timestamp comparison and reload cycle for all modified containers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}