Skip to content

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.

feat(logic): a graph can call another graph, and pay for it out of one budget

esengine7867fd049d40
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
block 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 no
component can express — the write would retire the world the component lives
in — 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 AudioSource
off, clearing its clip, or removing the component dropped the handle to the
voice WITHOUT stopping it. The sound kept playing with nothing anywhere able
diff --git a/desktop b/desktop
index ba6df0552..2554554ac 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ba6df055252c0b57d7620cf524c03e939d1dd84b
+Subproject commit 2554554ac62f5c79bc9ddddb75521d4386a5d99d
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.esgraph
new file mode 100644
index 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.meta
new file mode 100644
index 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.esgraph
index 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.esgraph
index 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.esgraph
index 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.md
index 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 | undefined
nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
prefabs: 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 | undefined
scaleMode: 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[] | undefined
name: string | undefined
nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
variables: ScriptGraphVariable[] | undefined
version: string
```
@@ -8075,6 +8092,20 @@ static new (): ScriptGraphPlugin
static 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: boolean
produced: Map<string, Record<string, ScriptValue>>
reported: Set<string>
@@ -8127,6 +8159,7 @@ ctx: Ctx
dt: number
onProblem: ((message: string) => void) | undefined
registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
world: World | undefined
```
@@ -8144,6 +8177,7 @@ boolean | number | string | null
```
getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
hasAction: (name: string) => boolean
isActionPure: (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): TileStamp
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | undefined
nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
prefabs: 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 | undefined
scaleMode: 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[] | undefined
name: string | undefined
nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
variables: ScriptGraphVariable[] | undefined
version: string
```
@@ -8268,6 +8285,20 @@ static new (): ScriptGraphPlugin
static 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: boolean
produced: Map<string, Record<string, ScriptValue>>
reported: Set<string>
@@ -8320,6 +8352,7 @@ ctx: Ctx
dt: number
onProblem: ((message: string) => void) | undefined
registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
world: World | undefined
```
@@ -8337,6 +8370,7 @@ boolean | number | string | null
```
getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
hasAction: (name: string) => boolean
isActionPure: (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): TileStamp
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | undefined
nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
prefabs: 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 | undefined
scaleMode: 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[] | undefined
name: string | undefined
nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
variables: ScriptGraphVariable[] | undefined
version: string
```
@@ -8070,6 +8087,20 @@ static new (): ScriptGraphPlugin
static 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: boolean
produced: Map<string, Record<string, ScriptValue>>
reported: Set<string>
@@ -8122,6 +8154,7 @@ ctx: Ctx
dt: number
onProblem: ((message: string) => void) | undefined
registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
world: World | undefined
```
@@ -8139,6 +8172,7 @@ boolean | number | string | null
```
getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
hasAction: (name: string) => boolean
isActionPure: (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): TileStamp
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | undefined
nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
prefabs: 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 | undefined
scaleMode: 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[] | undefined
name: string | undefined
nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
variables: ScriptGraphVariable[] | undefined
version: string
```
@@ -8318,6 +8335,20 @@ static new (): ScriptGraphPlugin
static 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: boolean
produced: Map<string, Record<string, ScriptValue>>
reported: Set<string>
@@ -8370,6 +8402,7 @@ ctx: Ctx
dt: number
onProblem: ((message: string) => void) | undefined
registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
world: World | undefined
```
@@ -8387,6 +8420,7 @@ boolean | number | string | null
```
getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
hasAction: (name: string) => boolean
isActionPure: (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): TileStamp
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | undefined
nodes: Map<string, ScriptGraphNode>
+outputNode: string | undefined
prefabs: 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 | undefined
scaleMode: 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[] | undefined
name: string | undefined
nodes: ScriptGraphNode[]
+outputs: ScriptGraphPort[] | undefined
variables: ScriptGraphVariable[] | undefined
version: string
```
@@ -8077,6 +8094,20 @@ static new (): ScriptGraphPlugin
static 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: boolean
produced: Map<string, Record<string, ScriptValue>>
reported: Set<string>
@@ -8129,6 +8161,7 @@ ctx: Ctx
dt: number
onProblem: ((message: string) => void) | undefined
registry: AiRegistry<Ctx>
+resolveGraph: ((ref: string) => CompiledScriptGraph | undefined) | undefined
world: World | undefined
```
@@ -8146,6 +8179,7 @@ boolean | number | string | null
```
getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
+graphSignature: (ref: string) => ScriptGraphSignature | null
hasAction: (name: string) => boolean
isActionPure: (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): TileStamp
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.ts
index 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 Team
import 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 3a1277323..f5deedcb2 100644
Binary files a/sdk/src/logic/ScriptGraphRunner.ts and b/sdk/src/logic/ScriptGraphRunner.ts differ
diff --git a/sdk/src/logic/graphOps.ts b/sdk/src/logic/graphOps.ts
index 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): ScriptGr
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.' },