Let a behavior be a node in another graph

A behavior that has a Start and an End node can now be dropped into any
other graph as a node of its own. What is declared on the start node
becomes the inputs of that node, what hangs on the end node its outputs;
the port list is derived from the sub graph, not copied, so declaring a
port in one graph grows the node in the other without touching it. The
node carries the behavior's name and the palette lists behaviors by
name, so a call is one grab instead of a node plus a dropdown.

An embedded behavior has no object and therefore no place for
variables: every call starts on the asset defaults and communicates
only through its ports. That is the conservative direction - state can
still be added later, and shared state already has a home in a behavior
object in the scene. Node ids are unique per graph only, so each call
gets its own pulse cache; without that, two graphs would collide.

Renaming a port used to silently drop the value typed on the calling
node. It is carried along now, project wide, like the edges.

src/core/graph/Graph.ts

@@ -18,6 +18,24 @@ export interface GraphNode {
   x: number;
   y: number;
   params: PropertyBag;
+  /**
+   * Ports the node declares itself, on top of the fixed ones of its type. Only the behavior
+   * start/end nodes carry this – they are what gives a nested behavior its signature.
+   */
+  ports?: DeclaredPort[];
+}
+
+/** A port a start/end node declares. `kind` maps to the PortType of the same name (`text` → string). */
+export interface DeclaredPort {
+  key: string;
+  kind: DeclaredPortKind;
+}
+
+export const DECLARED_PORT_KINDS = ['number', 'boolean', 'text', 'object'] as const;
+export type DeclaredPortKind = (typeof DECLARED_PORT_KINDS)[number];
+
+export function declaredPortType(kind: DeclaredPortKind): PortType {
+  return kind === 'text' ? 'string' : kind;
 }
 
 export interface GraphEdge {

src/core/graph/GraphInterpreter.ts

@@ -1,6 +1,14 @@
 import { edgesInto, edgesOutOf, type Graph, type GraphNode } from './Graph';
+import {
+  BEHAVIOR_END,
+  BEHAVIOR_START,
+  type BehaviorLookup,
+  NO_BEHAVIORS,
+  resolveDef,
+  terminalNode,
+} from './nested';
 import type { NodeContext } from './NodeContext';
-import { hasExecInput, inlineValue, isEventNode, type RepeatResult, requireNodeDef } from './NodeRegistry';
+import { type CallResult, hasExecInput, inlineValue, isEventNode, type RepeatResult } from './NodeRegistry';
 import type { Value } from './values';
 
 /** How much work one pulse may do. A Repeat over a 10×20 board is 200 rounds, so this is generous. */
@@ -18,6 +26,17 @@ export interface TraceListener {
   onNode(nodeId: string): void;
 }
 
+/** One graph's pulse state. A nested behavior runs in its own – node ids are unique per graph only. */
+interface Frame {
+  graph: Graph;
+  outputCache: Map<string, Record<string, Value>>;
+  dataCache: Map<string, Record<string, Value>>;
+}
+
+function emptyFrame(graph: Graph): Frame {
+  return { graph, outputCache: new Map(), dataCache: new Map() };
+}
+
 /**
  * Runs one behavior graph for one instance. An event node starts a *pulse*; the interpreter follows
  * exec edges and pulls data inputs from the connected output, evaluating pure data nodes lazily and
@@ -26,13 +45,19 @@ export interface TraceListener {
 export class GraphInterpreter {
   /** Per-node state that persists across pulses (timer accumulators etc.). */
   readonly nodeState = new Map<string, Record<string, number>>();
-  private outputCache = new Map<string, Record<string, Value>>();
-  /** Kept apart from `outputCache` because a loop round has to forget exactly these again. */
-  private dataCache = new Map<string, Record<string, Value>>();
+  /** Assets run as a node so far – the graph editor highlights them from this instance's trace. */
+  readonly calledBehaviors = new Set<string>();
+  private frame: Frame;
+  private callStack: string[] = [];
   private steps = 0;
   trace: TraceListener | null = null;
 
-  constructor(readonly graph: Graph) {}
+  constructor(
+    readonly graph: Graph,
+    private readonly behaviors: BehaviorLookup = NO_BEHAVIORS,
+  ) {
+    this.frame = emptyFrame(graph);
+  }
 
   eventNodes(type: string): GraphNode[] {
     return this.graph.nodes.filter((n) => n.type === type);
@@ -48,10 +73,10 @@ export class GraphInterpreter {
     let fired = 0;
     for (const node of this.eventNodes(type)) {
       if (filter && !filter(node)) continue;
-      this.outputCache = new Map();
-      this.dataCache = new Map();
+      this.frame = emptyFrame(this.graph);
+      this.callStack = [];
       this.steps = 0;
-      this.outputCache.set(node.id, { ...outputs });
+      this.frame.outputCache.set(node.id, { ...outputs });
       this.trace?.onNode(node.id);
       this.follow(node, 'exec', ctx, 0);
       fired++;
@@ -60,7 +85,7 @@ export class GraphInterpreter {
   }
 
   private follow(node: GraphNode, port: string, ctx: NodeContext, depth: number): void {
-    for (const edge of edgesOutOf(this.graph, node.id, port)) {
+    for (const edge of edgesOutOf(this.frame.graph, node.id, port)) {
       const target = this.node(edge.to.node);
       if (!target) continue;
       this.trace?.onEdge(edge.id);
@@ -73,41 +98,68 @@ export class GraphInterpreter {
       throw new Error('Behavior graph exceeded the step limit (endless loop?)');
     if (depth > MAX_DEPTH)
       throw new Error('Behavior graph nested too deeply (a flow feeding back on itself?)');
-    const def = requireNodeDef(node.type);
-    if (!def.run) return;
+    const def = this.def(node);
+    if (!def?.run) return;
     const inputs = this.collectInputs(node, ctx);
     const result = def.run(ctx, inputs, node.params);
-    this.outputCache.set(node.id, result.outputs ?? {});
+    const returned = result.call ? this.call(result.call, ctx, depth) : {};
+    this.frame.outputCache.set(node.id, { ...result.outputs, ...returned });
     this.trace?.onNode(node.id);
     if (result.repeat) this.loop(node, result.repeat, ctx, depth);
     const next = result.next === undefined ? [] : Array.isArray(result.next) ? result.next : [result.next];
     for (const port of next) this.follow(node, port, ctx, depth);
   }
 
+  /**
+   * Runs another behavior from its start node to its end node and returns what the end node was
+   * handed. The nested graph gets its own frame and a fresh copy of its variable defaults, so it is
+   * a call and not an inlining: nothing of it survives the return but the values it hands back.
+   */
+  private call(call: CallResult, ctx: NodeContext, depth: number): Record<string, Value> {
+    const program = this.behaviors(call.behaviorId);
+    if (!program) return {};
+    if (this.callStack.includes(call.behaviorId)) throw new Error(`Behavior "${program.name}" runs itself`);
+    const start = terminalNode(program.graph, BEHAVIOR_START);
+    if (!start) return {};
+    const outer = this.frame;
+    this.frame = emptyFrame(program.graph);
+    this.frame.outputCache.set(start.id, { ...call.inputs });
+    this.callStack.push(call.behaviorId);
+    this.calledBehaviors.add(call.behaviorId);
+    try {
+      this.trace?.onNode(start.id);
+      this.follow(start, 'exec', { ...ctx, variables: { ...program.defaults } }, depth + 1);
+      const end = terminalNode(program.graph, BEHAVIOR_END);
+      return (end && this.frame.outputCache.get(end.id)) ?? {};
+    } finally {
+      this.callStack.pop();
+      this.frame = outer;
+    }
+  }
+
   /**
    * One round per count, the loop node's `index` output carrying the round number. Data nodes are
    * cached for the whole pulse, so the round has to drop that cache first – otherwise every round
    * would read the values the first one computed.
    */
   private loop(node: GraphNode, repeat: RepeatResult, ctx: NodeContext, depth: number): void {
-    const outputs = this.outputCache.get(node.id) ?? {};
+    const outputs = this.frame.outputCache.get(node.id) ?? {};
     for (let round = 0; round < repeat.times; round++) {
       if (++this.steps > MAX_STEPS_PER_FIRE)
         throw new Error('Behavior graph exceeded the step limit (endless loop?)');
-      this.dataCache.clear();
-      this.outputCache.set(node.id, { ...outputs, [repeat.index]: round });
+      this.frame.dataCache.clear();
+      this.frame.outputCache.set(node.id, { ...outputs, [repeat.index]: round });
       this.follow(node, repeat.port, ctx, depth);
     }
-    this.dataCache.clear();
+    this.frame.dataCache.clear();
   }
 
   /** Resolves every data input: connected → pulled from the source, else the inline param. */
   private collectInputs(node: GraphNode, ctx: NodeContext): Record<string, Value> {
-    const def = requireNodeDef(node.type);
     const inputs: Record<string, Value> = {};
-    for (const port of def.inputs) {
+    for (const port of this.def(node)?.inputs ?? []) {
       if (port.type === 'exec') continue;
-      const edge = edgesInto(this.graph, node.id, port.key)[0];
+      const edge = edgesInto(this.frame.graph, node.id, port.key)[0];
       if (edge) inputs[port.key] = this.readOutput(edge.from.node, edge.from.port, ctx);
       else inputs[port.key] = inlineValue(node, port);
     }
@@ -116,24 +168,29 @@ export class GraphInterpreter {
 
   /** Value of one output port: from the pulse cache, or by evaluating a pure data node. */
   private readOutput(nodeId: string, port: string, ctx: NodeContext): Value {
-    const cached = this.outputCache.get(nodeId) ?? this.dataCache.get(nodeId);
+    const cached = this.frame.outputCache.get(nodeId) ?? this.frame.dataCache.get(nodeId);
     if (cached) return cached[port] ?? null;
     const source = this.node(nodeId);
     if (!source) return null;
-    const def = requireNodeDef(source.type);
+    const def = this.def(source);
+    if (!def) return null;
     // Exec nodes that have not run in this pulse have no value yet.
     if (isEventNode(def) || hasExecInput(def) || !def.run) return null;
     if (++this.steps > MAX_STEPS_PER_FIRE)
       throw new Error('Behavior graph exceeded the step limit (data cycle?)');
     // Mark before evaluating so a data cycle reads null instead of recursing forever.
-    this.dataCache.set(nodeId, {});
+    this.frame.dataCache.set(nodeId, {});
     const outputs = def.run(ctx, this.collectInputs(source, ctx), source.params).outputs ?? {};
-    this.dataCache.set(nodeId, outputs);
+    this.frame.dataCache.set(nodeId, outputs);
     this.trace?.onNode(nodeId);
     return outputs[port] ?? null;
   }
 
+  private def(node: GraphNode) {
+    return resolveDef(node, this.behaviors);
+  }
+
   private node(id: string): GraphNode | undefined {
-    return this.graph.nodes.find((n) => n.id === id);
+    return this.frame.graph.nodes.find((n) => n.id === id);
   }
 }

src/core/graph/NodeRegistry.ts

@@ -24,6 +24,12 @@ export interface RepeatResult {
   times: number;
 }
 
+/** How a node asks for another behavior's graph to be run in place, `inputs` seeding its start node. */
+export interface CallResult {
+  behaviorId: string;
+  inputs: Record<string, Value>;
+}
+
 export interface RunResult {
   /** Cached for the rest of the pulse. */
   outputs?: Record<string, Value>;
@@ -31,6 +37,8 @@ export interface RunResult {
   next?: string | string[];
   /** Runs `port` that many times before continuing along `next`. */
   repeat?: RepeatResult;
+  /** Runs another behavior before continuing along `next`; its results join `outputs`. */
+  call?: CallResult;
 }
 
 /** Palette, port rendering, connection validation and inspector fields are all derived from this. */

src/core/graph/dropTarget.ts

@@ -1,5 +1,6 @@
 import { edgesInto, findNode, type Graph, type PortType, portsCompatible } from './Graph';
-import { type NodeDef, nodeDef } from './NodeRegistry';
+import { type BehaviorLookup, resolveDef } from './nested';
+import type { NodeDef } from './NodeRegistry';
 
 /** One end of an edge being dragged: a port on a node, seen from its own side. */
 export interface PortSide {
@@ -8,18 +9,18 @@ export interface PortSide {
   isOutput: boolean;
 }
 
-export function portTypeOf(graph: Graph, side: PortSide): PortType | undefined {
+export function portTypeOf(graph: Graph, side: PortSide, lookup: BehaviorLookup): PortType | undefined {
   const node = findNode(graph, side.nodeId);
-  const def = node && nodeDef(node.type);
+  const def = node && resolveDef(node, lookup);
   const list = side.isOutput ? def?.outputs : def?.inputs;
   return list?.find((p) => p.key === side.port)?.type;
 }
 
 /** Whether a drag from `from` may land on `to`, i.e. whether ConnectCommand would accept it. */
-export function canConnect(graph: Graph, from: PortSide, to: PortSide): boolean {
+export function canConnect(graph: Graph, from: PortSide, to: PortSide, lookup: BehaviorLookup): boolean {
   if (from.isOutput === to.isOutput || from.nodeId === to.nodeId) return false;
-  const fromType = portTypeOf(graph, from);
-  const toType = portTypeOf(graph, to);
+  const fromType = portTypeOf(graph, from, lookup);
+  const toType = portTypeOf(graph, to, lookup);
   if (fromType === undefined || toType === undefined) return false;
   const [out, inp] = from.isOutput ? [fromType, toType] : [toType, fromType];
   return portsCompatible(out, inp) && !linked(graph, from, to);
@@ -30,11 +31,16 @@ export function canConnect(graph: Graph, from: PortSide, to: PortSide): boolean
  * the first free compatible one, or – when none is free – the last compatible one, whose edge is
  * then replaced. Returns null when the node offers nothing to connect to.
  */
-export function dropTargetPort(graph: Graph, from: PortSide, nodeId: string): PortSide | null {
+export function dropTargetPort(
+  graph: Graph,
+  from: PortSide,
+  nodeId: string,
+  lookup: BehaviorLookup,
+): PortSide | null {
   if (nodeId === from.nodeId) return null;
   const node = findNode(graph, nodeId);
-  const def = node && nodeDef(node.type);
-  const fromType = portTypeOf(graph, from);
+  const def = node && resolveDef(node, lookup);
+  const fromType = portTypeOf(graph, from, lookup);
   if (!def || fromType === undefined) return null;
   const candidates = compatiblePorts(def, fromType, from.isOutput)
     .map((p) => ({ side: { nodeId, port: p.key, isOutput: !from.isOutput }, type: p.type }))

src/core/graph/index.ts

@@ -3,6 +3,7 @@ import './nodes';
 
 export * from './dropTarget';
 export * from './Graph';
+export * from './nested';
 export * from './NodeContext';
 export * from './NodeRegistry';
 export * from './values';

src/core/graph/nested.ts

@@ -0,0 +1,80 @@
+import type { PropertyBag } from '../model/Properties';
+import { type DeclaredPort, declaredPortType, type Graph, type GraphNode } from './Graph';
+import { nodeDef, type NodeDef, type PortDef } from './NodeRegistry';
+
+export const BEHAVIOR_START = 'BehaviorStart';
+export const BEHAVIOR_END = 'BehaviorEnd';
+export const RUN_BEHAVIOR = 'RunBehavior';
+
+export const BEHAVIOR_PARAM = 'behavior';
+
+/** What running another behavior's graph in place needs: its nodes, its variable defaults, its name. */
+export interface BehaviorProgram {
+  name: string;
+  graph: Graph;
+  defaults: PropertyBag;
+}
+
+export type BehaviorLookup = (assetId: string) => BehaviorProgram | null;
+
+export const NO_BEHAVIORS: BehaviorLookup = () => null;
+
+/** Identifier-like, and not `exec`: that key belongs to the fixed flow port of every terminal node. */
+export function isValidPortName(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && name !== 'exec';
+}
+
+/** The single start (or end) node of a graph; a second one is ignored. */
+export function terminalNode(graph: Graph, type: string): GraphNode | undefined {
+  return graph.nodes.find((n) => n.type === type);
+}
+
+export function isTerminalType(type: string): boolean {
+  return type === BEHAVIOR_START || type === BEHAVIOR_END;
+}
+
+export function isTerminalNode(node: GraphNode): boolean {
+  return isTerminalType(node.type);
+}
+
+export function portsOf(port: DeclaredPort): PortDef {
+  return { key: port.key, label: port.key, type: declaredPortType(port.kind) };
+}
+
+function declaredOf(graph: Graph | undefined, type: string): PortDef[] {
+  const node = graph && terminalNode(graph, type);
+  return (node?.ports ?? []).map(portsOf);
+}
+
+/**
+ * The node definition as it applies to *this* node. Identical to the registered one for every fixed
+ * type; the three nested-behavior types grow ports from a declaration instead – the start and end
+ * node from their own, the call node from those of the behavior it names.
+ */
+export function resolveDef(node: GraphNode, lookup: BehaviorLookup): NodeDef | undefined {
+  const def = nodeDef(node.type);
+  if (!def) return undefined;
+  const own = (node.ports ?? []).map(portsOf);
+  if (node.type === BEHAVIOR_START) return { ...def, outputs: [...def.outputs, ...own] };
+  if (node.type === BEHAVIOR_END) return { ...def, inputs: [...def.inputs, ...own] };
+  if (node.type !== RUN_BEHAVIOR) return def;
+  const program = lookup(String(node.params[BEHAVIOR_PARAM] ?? ''));
+  return {
+    ...def,
+    // The graph reads as what it does, not as a row of identical "Run behavior" boxes.
+    label: program ? program.name : def.label,
+    inputs: [...def.inputs, ...declaredOf(program?.graph, BEHAVIOR_START)],
+    outputs: [...def.outputs, ...declaredOf(program?.graph, BEHAVIOR_END)],
+  };
+}
+
+/**
+ * Everything that changes a node's ports, as one string. Views and the inspector rebuild when it
+ * changes – a port list that is derived rather than fixed has no other way of being noticed.
+ */
+export function portSignature(node: GraphNode, lookup: BehaviorLookup): string {
+  const def = resolveDef(node, lookup);
+  if (!def) return 'missing';
+  const list = (ports: PortDef[]) => ports.map((p) => `${p.key}:${p.type}`).join(',');
+  return `${node.type}|${def.label}|${list(def.inputs)}|${list(def.outputs)}`;
+}

src/core/graph/nodes/flow/BehaviorEnd.ts

@@ -0,0 +1,21 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { BEHAVIOR_END } from '../../nested';
+import { exec } from '../shared';
+
+/**
+ * The exit of a behavior used as a node: what arrives at its declared inputs leaves the calling
+ * node as output. Handing the inputs straight back out is what parks the result in the pulse
+ * cache, where the caller reads it once the flow has returned.
+ */
+export const BehaviorEnd: NodeDef = {
+  type: BEHAVIOR_END,
+  label: 'End',
+  category: 'flow',
+  description:
+    'Ends this behavior and hands its results back to the graph that ran it. Every output declared ' +
+    'here becomes an output port on that node.',
+  inputs: [exec()],
+  outputs: [],
+  params: [],
+  run: (_ctx, inputs) => ({ outputs: inputs }),
+};

src/core/graph/nodes/flow/BehaviorStart.ts

@@ -0,0 +1,19 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { BEHAVIOR_START } from '../../nested';
+import { exec } from '../shared';
+
+/**
+ * The entry point of a behavior used as a node. Its declared outputs are the inputs the calling
+ * graph passes in; the interpreter seeds them, so it has no `run` – like an event node.
+ */
+export const BehaviorStart: NodeDef = {
+  type: BEHAVIOR_START,
+  label: 'Start',
+  category: 'event',
+  description:
+    'Where this behavior begins when another graph runs it as a node. Every input declared here ' +
+    'becomes an input port on that node.',
+  inputs: [],
+  outputs: [exec()],
+  params: [],
+};

src/core/graph/nodes/flow/RunBehavior.ts

@@ -0,0 +1,24 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { BEHAVIOR_PARAM, RUN_BEHAVIOR } from '../../nested';
+import { exec } from '../shared';
+
+/**
+ * Runs another behavior's graph in place, from its start node to its end node. The ports come from
+ * those two nodes (see `nested.ts`); the interpreter does the call, because only it can hold a
+ * second graph's pulse.
+ */
+export const RunBehavior: NodeDef = {
+  type: RUN_BEHAVIOR,
+  label: 'Run behavior',
+  category: 'flow',
+  description:
+    'Runs another behavior as a step of this one, passing values in and taking results out. The ' +
+    'behavior keeps no state between calls: its variables start at their defaults every time.',
+  inputs: [exec()],
+  outputs: [exec()],
+  params: [{ key: BEHAVIOR_PARAM, label: 'Behavior', kind: 'asset', default: '', assetTypes: ['behavior'] }],
+  run: (_ctx, inputs, params) => ({
+    call: { behaviorId: String(params[BEHAVIOR_PARAM] ?? ''), inputs },
+    next: 'exec',
+  }),
+};

src/core/graph/nodes/index.ts

@@ -65,8 +65,11 @@ import { OnKeyUp } from './events/OnKeyUp';
 import { OnStart } from './events/OnStart';
 import { OnTimer } from './events/OnTimer';
 import { OnUpdate } from './events/OnUpdate';
+import { BehaviorEnd } from './flow/BehaviorEnd';
+import { BehaviorStart } from './flow/BehaviorStart';
 import { Branch } from './flow/Branch';
 import { Repeat } from './flow/Repeat';
+import { RunBehavior } from './flow/RunBehavior';
 import { Sequence } from './flow/Sequence';
 import { GetVariable } from './variable/GetVariable';
 import { SetVariable } from './variable/SetVariable';
@@ -87,10 +90,13 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   OnCollisionStay,
   OnCollisionExit,
   OnClick,
+  BehaviorStart,
   // flow
   Branch,
   Sequence,
   Repeat,
+  RunBehavior,
+  BehaviorEnd,
   // variables
   GetVariable,
   SetVariable,