A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(logic): a graph can call another graph, and pay for it out of one budget
esengine7867fd049d40
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b67140912..945f2297b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -74,6 +74,35 @@ published separately; it ships inside the editor.player moves, releases it and they stop, dodges and the score rises, chases ablock and the run ends, presses Space and it begins again on a clear board.+- **A graph can call another graph.** The last thing a `.esgraph` could not do+ was reuse itself: a long graph could only be tidied by moving nodes around,+ and the same four nodes were redrawn everywhere the same question got asked.++ A graph that carries a `graph.input` is one a call can enter, and what it+ declares as `inputs`/`outputs` IS the signature — so a `graph.call` elsewhere+ draws exactly those pins, and changing the signature redraws every caller+ rather than leaving one on a stale shape. It is a built-in node kind rather+ than a registered name, for the reason `entity.spawn` is: a graph is an asset+ of the realm that loaded it, and the registry is process-wide.++ What it promises is a call, not a coroutine. The callee runs to completion+ inside the caller's step; it keeps its OWN frame per call site, so its+ variables are local to the call and survive between calls the way an entity's+ graph does; and it spends the CALLER's budget, or calling often would buy the+ unbounded work that looping cannot. A graph that reaches itself stops at a+ call depth rather than on the JS stack, and a `flow.delay` inside a called+ graph is refused at compile: the call returns within the caller's step, so+ there is no later tick for a timer to expire on.++ The signature travels with the ACQUISITION. A loader takes the graphs its call+ nodes name — which is what makes them owned by this era and there to run — and+ reads their declaration off the same door, because the caller's pins are the+ callee's declaration and the two facts have to arrive together.++ `examples/dodge-graph` now asks one question through one graph: three of its+ graphs drew the same "is the run still alive" four nodes, and now they call+ `alive.esgraph` instead.+- **A graph can change the scene.** It is the one thing gameplay needs that nocomponent can express — the write would retire the world the component livesin — so an authored surface could reach everything about a game except its@@ -119,6 +148,13 @@ published separately; it ships inside the editor.### Fixed+- **Two nodes under one id are reported instead of one replacing the other.**+ Every lookup in a compiled graph is by node id, so a file carrying the same id+ twice quietly kept whichever came last, and any wire drawn to either landed on+ it. `dodge-graph` carried such a pair — harmlessly, because both nodes did the+ same thing, which is exactly how a graph where they did not would have gone+ unnoticed.+- **A sound stops when whatever owned it goes away.** Switching an AudioSourceoff, clearing its clip, or removing the component dropped the handle to thevoice WITHOUT stopping it. The sound kept playing with nothing anywhere ablediff --git a/desktop b/desktopindex ba6df0552..2554554ac 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ba6df055252c0b57d7620cf524c03e939d1dd84b+Subproject commit 2554554ac62f5c79bc9ddddb75521d4386a5d99ddiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 19ef95184..7f41730b6 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 114,"beta": 101,- "experimental": 1963,+ "experimental": 1976,"deprecated": 3},- "total": 2178,+ "total": 2191,"subsystems": [{"id": "ecs",diff --git a/examples/dodge-graph/assets/logic/alive.esgraph b/examples/dodge-graph/assets/logic/alive.esgraphnew file mode 100644index 000000000..b7910adcb--- /dev/null+++ b/examples/dodge-graph/assets/logic/alive.esgraph@@ -0,0 +1,67 @@+{+ "version": "1.0",+ "name": "Alive",+ "outputs": [+ {+ "name": "alive",+ "type": "bool"+ }+ ],+ "nodes": [+ {+ "id": "in",+ "kind": "graph.input",+ "x": 0,+ "y": 0+ },+ {+ "id": "game",+ "kind": "call",+ "ref": "entity.byName",+ "literals": {+ "name": "Game"+ },+ "x": -40,+ "y": 140+ },+ {+ "id": "read",+ "kind": "call",+ "ref": "property.get",+ "literals": {+ "path": "GameState.alive"+ },+ "x": 190,+ "y": 140+ },+ {+ "id": "out",+ "kind": "graph.output",+ "x": 430,+ "y": 0+ }+ ],+ "edges": [+ {+ "id": "in.then->out",+ "from": "in",+ "fromPort": "then",+ "to": "out",+ "toPort": ""+ },+ {+ "id": "game.entity->read.entity",+ "from": "game",+ "fromPort": "entity",+ "to": "read",+ "toPort": "entity"+ },+ {+ "id": "read.value->out.alive",+ "from": "read",+ "fromPort": "value",+ "to": "out",+ "toPort": "alive"+ }+ ]+}diff --git a/examples/dodge-graph/assets/logic/alive.esgraph.meta b/examples/dodge-graph/assets/logic/alive.esgraph.metanew file mode 100644index 000000000..905022f29--- /dev/null+++ b/examples/dodge-graph/assets/logic/alive.esgraph.meta@@ -0,0 +1,6 @@+{+ "uuid": "7c0d0b10-2c44-4a8e-9f21-7c6b1d3e4b05",+ "version": "2.0",+ "type": "scriptgraph",+ "importer": {}+}diff --git a/examples/dodge-graph/assets/logic/block.esgraph b/examples/dodge-graph/assets/logic/block.esgraphindex 39bae0f83..1a9cda233 100644--- a/examples/dodge-graph/assets/logic/block.esgraph+++ b/examples/dodge-graph/assets/logic/block.esgraph@@ -317,16 +317,6 @@"x": -432,"y": 1010},- {- "id": "alive",- "kind": "call",- "ref": "property.get",- "literals": {- "path": "GameState.alive"- },- "x": 34,- "y": 1150- },{"id": "live","kind": "flow.branch",@@ -334,24 +324,13 @@"y": 960},{- "id": "game_1",- "kind": "call",- "ref": "entity.byName",- "literals": {- "name": "Game"- },- "x": 1034,- "y": 1720- },- {- "id": "game_1_1",- "kind": "call",- "ref": "entity.byName",+ "id": "askAlive",+ "kind": "graph.call","literals": {- "name": "Game"+ "graph": "assets/logic/alive.esgraph"},- "x": -182,- "y": 1340+ "x": -250,+ "y": 60}],"edges": [@@ -586,27 +565,6 @@"to": "out","toPort": "entity"},- {- "id": "upd.then->live.",- "from": "upd",- "fromPort": "then",- "to": "live",- "toPort": ""- },- {- "id": "game_1_1.entity->alive.entity",- "from": "game_1_1",- "fromPort": "entity",- "to": "alive",- "toPort": "entity"- },- {- "id": "alive.value->live.cond",- "from": "alive",- "fromPort": "value",- "to": "live",- "toPort": "cond"- },{"id": "live.true->setY.","from": "live",@@ -620,6 +578,27 @@"fromPort": "false","to": "die","toPort": ""+ },+ {+ "id": "upd.then->askAlive",+ "from": "upd",+ "fromPort": "then",+ "to": "askAlive",+ "toPort": ""+ },+ {+ "id": "askAlive.then->gate",+ "from": "askAlive",+ "fromPort": "then",+ "to": "live",+ "toPort": ""+ },+ {+ "id": "askAlive.alive->cond",+ "from": "askAlive",+ "fromPort": "alive",+ "to": "live",+ "toPort": "cond"}]-}\ No newline at end of file+}diff --git a/examples/dodge-graph/assets/logic/hud.esgraph b/examples/dodge-graph/assets/logic/hud.esgraphindex 8b2501a19..d2127f968 100644--- a/examples/dodge-graph/assets/logic/hud.esgraph+++ b/examples/dodge-graph/assets/logic/hud.esgraph@@ -8,26 +8,6 @@"x": 0,"y": 60},- {- "id": "game",- "kind": "call",- "x": -182,- "y": 440,- "ref": "entity.byName",- "literals": {- "name": "Game"- }- },- {- "id": "alive",- "kind": "call",- "x": 34,- "y": 250,- "ref": "property.get",- "literals": {- "path": "GameState.alive"- }- },{"id": "score","kind": "call",@@ -142,23 +122,18 @@"literals": {"name": "Game"}+ },+ {+ "id": "askAlive",+ "kind": "graph.call",+ "literals": {+ "graph": "assets/logic/alive.esgraph"+ },+ "x": -250,+ "y": 60}],"edges": [- {- "id": "upd.then->gate.",- "from": "upd",- "fromPort": "then",- "to": "gate",- "toPort": ""- },- {- "id": "game.entity->alive.entity",- "from": "game",- "fromPort": "entity",- "to": "alive",- "toPort": "entity"- },{"id": "game_1.entity->score.entity","from": "game_1",@@ -166,13 +141,6 @@"to": "score","toPort": "entity"},- {- "id": "alive.value->gate.cond",- "from": "alive",- "fromPort": "value",- "to": "gate",- "toPort": "cond"- },{"id": "gate.true->live.","from": "gate",@@ -242,6 +210,27 @@"fromPort": "entity","to": "zero","toPort": "entity"+ },+ {+ "id": "upd.then->askAlive",+ "from": "upd",+ "fromPort": "then",+ "to": "askAlive",+ "toPort": ""+ },+ {+ "id": "askAlive.then->gate",+ "from": "askAlive",+ "fromPort": "then",+ "to": "gate",+ "toPort": ""+ },+ {+ "id": "askAlive.alive->cond",+ "from": "askAlive",+ "fromPort": "alive",+ "to": "gate",+ "toPort": "cond"}]-}\ No newline at end of file+}diff --git a/examples/dodge-graph/assets/logic/player.esgraph b/examples/dodge-graph/assets/logic/player.esgraphindex 44f20a2a6..950d24c2d 100644--- a/examples/dodge-graph/assets/logic/player.esgraph+++ b/examples/dodge-graph/assets/logic/player.esgraph@@ -8,26 +8,6 @@"x": 0,"y": 60},- {- "id": "game",- "kind": "call",- "x": -182,- "y": 440,- "ref": "entity.byName",- "literals": {- "name": "Game"- }- },- {- "id": "alive",- "kind": "call",- "x": 34,- "y": 250,- "ref": "property.get",- "literals": {- "path": "GameState.alive"- }- },{"id": "gate","kind": "flow.branch",@@ -141,30 +121,18 @@"literals": {"name": "x"}+ },+ {+ "id": "askAlive",+ "kind": "graph.call",+ "literals": {+ "graph": "assets/logic/alive.esgraph"+ },+ "x": -250,+ "y": 60}],"edges": [- {- "id": "upd.then->gate.",- "from": "upd",- "fromPort": "then",- "to": "gate",- "toPort": ""- },- {- "id": "game.entity->alive.entity",- "from": "game",- "fromPort": "entity",- "to": "alive",- "toPort": "entity"- },- {- "id": "alive.value->gate.cond",- "from": "alive",- "fromPort": "value",- "to": "gate",- "toPort": "cond"- },{"id": "gate.true->setX.","from": "gate",@@ -248,6 +216,27 @@"fromPort": "value","to": "seedSet","toPort": "value"+ },+ {+ "id": "upd.then->askAlive",+ "from": "upd",+ "fromPort": "then",+ "to": "askAlive",+ "toPort": ""+ },+ {+ "id": "askAlive.then->gate",+ "from": "askAlive",+ "fromPort": "then",+ "to": "gate",+ "toPort": ""+ },+ {+ "id": "askAlive.alive->cond",+ "from": "askAlive",+ "fromPort": "alive",+ "to": "gate",+ "toPort": "cond"}],"variables": [@@ -257,4 +246,4 @@"default": 0}]-}\ No newline at end of file+}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex ac1c24220..ca9ba97d2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1802 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1815 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2519,7 +2519,9 @@ destroys: string[]events: Map<string, string[]>execTargets: Map<string, string>graph: ScriptGraph+inputNode: string | undefinednodes: Map<string, ScriptGraphNode>+outputNode: string | undefinedprefabs: Map<string, PreparedPrefab>problems: string[]shapes: Map<string, ScriptNodeShape>@@ -5018,6 +5020,11 @@ Restart = 1"1.0"```+## MAX_CALL_DEPTH — const @experimental+```+16+```+## MAX_POLYGON_VERTICES — const @experimental```8@@ -8029,11 +8036,21 @@ renderPolicy: RenderResolution | undefinedscaleMode: number```+## ScriptFrame — interface @experimental+```+calls: Map<string, ScriptFrame>+produced: Map<string, Record<string, ScriptValue>>+timers: Map<string, number>+vars: Map<string, ScriptValue>+```+## ScriptGraph — interface @experimental```edges: ScriptGraphEdge[]+inputs: ScriptGraphPort[] | undefinedname: string | undefinednodes: ScriptGraphNode[]+outputs: ScriptGraphPort[] | undefinedvariables: ScriptGraphVariable[] | undefinedversion: string```@@ -8075,6 +8092,20 @@ static new (): ScriptGraphPluginstatic prototype: ScriptGraphPlugin```+## ScriptGraphPort — interface @experimental+```+default: ScriptValue | undefined+label: string | undefined+name: string+type: "string" | "number" | "bool" | "entity" | "any"+```++## ScriptGraphSignature — interface @experimental+```+inputs: readonly ScriptGraphPort[]+outputs: readonly ScriptGraphPort[]+```+## ScriptGraphVariable — interface @experimental```default: ScriptValue | undefined@@ -8111,6 +8142,7 @@ type: ScriptValueType## ScriptRunState — interface @experimental```+calls: Map<string, ScriptFrame>halted: booleanproduced: Map<string, Record<string, ScriptValue>>reported: Set<string>@@ -8127,6 +8159,7 @@ ctx: Ctxdt: numberonProblem: ((message: string) => void) | undefinedregistry: AiRegistry<Ctx>+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefinedworld: World | undefined```@@ -8144,6 +8177,7 @@ boolean | number | string | null```getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]+graphSignature: (ref: string) => ScriptGraphSignature | nullhasAction: (name: string) => booleanisActionPure: (name: string) => boolean```@@ -11058,6 +11092,11 @@ TransformData(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void```+## addScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph+```+## addScriptNode — function @experimental```(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }@@ -12638,6 +12677,11 @@ GameplayPlugin(): Array<{ type: string; value: string; }>```+## graphCallRef — function @experimental+```+(node: ScriptGraphNode): string+```+## hasPlayableCta — function @experimental```(): boolean@@ -12763,6 +12807,11 @@ InputRouter(ref: string): boolean```+## isCallableGraph — function @experimental+```+(graph: ScriptGraph): boolean+```+## isCollisionPaletteRef — function @experimental```(refs: readonly string[]): boolean@@ -13673,6 +13722,11 @@ PrefabsPlugin(graph: ScriptGraph, id: string): ScriptGraph```+## removeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph+```+## removeScriptNode — function @experimental```(graph: ScriptGraph, id: string): ScriptGraph@@ -13698,6 +13752,11 @@ PrefabsPlugin(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef```+## renameScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph+```+## renameScriptVariable — function @experimental```(graph: ScriptGraph, from: string, to: string): ScriptGraph@@ -13813,6 +13872,11 @@ ReplicationPlugin(world: World, entity: Entity): void```+## retypeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph+```+## rootMotionVelocity — function @experimental```(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }@@ -13928,6 +13992,16 @@ Plugin(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }```+## scriptCatalog — function @experimental+```+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog+```++## scriptGraphCallRefs — function @experimental+```+(graph: ScriptGraph): string[]+```+## scriptGraphPlugin — const @experimental```ScriptGraphPlugin@@ -14238,6 +14312,11 @@ ServicesPlugin<T>(initial: T): Signal<T>```+## signatureOf — function @experimental+```+(graph: ScriptGraph): ScriptGraphSignature+```+## singleStamp — function @experimental```(raw: number): TileStampdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 92d0bd77c..de04a34fa 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 99 beta · 1821 experimental · 3 deprecated+Symbols: 114 public · 99 beta · 1834 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2519,7 +2519,9 @@ destroys: string[]events: Map<string, string[]>execTargets: Map<string, string>graph: ScriptGraph+inputNode: string | undefinednodes: Map<string, ScriptGraphNode>+outputNode: string | undefinedprefabs: Map<string, PreparedPrefab>problems: string[]shapes: Map<string, ScriptNodeShape>@@ -5026,6 +5028,11 @@ Restart = 1"1.0"```+## MAX_CALL_DEPTH — const @experimental+```+16+```+## MAX_POLYGON_VERTICES — const @experimental```8@@ -8222,11 +8229,21 @@ renderPolicy: RenderResolution | undefinedscaleMode: number```+## ScriptFrame — interface @experimental+```+calls: Map<string, ScriptFrame>+produced: Map<string, Record<string, ScriptValue>>+timers: Map<string, number>+vars: Map<string, ScriptValue>+```+## ScriptGraph — interface @experimental```edges: ScriptGraphEdge[]+inputs: ScriptGraphPort[] | undefinedname: string | undefinednodes: ScriptGraphNode[]+outputs: ScriptGraphPort[] | undefinedvariables: ScriptGraphVariable[] | undefinedversion: string```@@ -8268,6 +8285,20 @@ static new (): ScriptGraphPluginstatic prototype: ScriptGraphPlugin```+## ScriptGraphPort — interface @experimental+```+default: ScriptValue | undefined+label: string | undefined+name: string+type: "string" | "number" | "bool" | "entity" | "any"+```++## ScriptGraphSignature — interface @experimental+```+inputs: readonly ScriptGraphPort[]+outputs: readonly ScriptGraphPort[]+```+## ScriptGraphVariable — interface @experimental```default: ScriptValue | undefined@@ -8304,6 +8335,7 @@ type: ScriptValueType## ScriptRunState — interface @experimental```+calls: Map<string, ScriptFrame>halted: booleanproduced: Map<string, Record<string, ScriptValue>>reported: Set<string>@@ -8320,6 +8352,7 @@ ctx: Ctxdt: numberonProblem: ((message: string) => void) | undefinedregistry: AiRegistry<Ctx>+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefinedworld: World | undefined```@@ -8337,6 +8370,7 @@ boolean | number | string | null```getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]+graphSignature: (ref: string) => ScriptGraphSignature | nullhasAction: (name: string) => booleanisActionPure: (name: string) => boolean```@@ -11251,6 +11285,11 @@ TransformData(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void```+## addScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph+```+## addScriptNode — function @experimental```(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }@@ -12871,6 +12910,11 @@ GameplayPlugin(): Array<{ type: string; value: string; }>```+## graphCallRef — function @experimental+```+(node: ScriptGraphNode): string+```+## hasPlayableCta — function @experimental```(): boolean@@ -13006,6 +13050,11 @@ InputRouter(ref: string): boolean```+## isCallableGraph — function @experimental+```+(graph: ScriptGraph): boolean+```+## isCollisionPaletteRef — function @experimental```(refs: readonly string[]): boolean@@ -13916,6 +13965,11 @@ PrefabsPlugin(graph: ScriptGraph, id: string): ScriptGraph```+## removeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph+```+## removeScriptNode — function @experimental```(graph: ScriptGraph, id: string): ScriptGraph@@ -13941,6 +13995,11 @@ PrefabsPlugin(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef```+## renameScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph+```+## renameScriptVariable — function @experimental```(graph: ScriptGraph, from: string, to: string): ScriptGraph@@ -14056,6 +14115,11 @@ ReplicationPlugin(world: World, entity: Entity): void```+## retypeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph+```+## rootMotionVelocity — function @experimental```(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }@@ -14171,6 +14235,16 @@ Plugin(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }```+## scriptCatalog — function @experimental+```+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog+```++## scriptGraphCallRefs — function @experimental+```+(graph: ScriptGraph): string[]+```+## scriptGraphPlugin — const @experimental```ScriptGraphPlugin@@ -14481,6 +14555,11 @@ ServicesPlugin<T>(initial: T): Signal<T>```+## signatureOf — function @experimental+```+(graph: ScriptGraph): ScriptGraphSignature+```+## singleStamp — function @experimental```(raw: number): TileStampdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 2d9b5828c..9d87b6a97 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 96 beta · 1801 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1814 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2514,7 +2514,9 @@ destroys: string[]events: Map<string, string[]>execTargets: Map<string, string>graph: ScriptGraph+inputNode: string | undefinednodes: Map<string, ScriptGraphNode>+outputNode: string | undefinedprefabs: Map<string, PreparedPrefab>problems: string[]shapes: Map<string, ScriptNodeShape>@@ -5013,6 +5015,11 @@ Restart = 1"1.0"```+## MAX_CALL_DEPTH — const @experimental+```+16+```+## MAX_POLYGON_VERTICES — const @experimental```8@@ -8024,11 +8031,21 @@ renderPolicy: RenderResolution | undefinedscaleMode: number```+## ScriptFrame — interface @experimental+```+calls: Map<string, ScriptFrame>+produced: Map<string, Record<string, ScriptValue>>+timers: Map<string, number>+vars: Map<string, ScriptValue>+```+## ScriptGraph — interface @experimental```edges: ScriptGraphEdge[]+inputs: ScriptGraphPort[] | undefinedname: string | undefinednodes: ScriptGraphNode[]+outputs: ScriptGraphPort[] | undefinedvariables: ScriptGraphVariable[] | undefinedversion: string```@@ -8070,6 +8087,20 @@ static new (): ScriptGraphPluginstatic prototype: ScriptGraphPlugin```+## ScriptGraphPort — interface @experimental+```+default: ScriptValue | undefined+label: string | undefined+name: string+type: "string" | "number" | "bool" | "entity" | "any"+```++## ScriptGraphSignature — interface @experimental+```+inputs: readonly ScriptGraphPort[]+outputs: readonly ScriptGraphPort[]+```+## ScriptGraphVariable — interface @experimental```default: ScriptValue | undefined@@ -8106,6 +8137,7 @@ type: ScriptValueType## ScriptRunState — interface @experimental```+calls: Map<string, ScriptFrame>halted: booleanproduced: Map<string, Record<string, ScriptValue>>reported: Set<string>@@ -8122,6 +8154,7 @@ ctx: Ctxdt: numberonProblem: ((message: string) => void) | undefinedregistry: AiRegistry<Ctx>+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefinedworld: World | undefined```@@ -8139,6 +8172,7 @@ boolean | number | string | null```getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]+graphSignature: (ref: string) => ScriptGraphSignature | nullhasAction: (name: string) => booleanisActionPure: (name: string) => boolean```@@ -11053,6 +11087,11 @@ TransformData(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void```+## addScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph+```+## addScriptNode — function @experimental```(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }@@ -12633,6 +12672,11 @@ GameplayPlugin(): Array<{ type: string; value: string; }>```+## graphCallRef — function @experimental+```+(node: ScriptGraphNode): string+```+## hasPlayableCta — function @experimental```(): boolean@@ -12758,6 +12802,11 @@ InputRouter(ref: string): boolean```+## isCallableGraph — function @experimental+```+(graph: ScriptGraph): boolean+```+## isCollisionPaletteRef — function @experimental```(refs: readonly string[]): boolean@@ -13678,6 +13727,11 @@ PrefabsPlugin(graph: ScriptGraph, id: string): ScriptGraph```+## removeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph+```+## removeScriptNode — function @experimental```(graph: ScriptGraph, id: string): ScriptGraph@@ -13703,6 +13757,11 @@ PrefabsPlugin(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef```+## renameScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph+```+## renameScriptVariable — function @experimental```(graph: ScriptGraph, from: string, to: string): ScriptGraph@@ -13818,6 +13877,11 @@ ReplicationPlugin(world: World, entity: Entity): void```+## retypeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph+```+## rootMotionVelocity — function @experimental```(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }@@ -13933,6 +13997,16 @@ Plugin(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }```+## scriptCatalog — function @experimental+```+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog+```++## scriptGraphCallRefs — function @experimental+```+(graph: ScriptGraph): string[]+```+## scriptGraphPlugin — const @experimental```ScriptGraphPlugin@@ -14243,6 +14317,11 @@ ServicesPlugin<T>(initial: T): Signal<T>```+## signatureOf — function @experimental+```+(graph: ScriptGraph): ScriptGraphSignature+```+## singleStamp — function @experimental```(raw: number): TileStampdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 097e128b3..0c5c3fc40 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1823 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1836 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2514,7 +2514,9 @@ destroys: string[]events: Map<string, string[]>execTargets: Map<string, string>graph: ScriptGraph+inputNode: string | undefinednodes: Map<string, ScriptGraphNode>+outputNode: string | undefinedprefabs: Map<string, PreparedPrefab>problems: string[]shapes: Map<string, ScriptNodeShape>@@ -5013,6 +5015,11 @@ Restart = 1"1.0"```+## MAX_CALL_DEPTH — const @experimental+```+16+```+## MAX_POLYGON_VERTICES — const @experimental```8@@ -8272,11 +8279,21 @@ renderPolicy: RenderResolution | undefinedscaleMode: number```+## ScriptFrame — interface @experimental+```+calls: Map<string, ScriptFrame>+produced: Map<string, Record<string, ScriptValue>>+timers: Map<string, number>+vars: Map<string, ScriptValue>+```+## ScriptGraph — interface @experimental```edges: ScriptGraphEdge[]+inputs: ScriptGraphPort[] | undefinedname: string | undefinednodes: ScriptGraphNode[]+outputs: ScriptGraphPort[] | undefinedvariables: ScriptGraphVariable[] | undefinedversion: string```@@ -8318,6 +8335,20 @@ static new (): ScriptGraphPluginstatic prototype: ScriptGraphPlugin```+## ScriptGraphPort — interface @experimental+```+default: ScriptValue | undefined+label: string | undefined+name: string+type: "string" | "number" | "bool" | "entity" | "any"+```++## ScriptGraphSignature — interface @experimental+```+inputs: readonly ScriptGraphPort[]+outputs: readonly ScriptGraphPort[]+```+## ScriptGraphVariable — interface @experimental```default: ScriptValue | undefined@@ -8354,6 +8385,7 @@ type: ScriptValueType## ScriptRunState — interface @experimental```+calls: Map<string, ScriptFrame>halted: booleanproduced: Map<string, Record<string, ScriptValue>>reported: Set<string>@@ -8370,6 +8402,7 @@ ctx: Ctxdt: numberonProblem: ((message: string) => void) | undefinedregistry: AiRegistry<Ctx>+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefinedworld: World | undefined```@@ -8387,6 +8420,7 @@ boolean | number | string | null```getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]+graphSignature: (ref: string) => ScriptGraphSignature | nullhasAction: (name: string) => booleanisActionPure: (name: string) => boolean```@@ -11307,6 +11341,11 @@ TransformData(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void```+## addScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph+```+## addScriptNode — function @experimental```(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }@@ -12892,6 +12931,11 @@ GameplayPlugin(): Array<{ type: string; value: string; }>```+## graphCallRef — function @experimental+```+(node: ScriptGraphNode): string+```+## hasPlayableCta — function @experimental```(): boolean@@ -13027,6 +13071,11 @@ InputRouter(ref: string): boolean```+## isCallableGraph — function @experimental+```+(graph: ScriptGraph): boolean+```+## isCollisionPaletteRef — function @experimental```(refs: readonly string[]): boolean@@ -13937,6 +13986,11 @@ PrefabsPlugin(graph: ScriptGraph, id: string): ScriptGraph```+## removeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph+```+## removeScriptNode — function @experimental```(graph: ScriptGraph, id: string): ScriptGraph@@ -13962,6 +14016,11 @@ PrefabsPlugin(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef```+## renameScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph+```+## renameScriptVariable — function @experimental```(graph: ScriptGraph, from: string, to: string): ScriptGraph@@ -14077,6 +14136,11 @@ ReplicationPlugin(world: World, entity: Entity): void```+## retypeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph+```+## rootMotionVelocity — function @experimental```(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }@@ -14192,6 +14256,16 @@ Plugin(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }```+## scriptCatalog — function @experimental+```+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog+```++## scriptGraphCallRefs — function @experimental+```+(graph: ScriptGraph): string[]+```+## scriptGraphPlugin — const @experimental```ScriptGraphPlugin@@ -14502,6 +14576,11 @@ ServicesPlugin<T>(initial: T): Signal<T>```+## signatureOf — function @experimental+```+(graph: ScriptGraph): ScriptGraphSignature+```+## singleStamp — function @experimental```(raw: number): TileStampdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 8d9cbe55e..ec49e6400 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1813 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1826 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2514,7 +2514,9 @@ destroys: string[]events: Map<string, string[]>execTargets: Map<string, string>graph: ScriptGraph+inputNode: string | undefinednodes: Map<string, ScriptGraphNode>+outputNode: string | undefinedprefabs: Map<string, PreparedPrefab>problems: string[]shapes: Map<string, ScriptNodeShape>@@ -5020,6 +5022,11 @@ Restart = 1"1.0"```+## MAX_CALL_DEPTH — const @experimental+```+16+```+## MAX_POLYGON_VERTICES — const @experimental```8@@ -8031,11 +8038,21 @@ renderPolicy: RenderResolution | undefinedscaleMode: number```+## ScriptFrame — interface @experimental+```+calls: Map<string, ScriptFrame>+produced: Map<string, Record<string, ScriptValue>>+timers: Map<string, number>+vars: Map<string, ScriptValue>+```+## ScriptGraph — interface @experimental```edges: ScriptGraphEdge[]+inputs: ScriptGraphPort[] | undefinedname: string | undefinednodes: ScriptGraphNode[]+outputs: ScriptGraphPort[] | undefinedvariables: ScriptGraphVariable[] | undefinedversion: string```@@ -8077,6 +8094,20 @@ static new (): ScriptGraphPluginstatic prototype: ScriptGraphPlugin```+## ScriptGraphPort — interface @experimental+```+default: ScriptValue | undefined+label: string | undefined+name: string+type: "string" | "number" | "bool" | "entity" | "any"+```++## ScriptGraphSignature — interface @experimental+```+inputs: readonly ScriptGraphPort[]+outputs: readonly ScriptGraphPort[]+```+## ScriptGraphVariable — interface @experimental```default: ScriptValue | undefined@@ -8113,6 +8144,7 @@ type: ScriptValueType## ScriptRunState — interface @experimental```+calls: Map<string, ScriptFrame>halted: booleanproduced: Map<string, Record<string, ScriptValue>>reported: Set<string>@@ -8129,6 +8161,7 @@ ctx: Ctxdt: numberonProblem: ((message: string) => void) | undefinedregistry: AiRegistry<Ctx>+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefinedworld: World | undefined```@@ -8146,6 +8179,7 @@ boolean | number | string | null```getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]+graphSignature: (ref: string) => ScriptGraphSignature | nullhasAction: (name: string) => booleanisActionPure: (name: string) => boolean```@@ -11081,6 +11115,11 @@ TransformData(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void```+## addScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", port: ScriptGraphPort): ScriptGraph+```+## addScriptNode — function @experimental```(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }@@ -12661,6 +12700,11 @@ GameplayPlugin(): Array<{ type: string; value: string; }>```+## graphCallRef — function @experimental+```+(node: ScriptGraphNode): string+```+## hasPlayableCta — function @experimental```(): boolean@@ -12791,6 +12835,11 @@ InputRouter(ref: string): boolean```+## isCallableGraph — function @experimental+```+(graph: ScriptGraph): boolean+```+## isCollisionPaletteRef — function @experimental```(refs: readonly string[]): boolean@@ -13701,6 +13750,11 @@ PrefabsPlugin(graph: ScriptGraph, id: string): ScriptGraph```+## removeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string): ScriptGraph+```+## removeScriptNode — function @experimental```(graph: ScriptGraph, id: string): ScriptGraph@@ -13726,6 +13780,11 @@ PrefabsPlugin(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef```+## renameScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", from: string, to: string): ScriptGraph+```+## renameScriptVariable — function @experimental```(graph: ScriptGraph, from: string, to: string): ScriptGraph@@ -13841,6 +13900,11 @@ ReplicationPlugin(world: World, entity: Entity): void```+## retypeScriptGraphPort — function @experimental+```+(graph: ScriptGraph, side: "inputs" | "outputs", name: string, type: ScriptGraphPort["type"]): ScriptGraph+```+## rootMotionVelocity — function @experimental```(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }@@ -13956,6 +14020,16 @@ Plugin(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }```+## scriptCatalog — function @experimental+```+(verbs: Omit<ScriptVerbCatalog, "graphSignature">, signatures?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog+```++## scriptGraphCallRefs — function @experimental+```+(graph: ScriptGraph): string[]+```+## scriptGraphPlugin — const @experimental```ScriptGraphPlugin@@ -14266,6 +14340,11 @@ ServicesPlugin<T>(initial: T): Signal<T>```+## signatureOf — function @experimental+```+(graph: ScriptGraph): ScriptGraphSignature+```+## singleStamp — function @experimental```(raw: number): TileStampdiff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.tsindex 65e401c85..f3614487f 100644--- a/sdk/src/asset/AssetLoader.ts+++ b/sdk/src/asset/AssetLoader.ts@@ -2,6 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { Backend } from './Backend';import type { AssetLease } from './AssetLease';+import type { ScriptGraphSignature } from '../logic/nodes';import type { PreparedPrefab } from '../prefab/preparedPrefab';import type { RegistryEra } from './registryAssets';import type { Catalog } from './Catalog';@@ -88,6 +89,12 @@ export interface BtResult {export interface ScriptGraphResult {graphId: string;+ /**+ * What this graph takes and hands back, for one CALLING it: a caller's pins+ * come from the callee's declaration, and acquiring it is how the caller+ * gets both the ownership and the shape in one door.+ */+ signature?: ScriptGraphSignature;}export interface PrefabResult {diff --git a/sdk/src/asset/loaders/ScriptGraphAssetLoader.ts b/sdk/src/asset/loaders/ScriptGraphAssetLoader.tsindex da6446940..7b08b015c 100644--- a/sdk/src/asset/loaders/ScriptGraphAssetLoader.ts+++ b/sdk/src/asset/loaders/ScriptGraphAssetLoader.ts@@ -13,11 +13,17 @@* to the next node on the wire, so it cannot wait for a load; the wait belongs* here, where the graph itself is being loaded. Acquired through the context, so* the prefab is owned by this era and given back when it retires.+ *+ * The graphs it CALLS are acquired the same way, and the acquisition IS where+ * their signature comes from: a caller's pins are the callee's declaration, so+ * one door hands back both the ownership and the shape.*/import type { AssetLoader, LoadContext, RegistryAssetLoader, ScriptGraphResult } from '../AssetLoader';import type { RegistryEra } from '../registryAssets';import { compileAgainstRegistry } from '../../logic/ScriptGraphAgent';-import { scriptGraphPrefabRefs } from '../../logic/nodes';+import {+ scriptGraphCallRefs, scriptGraphPrefabRefs, signatureOf, type ScriptGraphSignature,+} from '../../logic/nodes';import type { ScriptGraph } from '../../logic/types';import { log } from '../../util/logger';@@ -29,7 +35,18 @@ export class ScriptGraphAssetLoader implements AssetLoader<ScriptGraphResult> {prepare: async (path: string, ctx: LoadContext): Promise<RegistryEra<ScriptGraphResult>> => {const text = await ctx.loadText(ctx.catalog.getBuildPath(path));const graph = JSON.parse(text) as ScriptGraph;- const compiled = compileAgainstRegistry(graph);+ const signatures = new Map<string, ScriptGraphSignature>();+ for (const ref of scriptGraphCallRefs(graph)) {+ try {+ const called = await ctx.acquireAsset<ScriptGraphResult>(this.type, ref);+ if (called.value.signature) signatures.set(ref, called.value.signature);+ } catch (e) {+ // Reported, not thrown: a graph that will not load leaves its+ // call sites unmakeable and every other node still running.+ log.warn('logic', `${path}: graph "${ref}" did not load: ${String(e)}`);+ }+ }+ const compiled = compileAgainstRegistry(graph, signatures);for (const ref of scriptGraphPrefabRefs(graph)) {try {compiled.prefabs.set(ref, (await ctx.preparePrefab!(ref)).value);@@ -39,7 +56,7 @@ export class ScriptGraphAssetLoader implements AssetLoader<ScriptGraphResult> {log.warn('logic', `${path}: prefab "${ref}" did not prepare: ${String(e)}`);}}- return { published: compiled, value: { graphId: path } };+ return { published: compiled, value: { graphId: path, signature: signatureOf(graph) } };},};}diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 90cf00fdd..0a27a259d 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -1007,6 +1007,12 @@ export {sequenceCount,BUILTIN_NODE_KINDS,scriptGraphPrefabRefs,+ graphCallRef,+ scriptGraphCallRefs,+ isCallableGraph,+ signatureOf,+ scriptCatalog,+ MAX_CALL_DEPTH,compileScriptGraph,createScriptRunState,stepScriptGraph,@@ -1017,11 +1023,14 @@ export {type ScriptGraphNode,type ScriptGraphEdge,type ScriptGraphVariable,+ type ScriptGraphPort,type ScriptPort,type ScriptValue,type ScriptValueType,type ScriptNodeShape,type ScriptVerbCatalog,+ type ScriptGraphSignature,+ type ScriptFrame,type CompiledScriptGraph,type ScriptRunState,type ScriptTickContext,@@ -1048,6 +1057,10 @@ export {addScriptVariable,removeScriptVariable,renameScriptVariable,+ addScriptGraphPort,+ removeScriptGraphPort,+ renameScriptGraphPort,+ retypeScriptGraphPort,type ScriptGraphAgentData,} from './logic';diff --git a/sdk/src/logic/ScriptGraphAgent.ts b/sdk/src/logic/ScriptGraphAgent.tsindex 4cf7c4cb2..11693eab4 100644--- a/sdk/src/logic/ScriptGraphAgent.ts+++ b/sdk/src/logic/ScriptGraphAgent.ts@@ -15,6 +15,7 @@ import { aiRegistry } from '../ai/fsm/AiContext';import { ensureBuiltinAiRegistrations } from '../ai/builtins';import { ensureBuiltinScriptNodes } from './builtinNodes';import { compileScriptGraph, type CompiledScriptGraph } from './ScriptGraphRunner';+import { scriptCatalog, signatureOf, type ScriptGraphSignature } from './nodes';import type { ScriptGraph } from './types';export interface ScriptGraphAgentData {@@ -38,15 +39,24 @@ export const ScriptGraphAgent = defineComponent<ScriptGraphAgentData>('ScriptGra});/**- * Compile against the shared registry, having made sure the engine's own verbs- * are in it. A graph compiled before they registered would carry a problem for- * every built-in name it calls — and the compile happens at asset prepare, which- * can precede any plugin's build.+ * Compile against the shared registry, having first put the engine's own verbs+ * in it: the compile happens at asset prepare, which can precede any plugin's+ * build. `signatures` is what the graphs THIS one calls declare — a verb is a+ * process-wide registration, a called graph an asset of the realm.*/-export function compileAgainstRegistry(graph: ScriptGraph): CompiledScriptGraph {+export function compileAgainstRegistry(+ graph: ScriptGraph,+ signatures?: ReadonlyMap<string, ScriptGraphSignature>,+): CompiledScriptGraph {ensureBuiltinAiRegistrations();ensureBuiltinScriptNodes();- return compileScriptGraph(graph, aiRegistry);+ const catalog = scriptCatalog(aiRegistry, signatures);+ return compileScriptGraph(graph, {+ ...catalog,+ // A graph registered in CODE answers for itself, so two of them can call+ // each other without a loader in the picture.+ graphSignature: (ref) => catalog.graphSignature(ref) ?? storedSignature(ref),+ });}/**@@ -66,6 +76,12 @@ export function getScriptGraph(key: string): CompiledScriptGraph | undefined {return graphStore.get(key);}+/** The signature of a graph registered in code, for one calling it. */+function storedSignature(ref: string): ScriptGraphSignature | null {+ const compiled = graphStore.get(ref);+ return compiled ? signatureOf(compiled.graph) : null;+}+/** Every registered graph — what the schedule reads to learn this system's reach. */export function allScriptGraphs(): Iterable<CompiledScriptGraph> {return graphStore.values();diff --git a/sdk/src/logic/ScriptGraphPlugin.ts b/sdk/src/logic/ScriptGraphPlugin.tsindex 289ce0e30..3daa232ec 100644--- a/sdk/src/logic/ScriptGraphPlugin.ts+++ b/sdk/src/logic/ScriptGraphPlugin.ts@@ -104,6 +104,7 @@ export function stepScriptGraphs(ctx: ctx as AiContext, bb: st.bb, registry: aiRegistry, dt: delta,world: world as unknown as World,onProblem: message => onProblem?.(entity, message),+ ...(resolveGraph ? { resolveGraph } : {}),};};@@ -273,6 +274,7 @@ export class ScriptGraphPlugin implements Plugin {ctx: ctx as AiContext, bb: st.bb, registry: aiRegistry, dt: dt_,world: world as unknown as World,onProblem: message => onProblem(entity, message),+ resolveGraph,};});diff --git a/sdk/src/logic/ScriptGraphRunner.ts b/sdk/src/logic/ScriptGraphRunner.tsindex 3a1277323..f5deedcb2 100644Binary files a/sdk/src/logic/ScriptGraphRunner.ts and b/sdk/src/logic/ScriptGraphRunner.ts differdiff --git a/sdk/src/logic/graphOps.ts b/sdk/src/logic/graphOps.tsindex b9caccc87..b2b7fa630 100644--- a/sdk/src/logic/graphOps.ts+++ b/sdk/src/logic/graphOps.ts@@ -10,7 +10,10 @@* the same ones to a file somebody wrote by hand.*/-import { canConnect, type ScriptGraph, type ScriptGraphEdge, type ScriptGraphVariable, type ScriptValue } from './types';+import {+ canConnect,+ type ScriptGraph, type ScriptGraphEdge, type ScriptGraphPort, type ScriptGraphVariable, type ScriptValue,+} from './types';import { describeNode, type ScriptVerbCatalog } from './nodes';function clone(graph: ScriptGraph): ScriptGraph {@@ -150,6 +153,66 @@ export function removeScriptVariable(graph: ScriptGraph, name: string): ScriptGrreturn next;}+/**+ * Declare a port on this graph's signature — what a `graph.call` elsewhere will+ * show. The side is the author's choice, not a guess from the wires: a port with+ * nothing wired to it yet still has to exist to wire INTO.+ */+export function addScriptGraphPort(+ graph: ScriptGraph, side: 'inputs' | 'outputs', port: ScriptGraphPort,+): ScriptGraph {+ const next = clone(graph);+ next[side] ??= [];+ if (!next[side]!.some((p) => p.name === port.name)) next[side]!.push(port);+ return next;+}++/**+ * Drop a port. Wires that landed on it go with it — unlike a variable, whose+ * nodes stay readable, a pin that no longer exists has nowhere to draw an edge.+ */+export function removeScriptGraphPort(+ graph: ScriptGraph, side: 'inputs' | 'outputs', name: string,+): ScriptGraph {+ const next = clone(graph);+ next[side] = (next[side] ?? []).filter((p) => p.name !== name);+ const kind = side === 'inputs' ? 'graph.input' : 'graph.output';+ const ends = new Set(next.nodes.filter((n) => n.kind === kind).map((n) => n.id));+ next.edges = next.edges.filter((e) => !(+ side === 'inputs' ? ends.has(e.from) && e.fromPort === name : ends.has(e.to) && e.toPort === name+ ));+ return next;+}++/** Rename a port, carrying the wires on it along. */+export function renameScriptGraphPort(+ graph: ScriptGraph, side: 'inputs' | 'outputs', from: string, to: string,+): ScriptGraph {+ if (!to || from === to) return graph;+ const next = clone(graph);+ const port = (next[side] ?? []).find((p) => p.name === from);+ if (!port || (next[side] ?? []).some((p) => p.name === to)) return graph;+ port.name = to;+ const kind = side === 'inputs' ? 'graph.input' : 'graph.output';+ const ends = new Set(next.nodes.filter((n) => n.kind === kind).map((n) => n.id));+ for (const e of next.edges) {+ if (side === 'inputs' && ends.has(e.from) && e.fromPort === from) e.fromPort = to;+ if (side === 'outputs' && ends.has(e.to) && e.toPort === from) e.toPort = to;+ }+ return next;+}++/** Retype a port, dropping wires the new type cannot carry. */+export function retypeScriptGraphPort(+ graph: ScriptGraph, side: 'inputs' | 'outputs', name: string, type: ScriptGraphPort['type'],+): ScriptGraph {+ const next = clone(graph);+ const port = (next[side] ?? []).find((p) => p.name === name);+ if (!port || port.type === type) return graph;+ port.type = type;+ return next;+}+/** Rename a variable, carrying every node that names it along with it. */export function renameScriptVariable(graph: ScriptGraph, from: string, to: string): ScriptGraph {if (!to || from === to) return graph;diff --git a/sdk/src/logic/index.ts b/sdk/src/logic/index.tsindex 9f416af27..242848447 100644--- a/sdk/src/logic/index.ts+++ b/sdk/src/logic/index.ts@@ -20,6 +20,7 @@ export {type ScriptGraphNode,type ScriptGraphEdge,type ScriptGraphVariable,+ type ScriptGraphPort,type ScriptPort,type ScriptValue,type ScriptValueType,@@ -31,9 +32,15 @@ export {BUILTIN_NODE_KINDS,spawnPrefabRef,scriptGraphPrefabRefs,+ graphCallRef,+ scriptGraphCallRefs,+ isCallableGraph,+ signatureOf,+ scriptCatalog,THEN,type ScriptNodeShape,type ScriptVerbCatalog,+ type ScriptGraphSignature,} from './nodes';export {@@ -43,7 +50,9 @@ export {destroyScriptGraph,fireScriptGraphEvent,DEFAULT_STEP_BUDGET,+ MAX_CALL_DEPTH,type CompiledScriptGraph,+ type ScriptFrame,type ScriptRunState,type ScriptTickContext,} from './ScriptGraphRunner';@@ -86,4 +95,8 @@ export {addScriptVariable,removeScriptVariable,renameScriptVariable,+ addScriptGraphPort,+ removeScriptGraphPort,+ renameScriptGraphPort,+ retypeScriptGraphPort,} from './graphOps';diff --git a/sdk/src/logic/nodes.ts b/sdk/src/logic/nodes.tsindex 046c50fb4..ba7deecad 100644--- a/sdk/src/logic/nodes.ts+++ b/sdk/src/logic/nodes.ts@@ -14,7 +14,7 @@*/import type { AiOutputDef, AiParamDef } from '../ai/fsm/registry';-import type { ScriptGraph, ScriptGraphNode, ScriptPort, ScriptValueType } from './types';+import type { ScriptGraph, ScriptGraphNode, ScriptGraphPort, ScriptPort, ScriptValueType } from './types';/*** The registry, narrowed to what a shape needs. An `AiRegistry` satisfies it@@ -27,6 +27,55 @@ export interface ScriptVerbCatalog {getActionParams(name: string): readonly AiParamDef[];getActionOutputs(name: string): readonly AiOutputDef[];isActionPure(name: string): boolean;+ /**+ * The signature a callable graph declares, or null where this build has no+ * such graph. A called graph's pins come from the GRAPH, so changing its+ * signature redraws every caller rather than leaving them on a stale one.+ */+ graphSignature(ref: string): ScriptGraphSignature | null;+}++/** What a callable graph takes and hands back. */+export interface ScriptGraphSignature {+ inputs: readonly ScriptGraphPort[];+ outputs: readonly ScriptGraphPort[];+}++/**+ * Whether a call can ENTER this graph: it carries the node a call arrives at.+ * Declaring ports alone does not — a signature with nothing behind it is a+ * graph a caller would fall straight through.+ */+export function isCallableGraph(graph: ScriptGraph): boolean {+ return graph.nodes.some((n) => n.kind === 'graph.input');+}++/**+ * A catalog over a verb registry plus whatever graph signatures the caller+ * knows. Two sources because they have two owners: a verb is a process-wide+ * registration, a graph is an asset of the realm that loaded it.+ */+export function scriptCatalog(+ verbs: Omit<ScriptVerbCatalog, 'graphSignature'>,+ signatures?: ReadonlyMap<string, ScriptGraphSignature>,+): ScriptVerbCatalog {+ return {+ hasAction: (name) => verbs.hasAction(name),+ getActionParams: (name) => verbs.getActionParams(name),+ getActionOutputs: (name) => verbs.getActionOutputs(name),+ isActionPure: (name) => verbs.isActionPure(name),+ graphSignature: (ref) => signatures?.get(ref) ?? null,+ };+}++/** A graph's own signature, as a catalog answers it. */+export function signatureOf(graph: ScriptGraph): ScriptGraphSignature {+ return { inputs: graph.inputs ?? [], outputs: graph.outputs ?? [] };+}++/** A declared graph port as a node pin. */+function portOfSignature(p: ScriptGraphPort): ScriptPort {+ return { name: p.name, type: p.type, label: p.label };}/** A node's pins, plus the two facts the interpreter needs to place it. */@@ -148,6 +197,34 @@ export function describeNode(pure: false,};+ case 'graph.input':+ // Where a call ARRIVES. Not an entry: no occasion lights it, the+ // caller does — which is why it has no `entry` and still no exec in.+ return {+ execIn: false, execOut: [THEN], inputs: NO_PORTS,+ outputs: (graph.inputs ?? []).map(portOfSignature), pure: false,+ };+ case 'graph.output':+ // Where a call RETURNS. Control stops here: what follows is the+ // caller's next node, not this graph's.+ return {+ execIn: true, execOut: [],+ inputs: (graph.outputs ?? []).map(portOfSignature), outputs: NO_PORTS, pure: false,+ };+ case 'graph.call': {+ // A built-in rather than a registered verb, for the reason+ // `entity.spawn` is one: a graph is an ASSET of the realm that+ // loaded it, and the registry is process-wide.+ const signature = catalog.graphSignature(graphCallRef(node));+ if (!signature) return null;+ return {+ execIn: true, execOut: [THEN],+ inputs: signature.inputs.map(portOfSignature),+ outputs: signature.outputs.map(portOfSignature),+ pure: false,+ };+ }+case 'var.get':return {execIn: false, execOut: [], inputs: NO_PORTS,@@ -185,11 +262,15 @@ export function describeNode(return null;}-/** Every built-in kind, for the editor palette. `call` is not one — it is a name. */+/**+ * Every built-in kind, for the editor palette. `call` is not one — it is a+ * name; nor is `graph.call`, which is a GRAPH, listed the way the verbs are.+ */export const BUILTIN_NODE_KINDS: readonly string[] = ['event.start', 'event.update', 'event.destroy', 'event.on','flow.branch', 'flow.sequence', 'flow.while', 'flow.delay','entity.spawn',+ 'graph.input', 'graph.output','var.get', 'var.set','lit.number', 'lit.bool', 'lit.string',];@@ -203,9 +284,25 @@ export function spawnPrefabRef(node: ScriptGraphNode): string {/** Every prefab a graph may spawn, deduplicated, in document order. */export function scriptGraphPrefabRefs(graph: ScriptGraph): string[] {+ return refsOf(graph, spawnPrefabRef);+}++/** The graph a `graph.call` node calls, or '' — the same single-reader rule+ * {@link spawnPrefabRef} keeps, so the loader and the compile step cannot+ * disagree about which graphs this one needs. */+export function graphCallRef(node: ScriptGraphNode): string {+ return node.kind === 'graph.call' ? String(node.literals?.graph ?? '') : '';+}++/** Every graph this one may call, deduplicated, in document order. */+export function scriptGraphCallRefs(graph: ScriptGraph): string[] {+ return refsOf(graph, graphCallRef);+}++function refsOf(graph: ScriptGraph, of: (node: ScriptGraphNode) => string): string[] {const out: string[] = [];for (const node of graph.nodes) {- const ref = spawnPrefabRef(node);+ const ref = of(node);if (ref && !out.includes(ref)) out.push(ref);}return out;diff --git a/sdk/src/logic/types.ts b/sdk/src/logic/types.tsindex f0fe35d6a..2c1de191e 100644--- a/sdk/src/logic/types.ts+++ b/sdk/src/logic/types.ts@@ -9,10 +9,11 @@* ships are the same bytes (the `.esbt` contract).** What a node's PORTS are is deliberately absent from the file. A port list- * comes from the node's kind (the built-in table) or, for a `call`, from what- * the name declared to the registry — one author, two readers (the interpreter- * and the canvas). Written into the file it would be a second author, and an- * old file would keep drawing a port its verb no longer has.+ * comes from the node's kind (the built-in table), from what a `call`'s name+ * declared to the registry, or from what a called GRAPH declares — one author,+ * two readers (the interpreter and the canvas). Written into the file it would+ * be a second author, and an old file would keep drawing a port its verb no+ * longer has.*//** What a wire carries. `exec` is the control wire; the rest are data. */@@ -55,6 +56,19 @@ export interface ScriptGraphEdge {toPort: string;}+/**+ * One port of a callable graph — its side of the signature. The node calling it+ * reads this, which is why a graph's ports live on the graph and not on the+ * call: change the signature and every caller is redrawn from it.+ */+export interface ScriptGraphPort {+ name: string;+ type: Exclude<ScriptValueType, 'exec'>;+ label?: string;+ /** What an unwired input carries into the call. */+ default?: ScriptValue;+}+/** A graph-local variable: declared by the asset, valued per entity. */export interface ScriptGraphVariable {name: string;@@ -65,11 +79,19 @@ export interface ScriptGraphVariable {export interface ScriptGraph {version: string;name?: string;+ /**+ * Declaring either side makes this graph CALLABLE: a `graph.call` elsewhere+ * gets these as its pins. A graph with neither is only ever ticked by the+ * occasions its entry nodes name.+ */+ inputs?: ScriptGraphPort[];+ outputs?: ScriptGraphPort[];variables?: ScriptGraphVariable[];nodes: ScriptGraphNode[];edges: ScriptGraphEdge[];}+export const SCRIPT_GRAPH_VERSION = '1.0';/** An empty graph, the shape "New Script Graph" writes. */diff --git a/sdk/tests/script-graph-agent.test.ts b/sdk/tests/script-graph-agent.test.tsindex 238d75886..e36365e2a 100644--- a/sdk/tests/script-graph-agent.test.ts+++ b/sdk/tests/script-graph-agent.test.ts@@ -19,6 +19,7 @@ import {} from '../src/logic/ScriptGraphPlugin';import { ensureBuiltinScriptNodes } from '../src/logic/builtinNodes';import { SCRIPT_GRAPH_VERSION, type ScriptGraph } from '../src/logic/types';+import { scriptCatalog } from '../src/logic/nodes';import { compileScriptGraph } from '../src/logic/ScriptGraphRunner';interface HealthData { value: number }@@ -212,7 +213,7 @@ describe('what the system reaches for comes from the graphs, not the system', (){ id: 'b', kind: 'flow.branch' },],[],- ), aiRegistry);+ ), scriptCatalog(aiRegistry));expect([...scriptGraphLeaves(compiled)]).toEqual([{ kind: 'action', name: 'test.hit' }]);});});diff --git a/sdk/tests/script-graph-call.test.ts b/sdk/tests/script-graph-call.test.tsnew file mode 100644index 000000000..db6eb6b33--- /dev/null+++ b/sdk/tests/script-graph-call.test.ts@@ -0,0 +1,362 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file script-graph-call.test.ts+ * @brief One graph calling another: the signature, the frame, and the two+ * ways a call has to stop rather than take the process with it.+ *+ * A call runs the callee to completion inside the caller's step, so+ * what is held here is that arguments arrive, results come back, the+ * callee's variables belong to the CALL SITE, and a graph that calls+ * itself is stopped by a depth rather than by the JS stack.+ */+import { describe, it, expect } from 'vitest';+import { AiRegistry } from '../src/ai/fsm/registry';+import { Blackboard } from '../src/ai/fsm/Blackboard';+import {+ compileScriptGraph, createScriptRunState, stepScriptGraph, MAX_CALL_DEPTH,+ type CompiledScriptGraph, type ScriptTickContext,+} from '../src/logic/ScriptGraphRunner';+import { scriptCatalog, signatureOf, type ScriptGraphSignature } from '../src/logic/nodes';+import {+ SCRIPT_GRAPH_VERSION,+ type ScriptGraph, type ScriptGraphEdge, type ScriptGraphNode, type ScriptGraphPort,+} from '../src/logic/types';++interface TestCtx { log: string[]; }++function registry(): AiRegistry<TestCtx> {+ const reg = new AiRegistry<TestCtx>();+ reg.registerAction('test.say', {+ params: [{ name: 'text', type: 'string' }],+ run: (ctx, _bb, _arg, params) => { ctx.log.push(String(params?.text ?? '')); },+ });+ reg.registerValue('test.add', {+ params: [{ name: 'a', type: 'number' }, { name: 'b', type: 'number' }],+ outputs: [{ name: 'sum', type: 'number' }],+ evaluate: (_ctx, _bb, params, out) => { out.sum = Number(params.a ?? 0) + Number(params.b ?? 0); },+ });+ return reg;+}++const node = (id: string, kind: string, extra: Partial<ScriptGraphNode> = {}): ScriptGraphNode =>+ ({ id, kind, ...extra });+const edge = (from: string, fromPort: string, to: string, toPort: string): ScriptGraphEdge =>+ ({ id: `${from}.${fromPort}->${to}.${toPort}`, from, fromPort, to, toPort });++function graphOf(+ nodes: ScriptGraphNode[],+ edges: ScriptGraphEdge[],+ extra: Partial<Pick<ScriptGraph, 'inputs' | 'outputs' | 'variables'>> = {},+): ScriptGraph {+ return { version: SCRIPT_GRAPH_VERSION, nodes, edges, ...extra };+}++interface Suite {+ log: string[];+ problems: string[];+ tick(dt?: number): void;+ halted(): boolean;+}++/**+ * Compile a whole set of graphs against each other, the way a loader does: each+ * one's signature is available to whoever calls it, and a call resolves by name+ * at run time.+ */+function suite(+ graphs: Record<string, ScriptGraph>,+ entry: string,+ opts: { budget?: number; unloaded?: readonly string[] } = {},+): Suite {+ const reg = registry();+ const signatures = new Map<string, ScriptGraphSignature>();+ for (const [key, g] of Object.entries(graphs)) signatures.set(key, signatureOf(g));++ const compiled = new Map<string, CompiledScriptGraph>();+ const problems: string[] = [];+ for (const [key, g] of Object.entries(graphs)) {+ const c = compileScriptGraph(g, scriptCatalog(reg, signatures));+ compiled.set(key, c);+ problems.push(...c.problems);+ }++ const root = compiled.get(entry)!;+ // A graph whose SIGNATURE this build knew at compile time but which is not+ // there to run — an asset the realm no longer holds.+ for (const key of opts.unloaded ?? []) compiled.delete(key);+ const state = createScriptRunState(root);+ const ctx: TestCtx = { log: [] };+ const tickCtx = (dt: number): ScriptTickContext<TestCtx> => ({+ ctx, bb: new Blackboard(), registry: reg, dt,+ onProblem: (m) => problems.push(m),+ resolveGraph: (ref) => compiled.get(ref),+ ...(opts.budget === undefined ? {} : { budget: opts.budget }),+ });+ return {+ log: ctx.log,+ problems,+ tick: (dt = 1 / 60) => stepScriptGraph(root, state, tickCtx(dt)),+ halted: () => state.halted,+ };+}++const NUM = (name: string): ScriptGraphPort => ({ name, type: 'number' });++/** A callable graph: `sum = a + b`, and it says so in the log. */+function adder(): ScriptGraph {+ return graphOf([+ node('in', 'graph.input'),+ node('say', 'call', { ref: 'test.say', literals: { text: 'added' } }),+ node('add', 'call', { ref: 'test.add' }),+ node('out', 'graph.output'),+ ], [+ edge('in', 'then', 'say', ''),+ edge('say', 'then', 'out', ''),+ edge('in', 'a', 'add', 'a'),+ edge('in', 'b', 'add', 'b'),+ edge('add', 'sum', 'out', 'sum'),+ ], { inputs: [NUM('a'), NUM('b')], outputs: [NUM('sum')] });+}++describe('a graph calling another graph', () => {+ it('hands the arguments in and reads the results back', () => {+ const s = suite({+ adder: adder(),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'adder', a: 2, b: 5 } }),+ node('say', 'call', { ref: 'test.say' }),+ ], [+ edge('start', 'then', 'call', ''),+ edge('call', 'then', 'say', ''),+ edge('call', 'sum', 'say', 'text'),+ ]),+ }, 'main');++ s.tick();++ expect(s.problems).toEqual([]);+ // The callee ran, and its result came back up the wire as a value the+ // caller could use.+ expect(s.log).toEqual(['added', '7']);+ });++ it('gives each call site its own variables', () => {+ // A counter graph: bump its own variable and report it back. Two call+ // sites must not be counting the same thing — a callee's state belongs+ // to the call site, the way an entity's graph belongs to the entity.+ const counter = graphOf([+ node('in', 'graph.input'),+ node('bump', 'var.set', { literals: { name: 'n' } }),+ node('add', 'call', { ref: 'test.add', literals: { b: 1 } }),+ node('get', 'var.get', { literals: { name: 'n' } }),+ node('out', 'graph.output'),+ ], [+ edge('in', 'then', 'bump', ''),+ edge('get', 'value', 'add', 'a'),+ edge('add', 'sum', 'bump', 'value'),+ edge('bump', 'then', 'out', ''),+ edge('get', 'value', 'out', 'n'),+ ], { outputs: [NUM('n')], variables: [{ name: 'n', type: 'number', default: 0 }] });++ const s = suite({+ counter,+ main: graphOf([+ node('upd', 'event.update'),+ node('c1', 'graph.call', { literals: { graph: 'counter' } }),+ node('s1', 'call', { ref: 'test.say' }),+ node('c2', 'graph.call', { literals: { graph: 'counter' } }),+ node('s2', 'call', { ref: 'test.say' }),+ ], [+ edge('upd', 'then', 'c1', ''),+ edge('c1', 'then', 's1', ''),+ edge('c1', 'n', 's1', 'text'),+ edge('s1', 'then', 'c2', ''),+ edge('c2', 'then', 's2', ''),+ edge('c2', 'n', 's2', 'text'),+ ]),+ }, 'main');++ s.tick();+ s.tick();++ expect(s.problems).toEqual([]);+ // Each site counts 1 then 2: its own variable, kept between calls the+ // way an entity's graph keeps its own. One shared variable would count+ // 1, 2, 3, 4.+ expect(s.log).toEqual(['1', '1', '2', '2']);+ });++ it('refuses to compile a call naming a graph nothing declares', () => {+ const s = suite({+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'missing' } }),+ node('after', 'call', { ref: 'test.say', literals: { text: 'after' } }),+ ], [+ edge('start', 'then', 'call', ''),+ edge('call', 'then', 'after', ''),+ ]),+ }, 'main');++ s.tick();++ // No signature, no pins — the node is one this build cannot make, so+ // control never reaches what was wired after it.+ expect(s.log).toEqual([]);+ expect(s.problems.join('\n')).toMatch(/no graph "missing"/);+ });++ it('stops at a call whose graph is declared but not loaded', () => {+ // The other half: the signature was there when this compiled, and the+ // asset is not there to run. Control still stops — the next node was+ // going to read results nothing produced.+ const s = suite({+ adder: adder(),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'adder', a: 1, b: 1 } }),+ node('after', 'call', { ref: 'test.say', literals: { text: 'after' } }),+ ], [+ edge('start', 'then', 'call', ''),+ edge('call', 'then', 'after', ''),+ ]),+ }, 'main', { unloaded: ['adder'] });++ s.tick();++ expect(s.log).toEqual([]);+ expect(s.problems.join('\n')).toMatch(/is not loaded/);+ });++ it('stops at a graph with no way in', () => {+ const s = suite({+ noEntry: graphOf([node('say', 'call', { ref: 'test.say', literals: { text: 'x' } })], []),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'noEntry' } }),+ node('after', 'call', { ref: 'test.say', literals: { text: 'after' } }),+ ], [+ edge('start', 'then', 'call', ''),+ edge('call', 'then', 'after', ''),+ ]),+ }, 'main');++ s.tick();++ expect(s.log).toEqual([]);+ expect(s.problems.join('\n')).toMatch(/no graph\.input/);+ });++ it('stops a graph that calls itself, at a depth rather than on the stack', () => {+ const s = suite({+ loop: graphOf([+ node('in', 'graph.input'),+ node('again', 'graph.call', { literals: { graph: 'loop' } }),+ ], [edge('in', 'then', 'again', '')]),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'loop' } }),+ ], [edge('start', 'then', 'call', '')]),+ }, 'main');++ expect(() => s.tick()).not.toThrow();+ expect(s.halted()).toBe(true);+ expect(s.problems.join('\n')).toMatch(new RegExp(`deeper than ${MAX_CALL_DEPTH}`));+ });++ it('spends the callers budget, so a runaway callee stops the instance', () => {+ // The callee loops forever. The budget belongs to the INSTANCE, not to+ // each graph, or a caller could buy an unbounded amount of work by+ // calling one that never returns.+ const s = suite({+ spin: graphOf([+ node('in', 'graph.input'),+ node('loop', 'flow.while', { literals: { cond: true } }),+ node('body', 'call', { ref: 'test.say', literals: { text: '.' } }),+ ], [+ edge('in', 'then', 'loop', ''),+ edge('loop', 'body', 'body', ''),+ ]),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'spin' } }),+ ], [edge('start', 'then', 'call', '')]),+ }, 'main', { budget: 50 });++ s.tick();++ expect(s.halted()).toBe(true);+ expect(s.log.length).toBeLessThanOrEqual(50);+ expect(s.problems.join('\n')).toMatch(/step budget/);+ });++ it('charges every call to the same budget', () => {+ // Two calls of a graph that costs 5 steps, against a budget of 10. One+ // budget per INSTANCE: a fresh one per callee would buy unbounded work+ // by calling often instead of looping.+ const work = graphOf([+ node('in', 'graph.input'),+ node('seq', 'flow.sequence', { literals: { count: 4 } }),+ node('a', 'call', { ref: 'test.say', literals: { text: 'a' } }),+ node('b', 'call', { ref: 'test.say', literals: { text: 'b' } }),+ node('c', 'call', { ref: 'test.say', literals: { text: 'c' } }),+ node('d', 'call', { ref: 'test.say', literals: { text: 'd' } }),+ ], [+ edge('in', 'then', 'seq', ''),+ edge('seq', '0', 'a', ''), edge('seq', '1', 'b', ''),+ edge('seq', '2', 'c', ''), edge('seq', '3', 'd', ''),+ ]);+ const s = suite({+ work,+ main: graphOf([+ node('start', 'event.start'),+ node('c1', 'graph.call', { literals: { graph: 'work' } }),+ node('c2', 'graph.call', { literals: { graph: 'work' } }),+ ], [+ edge('start', 'then', 'c1', ''),+ edge('c1', 'then', 'c2', ''),+ ]),+ }, 'main', { budget: 10 });++ s.tick();++ expect(s.halted()).toBe(true);+ expect(s.log.length).toBeLessThan(8);+ expect(s.problems.join('\n')).toMatch(/step budget/);+ });++ it('refuses a wait inside a graph a call enters', () => {+ const s = suite({+ waiter: graphOf([+ node('in', 'graph.input'),+ node('wait', 'flow.delay', { literals: { seconds: 1 } }),+ node('say', 'call', { ref: 'test.say', literals: { text: 'late' } }),+ ], [+ edge('in', 'then', 'wait', ''),+ edge('wait', 'then', 'say', ''),+ ]),+ main: graphOf([+ node('start', 'event.start'),+ node('call', 'graph.call', { literals: { graph: 'waiter' } }),+ ], [edge('start', 'then', 'call', '')]),+ }, 'main');++ s.tick();++ // There is no later tick for the timer to expire on: the call returns+ // within its caller's step. So the node is one this build cannot make.+ expect(s.problems.join('\n')).toMatch(/cannot wait/);+ expect(s.log).toEqual([]);+ });++ it('refuses a second way in', () => {+ const s = suite({+ two: graphOf([node('in', 'graph.input'), node('in2', 'graph.input')], []),+ main: graphOf([], []),+ }, 'main');++ expect(s.problems.join('\n')).toMatch(/a second graph\.input/);+ });+});diff --git a/sdk/tests/script-graph-corpus.test.ts b/sdk/tests/script-graph-corpus.test.tsindex e362a7a38..31890127e 100644--- a/sdk/tests/script-graph-corpus.test.ts+++ b/sdk/tests/script-graph-corpus.test.ts@@ -19,6 +19,7 @@ import { aiRegistry } from '../src/ai/fsm/AiContext';import { ensureBuiltinAiRegistrations } from '../src/ai/builtins';import { ensureBuiltinScriptNodes } from '../src/logic/builtinNodes';import { compileScriptGraph } from '../src/logic/ScriptGraphRunner';+import { isCallableGraph, scriptCatalog, signatureOf, type ScriptGraphSignature } from '../src/logic/nodes';import type { ScriptGraph } from '../src/logic/types';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');@@ -53,18 +54,30 @@ describe('the shipped script graphs', () => {expect(files.length).toBeGreaterThan(0);});+ // The signatures a caller compiles against, gathered the way the loader+ // gathers them: off the files, keyed by the project-relative ref a node+ // spells. Without this a graph that calls another reads as a broken one.+ const signatures = new Map<string, ScriptGraphSignature>();+ for (const file of files) {+ const graph = JSON.parse(readFileSync(file, 'utf8')) as ScriptGraph;+ const projectDir = file.slice(0, file.indexOf(`${path.sep}assets${path.sep}`));+ signatures.set(path.relative(projectDir, file).split(path.sep).join('/'), signatureOf(graph));+ }+for (const file of files) {const rel = path.relative(ROOT, file);it(`${rel} compiles with nothing missing`, () => {const graph = JSON.parse(readFileSync(file, 'utf8')) as ScriptGraph;- const compiled = compileScriptGraph(graph, aiRegistry);+ const compiled = compileScriptGraph(graph, scriptCatalog(aiRegistry, signatures));const problems = compiled.problems.filter((p) => !PROJECT_PREFIX.test(p.split('"')[1] ?? ''));expect(problems).toEqual([]);// A graph nothing can start is a picture. Every one of these ships as- // behaviour, so every one owes an entry.+ // behaviour, so every one owes a way in — an occasion that lights it,+ // or the node a call arrives at.const entries = compiled.starts.length + compiled.updates.length+ compiled.destroys.length + compiled.events.size;- expect(entries, 'no entry node — nothing would ever run it').toBeGreaterThan(0);+ const reachable = entries > 0 || isCallableGraph(graph);+ expect(reachable, 'no entry node and no graph.input — nothing would ever run it').toBe(true);});}});diff --git a/sdk/tests/script-graph-loader.test.ts b/sdk/tests/script-graph-loader.test.tsnew file mode 100644index 000000000..92122442f--- /dev/null+++ b/sdk/tests/script-graph-loader.test.ts@@ -0,0 +1,103 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file script-graph-loader.test.ts+ * @brief What loading a `.esgraph` has to do before it is runnable: acquire+ * the graphs it calls, and compile its call nodes against what THEY+ * declare.+ *+ * A caller's pins are the callee's declaration, so the two facts have+ * to arrive together. Reading the callee's file a second time is not+ * the same thing — one door resolves a ref that the other cannot, and+ * the shape of that failure is a game where nothing moves.+ */+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { ScriptGraphAssetLoader } from '../src/asset/loaders/ScriptGraphAssetLoader';+import type { LoadContext, ScriptGraphResult } from '../src/asset/AssetLoader';+import type { CompiledScriptGraph } from '../src/logic/ScriptGraphRunner';+import type { AssetLease } from '../src/asset/AssetLease';+import { aiRegistry } from '../src/ai/fsm/AiContext';+import { signatureOf } from '../src/logic/nodes';+import { SCRIPT_GRAPH_VERSION, type ScriptGraph } from '../src/logic/types';++const CALLEE: ScriptGraph = {+ version: SCRIPT_GRAPH_VERSION,+ name: 'Callee',+ inputs: [{ name: 'speed', type: 'number' }],+ outputs: [{ name: 'ok', type: 'bool' }],+ nodes: [{ id: 'in', kind: 'graph.input' }, { id: 'out', kind: 'graph.output' }],+ edges: [{ id: 'e', from: 'in', fromPort: 'then', to: 'out', toPort: '' }],+};++const CALLER: ScriptGraph = {+ version: SCRIPT_GRAPH_VERSION,+ name: 'Caller',+ nodes: [+ { id: 'upd', kind: 'event.update' },+ { id: 'call', kind: 'graph.call', literals: { graph: 'lib/callee.esgraph' } },+ ],+ edges: [{ id: 'e', from: 'upd', fromPort: 'then', to: 'call', toPort: '' }],+};++/** A lease over a value, with the ledger parts a loader never looks at. */+function lease<T>(value: T): AssetLease<T> {+ return { key: 'k', generation: 1, value, release: () => {}, split: () => null } as unknown as AssetLease<T>;+}++function context(acquire: (type: string, ref: string) => Promise<AssetLease<unknown>>): LoadContext {+ return {+ catalog: { getBuildPath: (p: string) => p },+ loadText: async () => JSON.stringify(CALLER),+ acquireAsset: acquire,+ preparePrefab: async () => lease({}),+ } as unknown as LoadContext;+}++/** The era a prepare publishes, with `published` named for what it is. */+async function prepare(path: string, ctx: LoadContext) {+ const era = await new ScriptGraphAssetLoader().registry.prepare(path, ctx);+ return { published: era.published as CompiledScriptGraph, value: era.value };+}++beforeEach(() => {+ aiRegistry.clear();+});++describe('loading a graph that calls another', () => {+ it('takes the callee signature off the acquisition, and compiles the call against it', async () => {+ const acquire = vi.fn(async (_type: string, _ref: string) =>+ lease<ScriptGraphResult>({ graphId: 'lib/callee.esgraph', signature: signatureOf(CALLEE) }));++ const era = await prepare('logic/caller.esgraph', context(acquire));++ // The callee is OWNED by this era, not merely read: the graph a call+ // enters has to still be there when the call runs.+ expect(acquire).toHaveBeenCalledWith('scriptgraph', 'lib/callee.esgraph');+ expect(era.published.problems).toEqual([]);+ const shape = era.published.shapes.get('call');+ expect(shape?.inputs).toEqual([{ name: 'speed', type: 'number', label: undefined }]);+ expect(shape?.outputs).toEqual([{ name: 'ok', type: 'bool', label: undefined }]);+ });++ it('publishes its own signature, which is what a caller of IT will read', async () => {+ const acquire = vi.fn(async () => lease<ScriptGraphResult>({ graphId: 'x' }));+ const ctx = context(acquire);+ (ctx as unknown as { loadText: () => Promise<string> }).loadText = async () => JSON.stringify(CALLEE);++ const era = await prepare('lib/callee.esgraph', ctx);++ expect(era.value.signature).toEqual(signatureOf(CALLEE));+ });++ it('leaves one unloadable call unmakeable and the rest of the graph intact', async () => {+ const acquire = vi.fn(async () => { throw new Error('404'); });++ const era = await prepare('logic/caller.esgraph', context(acquire));++ // The entry still compiled; only the node naming a graph this build+ // could not get is missing, and it says so.+ expect(era.published.updates).toEqual(['upd']);+ expect(era.published.shapes.has('call')).toBe(false);+ expect(era.published.problems.join('\n')).toMatch(/no graph "lib\/callee\.esgraph"/);+ });+});diff --git a/sdk/tests/script-graph-ops.test.ts b/sdk/tests/script-graph-ops.test.tsindex a3660b7cb..b2cf8f5f9 100644--- a/sdk/tests/script-graph-ops.test.ts+++ b/sdk/tests/script-graph-ops.test.ts@@ -10,6 +10,7 @@*/import { describe, it, expect } from 'vitest';import { AiRegistry } from '../src/ai/fsm/registry';+import { scriptCatalog, type ScriptVerbCatalog } from '../src/logic/nodes';import {addScriptNode, moveScriptNode, removeScriptNode, setScriptNodeLiteral,canConnectPorts, connectScriptNodes, disconnectScriptInput, removeScriptEdge,@@ -18,7 +19,7 @@ import {import { emptyScriptGraph, type ScriptGraph } from '../src/logic/types';import { describeNode } from '../src/logic/nodes';-function catalog(): AiRegistry<unknown> {+function catalog(): ScriptVerbCatalog {const reg = new AiRegistry<unknown>();reg.registerAction('demo.say', {params: [{ name: 'text', type: 'string' }],@@ -32,11 +33,11 @@ function catalog(): AiRegistry<unknown> {outputs: [{ name: 'on', type: 'bool' }],evaluate: (_c, _b, _p, out) => { out.on = true; },});- return reg;+ return scriptCatalog(reg);}/** start → say, with a count feeding the text. */-function scene(): { graph: ScriptGraph; reg: AiRegistry<unknown> } {+function scene(): { graph: ScriptGraph; reg: ScriptVerbCatalog } {const reg = catalog();let graph = emptyScriptGraph('demo');graph = addScriptNode(graph, 'event.start', 0, 0).graph;diff --git a/sdk/tests/script-graph-runner.test.ts b/sdk/tests/script-graph-runner.test.tsindex e743cf198..63d29c148 100644--- a/sdk/tests/script-graph-runner.test.ts+++ b/sdk/tests/script-graph-runner.test.ts@@ -16,7 +16,7 @@ import {fireScriptGraphEvent, type ScriptTickContext,} from '../src/logic/ScriptGraphRunner';import { SCRIPT_GRAPH_VERSION, type ScriptGraph, type ScriptGraphEdge, type ScriptGraphNode } from '../src/logic/types';-import { scriptGraphPrefabRefs } from '../src/logic/nodes';+import { scriptCatalog, scriptGraphPrefabRefs } from '../src/logic/nodes';interface TestCtx { log: string[]; }@@ -72,7 +72,7 @@ interface Run {}function run(graph: ScriptGraph, reg: AiRegistry<TestCtx>, budget?: number): Run {- const compiled = compileScriptGraph(graph, reg);+ const compiled = compileScriptGraph(graph, scriptCatalog(reg));const state = createScriptRunState(compiled);const ctx: TestCtx = { log: [] };const problems: string[] = [...compiled.problems];@@ -432,3 +432,21 @@ function runOnce(g: ScriptGraph, reg: AiRegistry<TestCtx>): string[] {r.tick();return r.log;}++describe('a graph whose file contradicts itself', () => {+ it('reports two nodes under one id instead of letting one replace the other', () => {+ const { reg } = registry();+ const g = graphOf([+ node('start', 'event.start'),+ node('twin', 'call', { ref: 'test.say', literals: { text: 'first' } }),+ node('twin', 'call', { ref: 'test.say', literals: { text: 'second' } }),+ ], [edge('start', 'then', 'twin', '')]);++ const r = run(g, reg);+ r.tick();++ // Every lookup here is by id, so the second would quietly become the+ // node every wire drawn to either one lands on.+ expect(r.problems.join('\n')).toMatch(/a second node carries this id/);+ });+});diff --git a/sdk/tests/script-graph-shape.test.ts b/sdk/tests/script-graph-shape.test.tsindex 6c7d0aae2..606e11508 100644--- a/sdk/tests/script-graph-shape.test.ts+++ b/sdk/tests/script-graph-shape.test.ts@@ -9,10 +9,14 @@*/import { describe, it, expect } from 'vitest';import { AiRegistry } from '../src/ai/fsm/registry';-import { describeNode, BUILTIN_NODE_KINDS } from '../src/logic/nodes';+import {+ describeNode, scriptCatalog, signatureOf, BUILTIN_NODE_KINDS,+ type ScriptGraphSignature, type ScriptVerbCatalog,+} from '../src/logic/nodes';import { canConnect, coerceValue, emptyScriptGraph, type ScriptGraph } from '../src/logic/types';-const catalog = (): AiRegistry<unknown> => {+/** The verbs, plus whatever graphs a caller is told about. */+const catalog = (graphs?: ReadonlyMap<string, ScriptGraphSignature>): ScriptVerbCatalog => {const reg = new AiRegistry<unknown>();reg.registerAction('demo.move', {params: [{ name: 'speed', type: 'number' }, { name: 'mode', type: 'enum' }],@@ -23,7 +27,7 @@ const catalog = (): AiRegistry<unknown> => {outputs: [{ name: 'meters', type: 'number' }],evaluate: (_c, _b, _p, out) => { out.meters = 1; },});- return reg;+ return scriptCatalog(reg, graphs);};const graph = (over: Partial<ScriptGraph> = {}): ScriptGraph => ({ ...emptyScriptGraph(), ...over });@@ -116,3 +120,40 @@ describe('coerceValue is the runtime half of canConnect', () => {expect(coerceValue(null, 'number')).toBeNull();});});++describe('a graph.call node takes its pins from the graph it names', () => {+ const called = { ...emptyScriptGraph(), inputs: [{ name: 'speed', type: 'number' as const }], outputs: [{ name: 'ok', type: 'bool' as const }] };+ const known = new Map([['moves.esgraph', signatureOf(called)]]);++ it('mirrors the callee signature, with an exec pin of its own', () => {+ const shape = describeNode(+ { id: 'n', kind: 'graph.call', literals: { graph: 'moves.esgraph' } },+ graph(), catalog(known),+ );+ expect(shape?.inputs).toEqual([{ name: 'speed', type: 'number', label: undefined }]);+ expect(shape?.outputs).toEqual([{ name: 'ok', type: 'bool', label: undefined }]);+ expect(shape?.execIn).toBe(true);+ expect(shape?.execOut).toEqual(['then']);+ // Never pure: a graph runs statements, so it sequences like one.+ expect(shape?.pure).toBe(false);+ });++ it('is null for a graph this build was told nothing about', () => {+ expect(describeNode(+ { id: 'n', kind: 'graph.call', literals: { graph: 'gone.esgraph' } },+ graph(), catalog(known),+ )).toBeNull();+ });++ it('gives the entry and exit nodes the pins the graph declares', () => {+ const inShape = describeNode({ id: 'in', kind: 'graph.input' }, graph(called), catalog());+ expect(inShape?.outputs).toEqual([{ name: 'speed', type: 'number', label: undefined }]);+ // A call arrives here; no occasion lights it, so it takes no exec wire.+ expect(inShape?.execIn).toBe(false);++ const outShape = describeNode({ id: 'out', kind: 'graph.output' }, graph(called), catalog());+ expect(outShape?.inputs).toEqual([{ name: 'ok', type: 'bool', label: undefined }]);+ // Control stops here: what runs next belongs to the caller.+ expect(outShape?.execOut).toEqual([]);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex c99cf3342..6e94f7bd7 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(logic): a graph can call another graph, and pay for it out of one budget':+ { note: 'A graph can call another graph.' },++ 'feat(logic): a signature to declare and a graph to call, on the shared canvas':+ { note: 'A graph can call another graph.' },+'feat(scene): a graph can change the scene, through the door every surface holds':{ note: 'A graph can change the scene.' },