Flowgraph States Manager

Overview

• File: extensions/flowgraph/states.lua

The States manager handles the flowgraph state machine system. It builds, starts, stops, and transitions between states defined in a state graph. States are subgraphs that run independently with their own extension proxies and hooks.

Exports

Returns a constructor function function(mgr) that creates a new States instance bound to a flowgraph manager.

Key Methods

Internals

State Structure

Each state contains:

{
  id = nodeId,           -- unique state ID (from the state node)
  depth = {...},         -- graph depth path for group-state nesting
  graph = targetGraph,   -- the subgraph this state executes
  name = "StateName",
  autoStart = bool,      -- whether to start automatically
  extProxy = proxy,      -- extension proxy for hook isolation
  active = bool,         -- current running status
  ports = {},            -- transition ports (name → {targets, stopDepth})
  transitionStack = {},  -- accumulated data passed through transitions
}

Build Pipeline

1. gatherNodesAndLinks() - Recursively collects all nodes and links from the state graph hierarchy into flat lists.
2. resolveInterHops() - Flattens connections through group-state connectors (entry/exit nodes) into direct "virtual links".
3. buildPortsAndStarts() - Assigns transition ports to each state node and identifies auto-start states.
4. addStateFromPortedNode() - Creates runtime state objects with extension proxies.

Transition Resolution

Transitions are queued during execution and resolved at frame end via a dedicated extension proxy:

1. All queued transitions are processed to determine which states turn on/off.
2. States exiting group-states trigger all nested states to stop.
3. Off-states are stopped first (sorted by ID), then on-states are started.
4. If a final exit node is reached with no new states starting, the project stops.
5. Transition data is accumulated in each state's transitionStack.

How It Works

1. The flowgraph manager calls buildStates() when a state graph project starts.
2. States are built from the state graph's node/link structure, flattening group-state hierarchies.
3. Each state gets its own extensionProxy for isolated hook management.
4. A resolver extension proxy runs every frame to process queued transitions.
5. State transitions are triggered by nodes calling states:transition(sourceId, name, data).
6. The resolver stops source states and starts target states atomically at frame end.

Usage Example

-- States are managed internally by the flowgraph system.
-- Nodes trigger transitions like:
self.mgr.states:transition(stateId, "success", {score = 100})

-- Checking if a state is running:
if self.mgr.states:isRunning(someStateId) then
  -- state is active
end

-- Getting accumulated transition data:
local stack = self.mgr.states:getTransitionStack(stateId)
local score = stack.score

Key Dependencies

• core_flowgraphManager - proxy registration and dependency management
• newExtensionProxy() - creates isolated extension hook proxies
• extensions.refresh() - refreshes hook routing after proxy changes

See Also

• Flowgraph Base Module - Related reference
• Flowgraph Base State Node - Related reference
• Flowgraph Base Node - Related reference
• FlowGraph Guide - Guide