packages/tools/flowGraphEditor/MANUAL.md
When updating the manual you must update the HelpTopics array in helpContent.ts to reflect the changes.
The Flow Graph Editor is a visual tool for building, debugging, and testing Babylon.js Flow Graphs. It provides a node-based interface where you wire together execution blocks (driven by signals) and data blocks (computing values) to define interactive behaviors.
When the editor opens without a Playground snippet, a default scene is automatically created with:
This lets you start building and testing flow graph logic immediately. The default scene is replaced when you load a Playground snippet or drop a scene file.
You can drag and drop a .glb, .gltf, or .babylon file onto the Scene Preview pane to load it as the test scene. For .gltf files that reference separate .bin or texture files, drop all files together.
The loaded scene replaces the current scene (default or snippet) and populates the scene context with all objects found in the file.
The editor can load a Babylon.js Playground snippet as a live scene to test your flow graph against.
ABC123), a versioned ID (ABC123#5), or a full Playground URL.The loaded scene's objects (meshes, lights, cameras, etc.) become available as references in flow graph block configuration fields.
flowGraph.json file to your machine.Click the </> button in the toolbar to open the How to Use dialog. It shows copy-to-clipboard code samples for integrating your flow graph into a project:
https://snippet.babylonjs.com/<snippetId>, parse the payload, then call ParseFlowGraphAsync(data, { coordinator }) from @babylonjs/core/FlowGraph/flowGraphParser..json file and call ParseFlowGraphAsync(data, { coordinator }) from @babylonjs/core/FlowGraph/flowGraphParser.Each code sample includes the necessary import statements and is ready to paste into your project.
The Variables section in the property panel (right sidebar, when no block is selected) lists all variables referenced by GetVariable and SetVariable blocks in the graph.
Each variable row shows:
2G / 1S means 2 GetVariable blocks and 1 SetVariable block reference it)Click + Add to create a new variable with an auto-generated name. The variable is registered on context 0 with an undefined default value.
Double-click a variable name to edit it. Press Enter to confirm or Escape to cancel. Renaming propagates to all GetVariable and SetVariable blocks that reference the old name, and also updates the variable in all execution contexts.
Click the ✕ button on a variable row to delete it. This removes all GetVariable and SetVariable blocks that reference the variable, and removes the variable from all execution contexts.
Importing a glTF with an interactive flow graph:
.glb or .gltf file onto the scene preview pane.Loading a glTF graph without a scene:
.glb/.gltf file (no scene is loaded).Exporting:
.glb containing only the flow graph data is created.The palette contains a Templates section with pre-built multi-block patterns:
Drag a template from the palette onto the canvas. All blocks are created and internally wired automatically. You can then edit individual blocks (change targets, configure conditions, etc.).
The toolbar at the top provides editing and execution controls:
The Undo (↩) and Redo (↪) buttons are at the left side of the toolbar. They are disabled when there is nothing to undo or redo. You can also use Ctrl+Z / Cmd+Z to undo and Ctrl+Shift+Z / Cmd+Shift+Z to redo.
| Button | Label | Description |
|---|---|---|
| ▶ | Start | Starts executing the flow graph. Enabled when the graph is stopped or paused. |
| ⏸ | Pause | Pauses execution. The graph can be resumed with Start. |
| ⏹ | Stop | Stops execution and resets execution state. |
| ↺ | Reset | Stops execution and reloads the scene from its snippet (if one was loaded). If the reload fails, an error is logged and the graph returns to the Stopped state. |
The state indicator next to the controls shows the current graph state: Stopped, Running, Paused, or Breakpoint.
The Speed buttons in the toolbar let you slow down or speed up scene execution:
| Button | Effect |
|---|---|
| 0.1× | 10% speed — near frame-by-frame, useful for watching individual block executions |
| 0.25× | 25% speed — slow motion |
| 0.5× | 50% speed — half speed |
| 1× | Normal speed (default) |
| 2× | Double speed — fast forward |
The time scale affects everything: scene animations, FlowGraph delta time, interpolation blocks, async waits, and timer-based logic. The active speed button is highlighted in orange. The selected speed persists when the scene is reloaded via Reset.
A FlowGraph can have multiple execution contexts, each representing an independent execution of the same graph logic with its own variable state. This enables patterns like running the same "click to animate" behavior on 10 different meshes, each with its own score, health, or animation state.
The Ctx dropdown in the toolbar shows all execution contexts. By default, there is one context ("Context 0") created when the graph starts.
| Control | Description |
|---|---|
| Ctx dropdown | Select which context is active — debug highlighting, breakpoints, and the Variables panel reflect the selected context. |
| + | Create a new execution context. Each new context starts with independent variable state. |
| − | Remove the selected context. Disabled when only one context remains. |
| ✎ | Rename the selected context. Press Enter to confirm, Escape to cancel. |
Per-context variables: Each context maintains its own set of user variables. When you switch contexts, the Variables panel shows the values for the selected context. Adding a variable via the Variables panel sets it on the currently selected context.
Serialization: Context names and per-context variables are preserved when saving and loading flow graphs.
Debug Mode enables real-time visualization of graph execution so you can see what's happening as your graph runs.
Click the Debug toggle button (magnifying glass icon) in the toolbar. The button is highlighted when debug mode is active.
When enabled, you'll see:
Debug mode adds some overhead. It throttles visual updates to 100ms per node to keep the editor responsive.
Debug mode also enables breakpoints — you can pause execution at a specific block and step through the graph one block at a time.
Breakpoints let you pause graph execution just before a specific execution block runs, so you can inspect state and step through logic.
A red dot appears on the left side of the block header when a breakpoint is active.
When execution reaches a block with a breakpoint, the graph pauses immediately before that block executes. You'll see:
| Button | Label | Description |
|---|---|---|
| ▶▶ | Continue | Resumes normal execution from the breakpoint. The graph runs until the next breakpoint (or completion). |
| ▶| | Step | Executes only the current block, then pauses again at the next execution block. |
Debug blocks are passthrough data blocks that let you inspect values flowing through your graph at runtime.
The debug block is a pure passthrough — it doesn't modify the data, so it's safe to insert anywhere in a data chain.
?.| Type | Display Format |
|---|---|
| Number (float) | 4 decimal places |
| Number (integer) | As-is |
| Boolean | true / false |
| String | Quoted string |
| Vector2 | (x, y) — 3 decimals |
| Vector3 | (x, y, z) — 3 decimals |
| Vector4 | (x, y, z, w) — 3 decimals |
| Color3 | (r, g, b) — 3 decimals |
| Color4 | (r, g, b, a) — 3 decimals |
| Object | JSON (truncated to 64 chars) |
| Null/Undefined | null / undefined |
Debug blocks can only be connected to data ports, not signal ports.
The editor can validate your graph for configuration errors and structural issues.
Click the Validate button (✓) in the toolbar. The button shows a count of errors and warnings found. Click it again to log individual issues to the console (up to 20 at a time). Clicking an issue navigates to the relevant block in the graph.
Click the Live Validation toggle (⚡) to enable automatic validation whenever the graph changes. Validation runs on a debounced schedule so it doesn't slow down editing.
Validation issues include the block name, severity (error/warning), and a descriptive message.
The editor enforces data type compatibility when connecting ports. Each data port has a rich type (e.g., Number, Vector3, Boolean) shown by its color. When dragging a connection:
If you release the mouse on an incompatible port, an error dialog explains the type mismatch (e.g., "Type mismatch: cannot connect Vector3 to number").
Compatibility rules:
| Source type | Accepted by |
|---|---|
| Any | All types (wildcard) |
| Same type | Always compatible |
| Number ↔ Integer | Interchangeable |
| Vector3, Vector4, Matrix → Quaternion | Accepted via type transformer |
Signal ports (execution flow) have no type restrictions — any signal output can connect to any signal input.
| Key | Action |
|---|---|
| Delete / Backspace | Delete selected blocks (removes from graph) |
| Alt+Delete / Alt+Backspace | Delete and auto-reconnect surrounding nodes |
| Ctrl+Z / Cmd+Z | Undo |
| Ctrl+Shift+Z / Cmd+Shift+Z | Redo |
| Ctrl+A / Cmd+A | Select all nodes and frames |
| Ctrl+C / Cmd+C | Copy selected blocks (or frames) |
| Ctrl+V / Cmd+V | Paste copied blocks at cursor position |
| Ctrl+G / Cmd+G | Create a smart group from selected blocks |
| F9 | Toggle breakpoint on selected execution block |
| Ctrl+M / Cmd+M | Create a sticky note at cursor position |
| Ctrl+F / Cmd+F | Find in graph (search nodes/frames) |
| Enter (in scene preview input) | Load the Playground snippet |
Select one or more blocks and press Ctrl+C (or Cmd+C on macOS) to copy them. Press Ctrl+V (or Cmd+V) to paste copies at the cursor position.
You can also copy and paste entire frames (groups) — select a frame and use Ctrl+C/V to duplicate it along with all its contained blocks.
Smart groups let you bundle multiple blocks into a collapsed frame with automatically exposed input/output ports, creating a reusable visual unit.
The editor analyzes the selected blocks and creates a collapsed frame with exposed boundary ports.
If your selection contains exactly one execution block plus any number of data blocks:
This is the most common case — e.g., a "Set Variable" block with a few constant/math blocks feeding its inputs.
If the selection contains multiple execution blocks, all signal ports that cross the group boundary (or are unconnected) are exposed. You can then expand the frame and refine which ports are exposed by toggling them in the frame port settings.
Deleting a frame (selecting the frame and pressing Delete) removes only the frame, not the blocks inside it. This is the "ungroup" operation — the blocks remain on the canvas with their connections intact. To delete the frame and its contents, expand the frame first, select all blocks inside, then delete them.
Select the frame and press Ctrl+C / Cmd+C, then Ctrl+V / Cmd+V to paste a copy. The copy includes all blocks, their internal connections, and the frame's collapse/port exposure state.
Sticky notes are free-floating annotations you can place anywhere on the canvas to document sections of your graph.
Press Ctrl+M (or Cmd+M on macOS) to create a new sticky note at the current cursor position.
Click a note to select it. Selected notes have a highlighted border. Press Delete or Backspace to remove selected notes. Multi-select with Ctrl+click or Shift+click.
Sticky notes are saved with the graph and restored on load. They also appear as yellow rectangles on the minimap.
Search for nodes and frames in the current graph by name or block type.
Press Ctrl+F (or Cmd+F on macOS) to open the search bar in the top-right corner of the canvas.
Type a query to filter. Matches include:
All matching items are outlined in yellow. The current match is highlighted in blue and the viewport pans to center on it.
Press Escape or click the X button to close the search bar. All highlights are removed.
The editor includes a set of blocks for interacting with the Babylon.js Physics V2 system. These blocks operate on PhysicsBody references, which can be obtained from mesh objects that have physics enabled (e.g., via PhysicsAggregate).
| Block | Description |
|---|---|
| PhysicsCollisionEvent | Fires whenever a collision occurs on the specified physics body. Outputs the other body, contact point, normal, impulse, and penetration distance. |
| Block | Description |
|---|---|
| ApplyForce | Applies a continuous force to a body at a world-space location. Use in a per-frame loop for sustained forces. |
| ApplyImpulse | Applies an instantaneous impulse (velocity change) to a body at a world-space location. |
| SetLinearVelocity | Directly sets the linear velocity vector of a body. |
| SetAngularVelocity | Directly sets the angular velocity vector of a body. |
| SetPhysicsMotionType | Changes the body's motion type: 0 = STATIC, 1 = ANIMATED, 2 = DYNAMIC. |
| Block | Description |
|---|---|
| GetLinearVelocity | Reads the current linear velocity of a physics body. |
| GetAngularVelocity | Reads the current angular velocity of a physics body. |
| GetPhysicsMassProperties | Reads the mass, center of mass, and inertia of a physics body. |
Note: Physics blocks require a scene with Physics V2 enabled and bodies attached to meshes. Without a physics engine loaded, the blocks will report errors at runtime.
The editor includes blocks for controlling audio playback using the Babylon.js Audio V2 system. These blocks operate on AbstractSound references (either StaticSound or StreamingSound instances created via CreateSoundAsync / CreateStreamingSoundAsync).
| Block | Description |
|---|---|
| PlaySound | Plays the sound with configurable volume, start offset, and loop options. |
| StopSound | Stops the sound immediately. |
| PauseSound | Pauses the sound if playing, or resumes it if paused. |
| SetSoundVolume | Sets the volume (0–1) of the sound. |
| Block | Description |
|---|---|
| SoundEndedEvent | Fires when the sound finishes playing (does not fire if loop is enabled). |
| Block | Description |
|---|---|
| GetSoundVolume | Reads the current volume of a sound. |
| IsSoundPlaying | Returns true if the sound is currently playing or starting. |
Note: Audio blocks require sounds created via the Audio V2 API (
CreateSoundAsync,CreateStreamingSoundAsync). The legacySoundclass (V1) is not supported by these blocks.
Right-click on the canvas, a node, a link, or a frame to open a context menu with relevant actions. The menu items change depending on what was clicked.
| Action | Shortcut | Description |
|---|---|---|
| Add Block... | Space | Opens the block search box to add a new block |
| Paste | Ctrl+V | Pastes previously copied blocks |
| Create Sticky Note | Ctrl+M | Adds a sticky note at the click position |
| Select All | Ctrl+A | Selects all nodes and frames |
| Zoom to Fit | — | Zooms to fit the entire graph |
| Reorganize | — | Auto-layouts the graph |
| Action | Shortcut | Description |
|---|---|---|
| Delete | Del | Deletes the selected node(s) |
| Duplicate | Ctrl+C/V | Copies and pastes the selected node(s) |
| Add/Remove Breakpoint | F9 | Toggles a breakpoint (single execution block only) |
| Create Smart Group | Ctrl+G | Groups 2+ selected blocks into a frame (when applicable) |
| Disconnect All Ports | — | Disconnects all input and output ports from the selection |
| Action | Shortcut | Description |
|---|---|---|
| Delete Connection | Del | Removes the selected connection line |
| Action | Shortcut | Description |
|---|---|---|
| Delete Frame | Del | Removes the frame (keeps contained blocks) |
| Collapse/Expand | — | Toggles the frame between collapsed and expanded states |
Hover over any port icon (the colored dot or shape on a node) to see a tooltip showing:
Signal ports (execution flow) show "Signal Input" or "Signal Output".
Brief notifications appear in the bottom-right corner of the editor for key operations. Toasts auto-dismiss after 4 seconds and can be closed early by clicking the ✕ button.
| Event | Severity | Message |
|---|---|---|
| File load success | Success | "Flow graph loaded from file" |
| File save | Success | "Flow graph saved to file" |
| Snippet save | Success | "Graph saved — ID: ... (copied to clipboard)" |
| Snippet load success | Success | "Flow graph loaded from snippet ..." |
| Snippet save/load failure | Error | Error description |
| Disconnect all ports | Info | "Disconnected all ports" |
All toast messages are also logged to the Log panel for reference.
Select a block on the canvas to view and edit its properties in the right-hand panel. The panel has up to four sections:
Name, type, and comments for the selected block.
Shows constructor configuration fields that control how the block is created. These vary by block type. Examples:
| Block | Fields |
|---|---|
| Math blocks (Add, Subtract, …) | Type, Matrix per component, Prevent int/float arithmetic |
| Interpolation | Key frames count, Animation type |
| Custom event (Send/Receive) | Event ID |
| ForLoop | Initial index, Increment when done |
| DoN | Start index |
| Bitwise blocks | Value type |
| GetProperty | Reset to default when undefined |
| Pointer/Pick events | Stop propagation |
Note: Some construction variables (like key frames count) control the block's port structure. Changing them updates the saved config but may require re-creating the block for new ports to appear.
Editable default values for unconnected data-input ports. The following types are supported automatically: number, boolean, string, FlowGraphInteger, Vector2, Vector3, Vector4, Color3, Color4, and Matrix. Connected inputs are displayed as read-only.
Additional properties registered with the editableInPropertyPage decorator on the block class.
Some blocks have dedicated property panels that replace the generic panel with richer editing controls:
| Block(s) | Special Section | Description |
|---|---|---|
| GetAsset | Asset Configuration | Type dropdown + named asset picker from the loaded scene. |
| Pointer Down/Up/Move/Over/Out, MeshPick | Target Mesh | Mesh dropdown picker from the loaded scene. Filters which mesh triggers the event. |
| PlayAnimation | Animation Group | AnimationGroup dropdown from the loaded scene. Sets the default animation group to play. |
| Constant | Constant Value | Type selector (Number, Integer, Boolean, String, Vector2/3, Color3/4, Matrix) + matching value editor. Changing the type updates the output port's rich type. |
| Switch | Cases | Dynamic list of numeric case values with add/remove buttons. Each case creates a signal output. |
| DataSwitch | Cases | Numeric case list like Switch; also shows the treatCasesAsIntegers toggle. Each case creates a data input. |
| SetVariable (multi mode) | Variables | Dynamic list of variable names with add/remove. Each variable creates a data input. |
| Send/Receive Custom Event | Event Data Inputs/Outputs | Key-type list editor. Add entries by name + FlowGraph-type dropdown. Each entry creates a data input (Send) or output (Receive). |
Scene-dependent pickers: The mesh and animation-group pickers require a scene to be loaded in the Preview panel. Without a loaded scene, an info message is shown instead.