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 is nodes, wires, and one vocabulary it shares

esengine34b2f146c940
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 758f056ef..d2afe2cc0 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": 1908,
+ "experimental": 1938,
"deprecated": 3
},
- "total": 2123,
+ "total": 2153,
"subsystems": [
{
"id": "ecs",
@@ -290,6 +290,20 @@
"Perception"
]
},
+ {
+ "id": "script-graph",
+ "title": "Script graphs — visual logic",
+ "titleZh": "脚本图 —— 可视化逻辑",
+ "tier": "experimental",
+ "why": "the node vocabulary is still growing: a name that gains an output changes what an authored graph can read, so the shape is not one to freeze yet",
+ "whyZh": "节点词汇表还在长:一个名字多一个输出就改变了已画好的图能读到什么,形状还不到冻结的时候",
+ "entry": [
+ "compileScriptGraph",
+ "stepScriptGraph",
+ "describeNode",
+ "canConnect"
+ ]
+ },
{
"id": "networking",
"title": "Networking & replication",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index a5cec83fc..f0907bd58 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 · 1747 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1777 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -172,6 +172,7 @@ static prototype: AdsAPI
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status
```
@@ -183,7 +184,9 @@ params: Readonly<Record<string, AiParamValue>> | undefined
## AiActionSpec — interface @experimental
```
+outputs: readonly AiOutputDef[] | undefined
params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
run: AiAction<Ctx>
separator: string | undefined
touches: AiTouchesSource | undefined
@@ -216,6 +219,19 @@ world: World
ResourceDef<StateMachines>
```
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
## AiParamDef — interface @experimental
```
label: string | undefined
@@ -247,17 +263,28 @@ clear: () => void
conditionNames: () => string[]
conditionTouches: (name: string) => AiTouches | undefined
getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
getActionSeparator: (name: string) => string
getCondition: (name: string) => AiCondition<Ctx> | undefined
hasAction: (name: string) => boolean
hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
static new <Ctx = unknown>(): AiRegistry<Ctx>
static prototype: AiRegistry<any>
```
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
## AlignContent — enum @experimental
```
Center = 1
@@ -1320,6 +1347,11 @@ readonly [{ readonly name: "master"; readonly parent: null; readonly volume: 1;
readonly BuiltinMeshTemplate[]
```
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
## BUILTIN_SHADER_TEMPLATES — const @experimental
```
readonly BuiltinShaderTemplate[]
@@ -2471,6 +2503,20 @@ initial: string
states: Map<string, FsmState>
```
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+nodes: Map<string, ScriptGraphNode>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+updates: string[]
+```
+
## Completable — interface @experimental
```
cancel: () => void
@@ -2729,6 +2775,11 @@ ScreenScalingData
{ x: number; y: number; }
```
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
## DEFAULT_TEXT_CANVAS_SIZE — const @experimental
```
512
@@ -7553,6 +7604,11 @@ ComponentDef<{}>
-1
```
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
## SH_BASIS_SCALE — const @experimental
```
readonly [0.282095, 0.488603, 0.488603, 0.488603, 1.092548, 1.092548, 0.315392, 1.092548, 0.546274]
@@ -7962,6 +8018,96 @@ renderPolicy: RenderResolution | undefined
scaleMode: number
```
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+name: string | undefined
+nodes: ScriptGraphNode[]
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "update" | "destroy" | "event" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
## ScrollContainer — class @experimental
```
dispose: () => void
@@ -11257,6 +11403,11 @@ BtPlugin
(module: ESEngineModule): boolean
```
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11357,6 +11508,11 @@ BtPlugin
(world: World, e: Entity): void
```
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
## col — const @experimental
```
{ readonly create: (r?: number, g?: number, b?: number, a?: number) => Color; readonly rgb: (r: number, g: number, b: number) => Color; readonly from255: (r: number, g: number, b: number, a?: number) => Color; readonly clone: (c: Color) => Color; readonly lerp: (a: Color, b: Color, t: number) => Color; readonly withAlpha: (c: Color, a: number) => Color; readonly multiply: (a: Color, b: Color) => Color; readonly scaleRgb: (c: Color, s: number) => Color; readonly fromHex: (hex: string) => Color; readonly toHex: (c: Color, withAlpha?: boolean) => string; readonly equals: (a: Color, b: Color, epsilon?: number) => boolean; }
@@ -11452,6 +11608,11 @@ BtPlugin
(graph: MaterialGraph): string
```
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
## composeTRS — function @experimental
```
(p: { x: number; y: number; z: number; }, q: { x: number; y: number; z: number; w: number; }, s: { x: number; y: number; z: number; }): number[]
@@ -11602,6 +11763,11 @@ Plugin
(name: string, sceneData: SceneData | undefined, options: Omit<LoadRuntimeSceneOptions, "sceneData" | "sceneName">, scenePath?: string): SceneConfig
```
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
## createScrollView — function @experimental
```
(opts: ScrollViewOptions): ScrollViewHandle
@@ -11697,6 +11863,11 @@ Plugin
(vertices: readonly Vec2[]): PolygonDecomposition
```
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
## defaultFrameStats — function @experimental
```
(): FrameStats
@@ -11752,6 +11923,11 @@ PluralSelector
<T>(sources: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T>
```
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
## desiredDirection — function @experimental
```
(input: { x: number; y: number; }, basis: MoveBasis): Vec3
@@ -11762,6 +11938,11 @@ PluralSelector
(cells: readonly WorldCell[], sources: readonly ResidencySource[], resident: ReadonlySet<string>): ResidencyDecision
```
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## detectAnchor — function @experimental
```
(node: UINodeData): AnchorPreset | null
@@ -11912,6 +12093,11 @@ DragPlugin
(): FsmDefinition
```
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
## enableSceneOrigins — function @experimental
```
(app: App): void
@@ -12082,6 +12268,11 @@ EventBindingPlugin
(): number
```
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number): void
+```
+
## flattenPrefab — function @experimental
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -12459,7 +12650,7 @@ InputRouter
## invokeAction — function @experimental
```
-<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput): void | Status
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
```
## isAuto — const @experimental
@@ -13327,6 +13518,11 @@ PrefabsPlugin
(id: string, descriptor: SideModuleDescriptor): void
```
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
## registryEntityFields — function @experimental
```
(): (componentType: string) => readonly string[]
@@ -13637,6 +13833,11 @@ Plugin
(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
```
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -13967,6 +14168,11 @@ StatsPlugin
(world: PerceptionWorldView, isBlocked?: LosCheck): void
```
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## stopNavAgent — function @experimental
```
(world: World, entity: Entity): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 52569c982..4e6f64d88 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 · 1766 experimental · 3 deprecated
+Symbols: 114 public · 99 beta · 1796 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -172,6 +172,7 @@ static prototype: AdsAPI
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status
```
@@ -183,7 +184,9 @@ params: Readonly<Record<string, AiParamValue>> | undefined
## AiActionSpec — interface @experimental
```
+outputs: readonly AiOutputDef[] | undefined
params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
run: AiAction<Ctx>
separator: string | undefined
touches: AiTouchesSource | undefined
@@ -216,6 +219,19 @@ world: World
ResourceDef<StateMachines>
```
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
## AiParamDef — interface @experimental
```
label: string | undefined
@@ -247,17 +263,28 @@ clear: () => void
conditionNames: () => string[]
conditionTouches: (name: string) => AiTouches | undefined
getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
getActionSeparator: (name: string) => string
getCondition: (name: string) => AiCondition<Ctx> | undefined
hasAction: (name: string) => boolean
hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
static new <Ctx = unknown>(): AiRegistry<Ctx>
static prototype: AiRegistry<any>
```
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
## AlignContent — enum @experimental
```
Center = 1
@@ -1320,6 +1347,11 @@ readonly [{ readonly name: "master"; readonly parent: null; readonly volume: 1;
readonly BuiltinMeshTemplate[]
```
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
## BUILTIN_SHADER_TEMPLATES — const @experimental
```
readonly BuiltinShaderTemplate[]
@@ -2471,6 +2503,20 @@ initial: string
states: Map<string, FsmState>
```
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+nodes: Map<string, ScriptGraphNode>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+updates: string[]
+```
+
## Completable — interface @experimental
```
cancel: () => void
@@ -2737,6 +2783,11 @@ ScreenScalingData
{ x: number; y: number; }
```
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
## DEFAULT_TEXT_CANVAS_SIZE — const @experimental
```
512
@@ -7746,6 +7797,11 @@ ComponentDef<{}>
-1
```
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
## SH_BASIS_SCALE — const @experimental
```
readonly [0.282095, 0.488603, 0.488603, 0.488603, 1.092548, 1.092548, 0.315392, 1.092548, 0.546274]
@@ -8155,6 +8211,96 @@ renderPolicy: RenderResolution | undefined
scaleMode: number
```
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+name: string | undefined
+nodes: ScriptGraphNode[]
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "update" | "destroy" | "event" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
## ScrollContainer — class @experimental
```
dispose: () => void
@@ -11465,6 +11611,11 @@ BtPlugin
(module: ESEngineModule): boolean
```
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11565,6 +11716,11 @@ BtPlugin
(world: World, e: Entity): void
```
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
## col — const @experimental
```
{ readonly create: (r?: number, g?: number, b?: number, a?: number) => Color; readonly rgb: (r: number, g: number, b: number) => Color; readonly from255: (r: number, g: number, b: number, a?: number) => Color; readonly clone: (c: Color) => Color; readonly lerp: (a: Color, b: Color, t: number) => Color; readonly withAlpha: (c: Color, a: number) => Color; readonly multiply: (a: Color, b: Color) => Color; readonly scaleRgb: (c: Color, s: number) => Color; readonly fromHex: (hex: string) => Color; readonly toHex: (c: Color, withAlpha?: boolean) => string; readonly equals: (a: Color, b: Color, epsilon?: number) => boolean; }
@@ -11660,6 +11816,11 @@ BtPlugin
(graph: MaterialGraph): string
```
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
## composeTRS — function @experimental
```
(p: { x: number; y: number; z: number; }, q: { x: number; y: number; z: number; w: number; }, s: { x: number; y: number; z: number; }): number[]
@@ -11835,6 +11996,11 @@ Plugin
(name: string, sceneData: SceneData | undefined, options: Omit<LoadRuntimeSceneOptions, "sceneData" | "sceneName">, scenePath?: string): SceneConfig
```
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
## createScrollView — function @experimental
```
(opts: ScrollViewOptions): ScrollViewHandle
@@ -11930,6 +12096,11 @@ Plugin
(vertices: readonly Vec2[]): PolygonDecomposition
```
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
## defaultFrameStats — function @experimental
```
(): FrameStats
@@ -11985,6 +12156,11 @@ PluralSelector
<T>(sources: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T>
```
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
## desiredDirection — function @experimental
```
(input: { x: number; y: number; }, basis: MoveBasis): Vec3
@@ -11995,6 +12171,11 @@ PluralSelector
(cells: readonly WorldCell[], sources: readonly ResidencySource[], resident: ReadonlySet<string>): ResidencyDecision
```
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## detectAnchor — function @experimental
```
(node: UINodeData): AnchorPreset | null
@@ -12145,6 +12326,11 @@ DragPlugin
(): FsmDefinition
```
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
## enableSceneOrigins — function @experimental
```
(app: App): void
@@ -12315,6 +12501,11 @@ EventBindingPlugin
(): number
```
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number): void
+```
+
## flattenPrefab — function @experimental
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -12702,7 +12893,7 @@ InputRouter
## invokeAction — function @experimental
```
-<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput): void | Status
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
```
## isAuto — const @experimental
@@ -13570,6 +13761,11 @@ PrefabsPlugin
(id: string, descriptor: SideModuleDescriptor): void
```
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
## registryEntityFields — function @experimental
```
(): (componentType: string) => readonly string[]
@@ -13880,6 +14076,11 @@ Plugin
(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
```
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -14210,6 +14411,11 @@ StatsPlugin
(world: PerceptionWorldView, isBlocked?: LosCheck): void
```
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## stopNavAgent — function @experimental
```
(world: World, entity: Entity): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 1b201162b..4aa22f665 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 · 1746 experimental · 3 deprecated
+Symbols: 114 public · 96 beta · 1776 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -167,6 +167,7 @@ static prototype: AdsAPI
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status
```
@@ -178,7 +179,9 @@ params: Readonly<Record<string, AiParamValue>> | undefined
## AiActionSpec — interface @experimental
```
+outputs: readonly AiOutputDef[] | undefined
params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
run: AiAction<Ctx>
separator: string | undefined
touches: AiTouchesSource | undefined
@@ -211,6 +214,19 @@ world: World
ResourceDef<StateMachines>
```
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
## AiParamDef — interface @experimental
```
label: string | undefined
@@ -242,17 +258,28 @@ clear: () => void
conditionNames: () => string[]
conditionTouches: (name: string) => AiTouches | undefined
getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
getActionSeparator: (name: string) => string
getCondition: (name: string) => AiCondition<Ctx> | undefined
hasAction: (name: string) => boolean
hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
static new <Ctx = unknown>(): AiRegistry<Ctx>
static prototype: AiRegistry<any>
```
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
## AlignContent — enum @experimental
```
Center = 1
@@ -1315,6 +1342,11 @@ readonly [{ readonly name: "master"; readonly parent: null; readonly volume: 1;
readonly BuiltinMeshTemplate[]
```
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
## BUILTIN_SHADER_TEMPLATES — const @experimental
```
readonly BuiltinShaderTemplate[]
@@ -2466,6 +2498,20 @@ initial: string
states: Map<string, FsmState>
```
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+nodes: Map<string, ScriptGraphNode>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+updates: string[]
+```
+
## Completable — interface @experimental
```
cancel: () => void
@@ -2724,6 +2770,11 @@ ScreenScalingData
{ x: number; y: number; }
```
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
## DEFAULT_TEXT_CANVAS_SIZE — const @experimental
```
512
@@ -7548,6 +7599,11 @@ ComponentDef<{}>
-1
```
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
## SH_BASIS_SCALE — const @experimental
```
readonly [0.282095, 0.488603, 0.488603, 0.488603, 1.092548, 1.092548, 0.315392, 1.092548, 0.546274]
@@ -7957,6 +8013,96 @@ renderPolicy: RenderResolution | undefined
scaleMode: number
```
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+name: string | undefined
+nodes: ScriptGraphNode[]
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "update" | "destroy" | "event" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
## ScrollContainer — class @experimental
```
dispose: () => void
@@ -11252,6 +11398,11 @@ BtPlugin
(module: ESEngineModule): boolean
```
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11352,6 +11503,11 @@ BtPlugin
(world: World, e: Entity): void
```
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
## col — const @experimental
```
{ readonly create: (r?: number, g?: number, b?: number, a?: number) => Color; readonly rgb: (r: number, g: number, b: number) => Color; readonly from255: (r: number, g: number, b: number, a?: number) => Color; readonly clone: (c: Color) => Color; readonly lerp: (a: Color, b: Color, t: number) => Color; readonly withAlpha: (c: Color, a: number) => Color; readonly multiply: (a: Color, b: Color) => Color; readonly scaleRgb: (c: Color, s: number) => Color; readonly fromHex: (hex: string) => Color; readonly toHex: (c: Color, withAlpha?: boolean) => string; readonly equals: (a: Color, b: Color, epsilon?: number) => boolean; }
@@ -11447,6 +11603,11 @@ BtPlugin
(graph: MaterialGraph): string
```
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
## composeTRS — function @experimental
```
(p: { x: number; y: number; z: number; }, q: { x: number; y: number; z: number; w: number; }, s: { x: number; y: number; z: number; }): number[]
@@ -11597,6 +11758,11 @@ Plugin
(name: string, sceneData: SceneData | undefined, options: Omit<LoadRuntimeSceneOptions, "sceneData" | "sceneName">, scenePath?: string): SceneConfig
```
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
## createScrollView — function @experimental
```
(opts: ScrollViewOptions): ScrollViewHandle
@@ -11692,6 +11858,11 @@ Plugin
(vertices: readonly Vec2[]): PolygonDecomposition
```
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
## defaultFrameStats — function @experimental
```
(): FrameStats
@@ -11747,6 +11918,11 @@ PluralSelector
<T>(sources: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T>
```
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
## desiredDirection — function @experimental
```
(input: { x: number; y: number; }, basis: MoveBasis): Vec3
@@ -11757,6 +11933,11 @@ PluralSelector
(cells: readonly WorldCell[], sources: readonly ResidencySource[], resident: ReadonlySet<string>): ResidencyDecision
```
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## detectAnchor — function @experimental
```
(node: UINodeData): AnchorPreset | null
@@ -11907,6 +12088,11 @@ DragPlugin
(): FsmDefinition
```
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
## enableSceneOrigins — function @experimental
```
(app: App): void
@@ -12077,6 +12263,11 @@ EventBindingPlugin
(): number
```
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number): void
+```
+
## flattenPrefab — function @experimental
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -12454,7 +12645,7 @@ InputRouter
## invokeAction — function @experimental
```
-<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput): void | Status
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
```
## isAuto — const @experimental
@@ -13332,6 +13523,11 @@ PrefabsPlugin
(id: string, descriptor: SideModuleDescriptor): void
```
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
## registryEntityFields — function @experimental
```
(): (componentType: string) => readonly string[]
@@ -13642,6 +13838,11 @@ Plugin
(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
```
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -13972,6 +14173,11 @@ StatsPlugin
(world: PerceptionWorldView, isBlocked?: LosCheck): void
```
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## stopNavAgent — function @experimental
```
(world: World, entity: Entity): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 9b36a3c0d..0d4b44ac8 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 · 1768 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1798 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -167,6 +167,7 @@ static prototype: AdsAPI
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status
```
@@ -178,7 +179,9 @@ params: Readonly<Record<string, AiParamValue>> | undefined
## AiActionSpec — interface @experimental
```
+outputs: readonly AiOutputDef[] | undefined
params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
run: AiAction<Ctx>
separator: string | undefined
touches: AiTouchesSource | undefined
@@ -211,6 +214,19 @@ world: World
ResourceDef<StateMachines>
```
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
## AiParamDef — interface @experimental
```
label: string | undefined
@@ -242,17 +258,28 @@ clear: () => void
conditionNames: () => string[]
conditionTouches: (name: string) => AiTouches | undefined
getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
getActionSeparator: (name: string) => string
getCondition: (name: string) => AiCondition<Ctx> | undefined
hasAction: (name: string) => boolean
hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
static new <Ctx = unknown>(): AiRegistry<Ctx>
static prototype: AiRegistry<any>
```
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
## AlignContent — enum @experimental
```
Center = 1
@@ -1315,6 +1342,11 @@ readonly [{ readonly name: "master"; readonly parent: null; readonly volume: 1;
readonly BuiltinMeshTemplate[]
```
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
## BUILTIN_SHADER_TEMPLATES — const @experimental
```
readonly BuiltinShaderTemplate[]
@@ -2466,6 +2498,20 @@ initial: string
states: Map<string, FsmState>
```
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+nodes: Map<string, ScriptGraphNode>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+updates: string[]
+```
+
## Completable — interface @experimental
```
cancel: () => void
@@ -2724,6 +2770,11 @@ ScreenScalingData
{ x: number; y: number; }
```
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
## DEFAULT_TEXT_CANVAS_SIZE — const @experimental
```
512
@@ -7796,6 +7847,11 @@ ComponentDef<{}>
-1
```
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
## SH_BASIS_SCALE — const @experimental
```
readonly [0.282095, 0.488603, 0.488603, 0.488603, 1.092548, 1.092548, 0.315392, 1.092548, 0.546274]
@@ -8205,6 +8261,96 @@ renderPolicy: RenderResolution | undefined
scaleMode: number
```
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+name: string | undefined
+nodes: ScriptGraphNode[]
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "update" | "destroy" | "event" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
## ScrollContainer — class @experimental
```
dispose: () => void
@@ -11506,6 +11652,11 @@ BtPlugin
(module: ESEngineModule): boolean
```
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11606,6 +11757,11 @@ BtPlugin
(world: World, e: Entity): void
```
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
## col — const @experimental
```
{ readonly create: (r?: number, g?: number, b?: number, a?: number) => Color; readonly rgb: (r: number, g: number, b: number) => Color; readonly from255: (r: number, g: number, b: number, a?: number) => Color; readonly clone: (c: Color) => Color; readonly lerp: (a: Color, b: Color, t: number) => Color; readonly withAlpha: (c: Color, a: number) => Color; readonly multiply: (a: Color, b: Color) => Color; readonly scaleRgb: (c: Color, s: number) => Color; readonly fromHex: (hex: string) => Color; readonly toHex: (c: Color, withAlpha?: boolean) => string; readonly equals: (a: Color, b: Color, epsilon?: number) => boolean; }
@@ -11701,6 +11857,11 @@ BtPlugin
(graph: MaterialGraph): string
```
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
## composeTRS — function @experimental
```
(p: { x: number; y: number; z: number; }, q: { x: number; y: number; z: number; w: number; }, s: { x: number; y: number; z: number; }): number[]
@@ -11856,6 +12017,11 @@ Plugin
(name: string, sceneData: SceneData | undefined, options: Omit<LoadRuntimeSceneOptions, "sceneData" | "sceneName">, scenePath?: string): SceneConfig
```
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
## createScrollView — function @experimental
```
(opts: ScrollViewOptions): ScrollViewHandle
@@ -11951,6 +12117,11 @@ Plugin
(vertices: readonly Vec2[]): PolygonDecomposition
```
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
## defaultFrameStats — function @experimental
```
(): FrameStats
@@ -12006,6 +12177,11 @@ PluralSelector
<T>(sources: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T>
```
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
## desiredDirection — function @experimental
```
(input: { x: number; y: number; }, basis: MoveBasis): Vec3
@@ -12016,6 +12192,11 @@ PluralSelector
(cells: readonly WorldCell[], sources: readonly ResidencySource[], resident: ReadonlySet<string>): ResidencyDecision
```
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## detectAnchor — function @experimental
```
(node: UINodeData): AnchorPreset | null
@@ -12166,6 +12347,11 @@ DragPlugin
(): FsmDefinition
```
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
## enableSceneOrigins — function @experimental
```
(app: App): void
@@ -12336,6 +12522,11 @@ EventBindingPlugin
(): number
```
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number): void
+```
+
## flattenPrefab — function @experimental
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -12723,7 +12914,7 @@ InputRouter
## invokeAction — function @experimental
```
-<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput): void | Status
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
```
## isAuto — const @experimental
@@ -13591,6 +13782,11 @@ PrefabsPlugin
(id: string, descriptor: SideModuleDescriptor): void
```
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
## registryEntityFields — function @experimental
```
(): (componentType: string) => readonly string[]
@@ -13901,6 +14097,11 @@ Plugin
(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
```
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -14231,6 +14432,11 @@ StatsPlugin
(world: PerceptionWorldView, isBlocked?: LosCheck): void
```
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## stopNavAgent — function @experimental
```
(world: World, entity: Entity): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 6270f7953..a3d4547c2 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 · 1758 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1788 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -167,6 +167,7 @@ static prototype: AdsAPI
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status
```
@@ -178,7 +179,9 @@ params: Readonly<Record<string, AiParamValue>> | undefined
## AiActionSpec — interface @experimental
```
+outputs: readonly AiOutputDef[] | undefined
params: readonly AiParamDef[] | undefined
+pure: boolean | undefined
run: AiAction<Ctx>
separator: string | undefined
touches: AiTouchesSource | undefined
@@ -211,6 +214,19 @@ world: World
ResourceDef<StateMachines>
```
+## AiOutputDef — interface @experimental
+```
+label: string | undefined
+name: string
+tooltip: string | undefined
+type: "string" | "number" | "bool" | "entity"
+```
+
+## AiOutputs — type @experimental
+```
+Record<string, AiParamValue>
+```
+
## AiParamDef — interface @experimental
```
label: string | undefined
@@ -242,17 +258,28 @@ clear: () => void
conditionNames: () => string[]
conditionTouches: (name: string) => AiTouches | undefined
getAction: (name: string) => AiAction<Ctx> | undefined
+getActionOutputs: (name: string) => readonly AiOutputDef[]
getActionParams: (name: string) => readonly AiParamDef[]
getActionSeparator: (name: string) => string
getCondition: (name: string) => AiCondition<Ctx> | undefined
hasAction: (name: string) => boolean
hasCondition: (name: string) => boolean
+isActionPure: (name: string) => boolean
registerAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => void
registerCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void
+registerValue: (name: string, spec: AiValueSpec<Ctx>) => void
static new <Ctx = unknown>(): AiRegistry<Ctx>
static prototype: AiRegistry<any>
```
+## AiValueSpec — interface @experimental
+```
+evaluate: (ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs) => void
+outputs: readonly AiOutputDef[]
+params: readonly AiParamDef[] | undefined
+touches: AiTouches | undefined
+```
+
## AlignContent — enum @experimental
```
Center = 1
@@ -1315,6 +1342,11 @@ readonly [{ readonly name: "master"; readonly parent: null; readonly volume: 1;
readonly BuiltinMeshTemplate[]
```
+## BUILTIN_NODE_KINDS — const @experimental
+```
+readonly string[]
+```
+
## BUILTIN_SHADER_TEMPLATES — const @experimental
```
readonly BuiltinShaderTemplate[]
@@ -2466,6 +2498,20 @@ initial: string
states: Map<string, FsmState>
```
+## CompiledScriptGraph — interface @experimental
+```
+dataSources: Map<string, { node: string; port: string; }>
+destroys: string[]
+events: Map<string, string[]>
+execTargets: Map<string, string>
+graph: ScriptGraph
+nodes: Map<string, ScriptGraphNode>
+problems: string[]
+shapes: Map<string, ScriptNodeShape>
+starts: string[]
+updates: string[]
+```
+
## Completable — interface @experimental
```
cancel: () => void
@@ -2724,6 +2770,11 @@ ScreenScalingData
{ x: number; y: number; }
```
+## DEFAULT_STEP_BUDGET — const @experimental
+```
+4096
+```
+
## DEFAULT_TEXT_CANVAS_SIZE — const @experimental
```
512
@@ -7555,6 +7606,11 @@ ComponentDef<{}>
-1
```
+## SCRIPT_GRAPH_VERSION — const @experimental
+```
+"1.0"
+```
+
## SH_BASIS_SCALE — const @experimental
```
readonly [0.282095, 0.488603, 0.488603, 0.488603, 1.092548, 1.092548, 0.315392, 1.092548, 0.546274]
@@ -7964,6 +8020,96 @@ renderPolicy: RenderResolution | undefined
scaleMode: number
```
+## ScriptGraph — interface @experimental
+```
+edges: ScriptGraphEdge[]
+name: string | undefined
+nodes: ScriptGraphNode[]
+variables: ScriptGraphVariable[] | undefined
+version: string
+```
+
+## ScriptGraphEdge — interface @experimental
+```
+from: string
+fromPort: string
+id: string
+to: string
+toPort: string
+```
+
+## ScriptGraphNode — interface @experimental
+```
+id: string
+kind: string
+literals: Record<string, ScriptValue> | undefined
+ref: string | undefined
+x: number | undefined
+y: number | undefined
+```
+
+## ScriptGraphVariable — interface @experimental
+```
+default: ScriptValue | undefined
+name: string
+type: "string" | "number" | "bool" | "entity"
+```
+
+## ScriptNodeShape — interface @experimental
+```
+entry: "start" | "update" | "destroy" | "event" | undefined
+execIn: boolean
+execOut: readonly string[]
+inputs: readonly ScriptPort[]
+outputs: readonly ScriptPort[]
+pure: boolean
+```
+
+## ScriptPort — interface @experimental
+```
+label: string | undefined
+name: string
+type: ScriptValueType
+```
+
+## ScriptRunState — interface @experimental
+```
+halted: boolean
+produced: Map<string, Record<string, ScriptValue>>
+reported: Set<string>
+started: boolean
+timers: Map<string, number>
+vars: Map<string, ScriptValue>
+```
+
+## ScriptTickContext — interface @experimental
+```
+bb: Blackboard
+budget: number | undefined
+ctx: Ctx
+dt: number
+onProblem: ((message: string) => void) | undefined
+registry: AiRegistry<Ctx>
+```
+
+## ScriptValue — type @experimental
+```
+boolean | number | string | null
+```
+
+## ScriptValueType — type @experimental
+```
+'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any'
+```
+
+## ScriptVerbCatalog — interface @experimental
+```
+getActionOutputs: (name: string) => readonly AiOutputDef[]
+getActionParams: (name: string) => readonly AiParamDef[]
+hasAction: (name: string) => boolean
+isActionPure: (name: string) => boolean
+```
+
## ScrollContainer — class @experimental
```
dispose: () => void
@@ -11280,6 +11426,11 @@ BtPlugin
(module: ESEngineModule): boolean
```
+## canConnect — function @experimental
+```
+(from: ScriptValueType, to: ScriptValueType): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11380,6 +11531,11 @@ BtPlugin
(world: World, e: Entity): void
```
+## coerceValue — function @experimental
+```
+(value: ScriptValue, type: ScriptValueType): ScriptValue
+```
+
## col — const @experimental
```
{ readonly create: (r?: number, g?: number, b?: number, a?: number) => Color; readonly rgb: (r: number, g: number, b: number) => Color; readonly from255: (r: number, g: number, b: number, a?: number) => Color; readonly clone: (c: Color) => Color; readonly lerp: (a: Color, b: Color, t: number) => Color; readonly withAlpha: (c: Color, a: number) => Color; readonly multiply: (a: Color, b: Color) => Color; readonly scaleRgb: (c: Color, s: number) => Color; readonly fromHex: (hex: string) => Color; readonly toHex: (c: Color, withAlpha?: boolean) => string; readonly equals: (a: Color, b: Color, epsilon?: number) => boolean; }
@@ -11475,6 +11631,11 @@ BtPlugin
(graph: MaterialGraph): string
```
+## compileScriptGraph — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog): CompiledScriptGraph
+```
+
## composeTRS — function @experimental
```
(p: { x: number; y: number; z: number; }, q: { x: number; y: number; z: number; w: number; }, s: { x: number; y: number; z: number; }): number[]
@@ -11625,6 +11786,11 @@ Plugin
(name: string, sceneData: SceneData | undefined, options: Omit<LoadRuntimeSceneOptions, "sceneData" | "sceneName">, scenePath?: string): SceneConfig
```
+## createScriptRunState — function @experimental
+```
+(compiled: CompiledScriptGraph): ScriptRunState
+```
+
## createScrollView — function @experimental
```
(opts: ScrollViewOptions): ScrollViewHandle
@@ -11720,6 +11886,11 @@ Plugin
(vertices: readonly Vec2[]): PolygonDecomposition
```
+## defaultForType — function @experimental
+```
+(type: ScriptValueType): ScriptValue
+```
+
## defaultFrameStats — function @experimental
```
(): FrameStats
@@ -11775,6 +11946,11 @@ PluralSelector
<T>(sources: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T>
```
+## describeNode — function @experimental
+```
+(node: ScriptGraphNode, graph: ScriptGraph, catalog: ScriptVerbCatalog): ScriptNodeShape | null
+```
+
## desiredDirection — function @experimental
```
(input: { x: number; y: number; }, basis: MoveBasis): Vec3
@@ -11785,6 +11961,11 @@ PluralSelector
(cells: readonly WorldCell[], sources: readonly ResidencySource[], resident: ReadonlySet<string>): ResidencyDecision
```
+## destroyScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## detectAnchor — function @experimental
```
(node: UINodeData): AnchorPreset | null
@@ -11935,6 +12116,11 @@ DragPlugin
(): FsmDefinition
```
+## emptyScriptGraph — function @experimental
+```
+(name?: string): ScriptGraph
+```
+
## enableSceneOrigins — function @experimental
```
(app: App): void
@@ -12105,6 +12291,11 @@ EventBindingPlugin
(): number
```
+## fireScriptGraphEvent — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>, type: string, target: number): void
+```
+
## flattenPrefab — function @experimental
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -12487,7 +12678,7 @@ InputRouter
## invokeAction — function @experimental
```
-<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput): void | Status
+<Ctx>(registry: AiRegistry<Ctx>, name: string, ctx: Ctx, bb: Blackboard, input?: AiActionInput, out?: AiOutputs): void | Status
```
## isAuto — const @experimental
@@ -13355,6 +13546,11 @@ PrefabsPlugin
(id: string, descriptor: SideModuleDescriptor): void
```
+## registerValue — function @experimental
+```
+(name: string, spec: AiValueSpec<AiContext>): void
+```
+
## registryEntityFields — function @experimental
```
(): (componentType: string) => readonly string[]
@@ -13665,6 +13861,11 @@ Plugin
(observer: Vec3, facing: Vec3, target: Vec3, range: number, halfFov: number, isBlocked?: (from: Vec3, to: Vec3) => boolean): SenseResult
```
+## sequenceCount — function @experimental
+```
+(node: ScriptGraphNode): number
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -13995,6 +14196,11 @@ StatsPlugin
(world: PerceptionWorldView, isBlocked?: LosCheck): void
```
+## stepScriptGraph — function @experimental
+```
+<Ctx>(compiled: CompiledScriptGraph, run: ScriptRunState, tick: ScriptTickContext<Ctx>): void
+```
+
## stopNavAgent — function @experimental
```
(world: World, entity: Entity): void
diff --git a/sdk/src/ai/fsm/AiContext.ts b/sdk/src/ai/fsm/AiContext.ts
index eb31e681a..e55f2272a 100644
--- a/sdk/src/ai/fsm/AiContext.ts
+++ b/sdk/src/ai/fsm/AiContext.ts
@@ -16,7 +16,7 @@ import type { World } from '../../ecs/world';
import type { CommandsInstance } from '../../ecs/commands';
import type { AnyComponentDef, ComponentData } from '../../ecs/component';
import type { Blackboard } from './Blackboard';
-import { AiRegistry, type AiAction, type AiActionSpec, type AiCondition } from './registry';
+import { AiRegistry, type AiAction, type AiActionSpec, type AiCondition, type AiValueSpec } from './registry';
export interface AiContext {
/** The agent entity this action/condition runs for. */
@@ -57,3 +57,12 @@ export function registerAction(name: string, fn: AiAction<AiContext> | AiActionS
export function registerCondition(name: string, fn: AiCondition<AiContext>): void {
aiRegistry.registerCondition(name, fn);
}
+
+/**
+ * Register a named VALUE — a pure name that answers a question, which a script
+ * graph reads by wiring its declared outputs. Same store as the actions, so it
+ * shows up in the same palettes.
+ */
+export function registerValue(name: string, spec: AiValueSpec<AiContext>): void {
+ aiRegistry.registerValue(name, spec);
+}
diff --git a/sdk/src/ai/fsm/index.ts b/sdk/src/ai/fsm/index.ts
index a4a69fff5..3a3541872 100644
--- a/sdk/src/ai/fsm/index.ts
+++ b/sdk/src/ai/fsm/index.ts
@@ -27,6 +27,10 @@ export {
type AiParamDef,
type AiParamValue,
type AiParams,
+ type AiOutputDef,
+ type AiOutputs,
+ type AiValueSpec,
+ type AiTouches,
} from './registry';
export {
compileFsm,
diff --git a/sdk/src/ai/fsm/registry.ts b/sdk/src/ai/fsm/registry.ts
index 7939d3f90..1d6f89431 100644
--- a/sdk/src/ai/fsm/registry.ts
+++ b/sdk/src/ai/fsm/registry.ts
@@ -28,20 +28,26 @@ export type AiParamValue = string | number | boolean;
/** Declared parameters of one action reference, keyed by {@link AiParamDef.name}. */
export type AiParams = Readonly<Record<string, AiParamValue>>;
-// Returns Status (a BT leaf that may run across frames) or nothing (a one-shot
-// FSM action). FSM ignores the return; BT reads it, treating void as Success.
-// `arg` is the canonical string form of the reference (what authored data has
-// always carried); `params` is the same input keyed by declared parameter name,
-// empty for an action that declares none. An action reads whichever it prefers —
-// both are always supplied, so neither channel is a second way to be wrong.
+// Returns Status (a BT leaf running across frames) or nothing; FSM ignores the
+// return, BT treats void as Success. `arg` and `params` are one input in two
+// forms, both always supplied, so neither is a second way to be wrong.
export type AiAction<Ctx> = (
ctx: Ctx,
bb: Blackboard,
arg?: string,
params?: AiParams,
+ out?: AiOutputs,
) => void | Status;
export type AiCondition<Ctx> = (ctx: Ctx, bb: Blackboard) => boolean;
+/**
+ * Values a name hands back, keyed by {@link AiOutputDef.name} — filled through
+ * the `out` parameter rather than the return, which already answers the BT's
+ * question. One channel with two meanings reports a leaf as Running because it
+ * produced a value.
+ */
+export type AiOutputs = Record<string, AiParamValue>;
+
/**
* One declared parameter. The vocabulary is deliberately the component-field one
* (`enum` options, numeric range, tooltip) so an editor renders action parameters
@@ -67,6 +73,20 @@ export interface AiParamDef {
step?: number;
}
+/**
+ * One declared output — what a name hands back. Deliberately thinner than
+ * {@link AiParamDef}: an output has no control to render, so it carries the
+ * type a wire is checked against and a label, and nothing an inspector would
+ * need.
+ */
+export interface AiOutputDef {
+ /** Key in the {@link AiOutputs} record, and the fallback label. */
+ name: string;
+ type: 'string' | 'number' | 'bool' | 'entity';
+ label?: string;
+ tooltip?: string;
+}
+
/**
* What a leaf reaches for on the world, by component name.
*
@@ -91,6 +111,15 @@ export interface AiActionSpec<Ctx> {
run: AiAction<Ctx>;
/** Declared parameters, in canonical string order. */
params?: readonly AiParamDef[];
+ /** Declared outputs — what it writes into the `out` record it is handed. */
+ outputs?: readonly AiOutputDef[];
+ /**
+ * True when running it changes nothing: the name answers a question. A pure
+ * name may be evaluated on demand and in any order, which is what lets a
+ * script graph pull a value up its data wires instead of sequencing it.
+ * A leaf that mutates the world and ALSO hands back a value is not pure.
+ */
+ pure?: boolean;
/** What it reaches for. Undeclared means unknown, not nothing. */
touches?: AiTouchesSource;
/**
@@ -105,10 +134,29 @@ export interface AiActionSpec<Ctx> {
interface ActionEntry<Ctx> {
fn: AiAction<Ctx>;
params: readonly AiParamDef[];
+ outputs: readonly AiOutputDef[];
+ pure: boolean;
separator: string;
touches?: AiTouchesSource;
}
+/**
+ * A name that answers a question instead of doing something — the registration
+ * shape for a pure leaf. {@link AiActionSpec} minus the parts a question has no
+ * use for: no Status (nothing runs across frames) and no canonical-string
+ * projection (a value is reached by a wire, never by a hand-typed `arg`).
+ */
+export interface AiValueSpec<Ctx> {
+ /** Declared inputs — the same vocabulary an action's parameters use. */
+ params?: readonly AiParamDef[];
+ /** Declared outputs. A value with none is a name nothing can read. */
+ outputs: readonly AiOutputDef[];
+ /** What it reads. Undeclared means unknown, not nothing. */
+ touches?: AiTouches;
+ /** Fill `out` with the declared outputs. Must not change the world. */
+ evaluate(ctx: Ctx, bb: Blackboard, params: AiParams, out: AiOutputs): void;
+}
+
/** A condition registered with metadata rather than as a bare predicate. */
export interface AiConditionSpec<Ctx> {
check: AiCondition<Ctx>;
@@ -141,13 +189,34 @@ export class AiRegistry<Ctx = unknown> {
const run = spec.run;
const wrapped: AiAction<Ctx> = params.length === 0
? run // no declaration, no projection — byte-identical behaviour
- : (ctx, bb, arg, given) => {
+ : (ctx, bb, arg, given, out) => {
const named = given && Object.keys(given).length > 0
? given
: parseActionArg(arg, params, separator);
- return run(ctx, bb, arg ?? formatActionArg(named, params, separator), named);
+ return run(ctx, bb, arg ?? formatActionArg(named, params, separator), named, out);
};
- this.actions.set(name, { fn: wrapped, params, separator, touches: spec.touches });
+ this.actions.set(name, {
+ fn: wrapped, params, outputs: spec.outputs ?? [], pure: spec.pure === true,
+ separator, touches: spec.touches,
+ });
+ }
+
+ /**
+ * Register a pure name — see {@link AiValueSpec}. It lands in the SAME store
+ * actions do, so one lookup, one catalog and one extractor serve both: a
+ * palette asks what names exist, not what kind of thing each one is.
+ */
+ registerValue(name: string, spec: AiValueSpec<Ctx>): void {
+ const { evaluate } = spec;
+ this.registerAction(name, {
+ params: spec.params,
+ outputs: spec.outputs,
+ pure: true,
+ touches: spec.touches,
+ run: (ctx, bb, _arg, params, out) => {
+ if (out) evaluate(ctx, bb, params ?? {}, out);
+ },
+ });
}
registerCondition(name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>): void {
@@ -185,6 +254,16 @@ export class AiRegistry<Ctx = unknown> {
return this.actions.get(name)?.separator ?? ':';
}
+ /** What `name` hands back (empty when it declares nothing). */
+ getActionOutputs(name: string): readonly AiOutputDef[] {
+ return this.actions.get(name)?.outputs ?? [];
+ }
+
+ /** Whether running `name` changes nothing — see {@link AiActionSpec.pure}. */
+ isActionPure(name: string): boolean {
+ return this.actions.get(name)?.pure ?? false;
+ }
+
getCondition(name: string): AiCondition<Ctx> | undefined {
return this.conditions.get(name)?.fn;
}
@@ -279,6 +358,7 @@ export function invokeAction<Ctx>(
ctx: Ctx,
bb: Blackboard,
input: AiActionInput = {},
+ out?: AiOutputs,
): void | Status {
const fn = registry.getAction(name);
if (!fn) return undefined;
@@ -287,7 +367,7 @@ export function invokeAction<Ctx>(
const arg = named
? formatActionArg(named, registry.getActionParams(name), registry.getActionSeparator(name)) ?? input.arg
: input.arg;
- return fn(ctx, bb, arg, named);
+ return fn(ctx, bb, arg, named, out);
}
function coerce(raw: string, type: AiParamDef['type']): AiParamValue {
diff --git a/sdk/src/ai/index.ts b/sdk/src/ai/index.ts
index b7277951f..ae50ff720 100644
--- a/sdk/src/ai/index.ts
+++ b/sdk/src/ai/index.ts
@@ -15,6 +15,7 @@ export {
aiRegistry,
registerAction,
registerCondition,
+ registerValue,
type AiContext,
} from './fsm/AiContext';
export {
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 59fc56462..bfad94650 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -904,6 +904,7 @@ export {
aiRegistry,
registerAction,
registerCondition,
+ registerValue,
// The declared-parameter surface: an action says what it takes, and the
// projection to/from the canonical `arg` string keeps old data running.
invokeAction,
@@ -914,6 +915,9 @@ export {
type AiParams,
type AiActionSpec,
type AiActionInput,
+ type AiOutputDef,
+ type AiOutputs,
+ type AiValueSpec,
StateMachineAgent,
registerFsm,
getFsm,
@@ -989,6 +993,39 @@ export {
type BehaviorTreeAgentData,
} from './ai';
+// =============================================================================
+// Script graph — the `.esgraph` authoring form: events, an exec wire, data wires
+// =============================================================================
+
+export {
+ SCRIPT_GRAPH_VERSION,
+ emptyScriptGraph,
+ canConnect,
+ coerceValue,
+ defaultForType,
+ describeNode,
+ sequenceCount,
+ BUILTIN_NODE_KINDS,
+ compileScriptGraph,
+ createScriptRunState,
+ stepScriptGraph,
+ destroyScriptGraph,
+ fireScriptGraphEvent,
+ DEFAULT_STEP_BUDGET,
+ type ScriptGraph,
+ type ScriptGraphNode,
+ type ScriptGraphEdge,
+ type ScriptGraphVariable,
+ type ScriptPort,
+ type ScriptValue,
+ type ScriptValueType,
+ type ScriptNodeShape,
+ type ScriptVerbCatalog,
+ type CompiledScriptGraph,
+ type ScriptRunState,
+ type ScriptTickContext,
+} from './logic';
+
// =============================================================================
// AI — Perception (sight/FOV sensing into a Perception component)
// =============================================================================
diff --git a/sdk/src/logic/ScriptGraphRunner.ts b/sdk/src/logic/ScriptGraphRunner.ts
new file mode 100644
index 000000000..062fe4a09
Binary files /dev/null and b/sdk/src/logic/ScriptGraphRunner.ts differ
diff --git a/sdk/src/logic/index.ts b/sdk/src/logic/index.ts
new file mode 100644
index 000000000..ddc18c973
--- /dev/null
+++ b/sdk/src/logic/index.ts
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file index.ts
+ * @brief Script graph barrel — the `.esgraph` authoring form of a behaviour.
+ *
+ * The core is pure and wasm-free (types, pins, interpreter), the way the FSM and
+ * behaviour-tree cores are, so the editor can compile a graph to validate it
+ * without an engine. The verbs a graph calls are the `aiRegistry` names — this
+ * layer adds no second vocabulary.
+ */
+
+export {
+ SCRIPT_GRAPH_VERSION,
+ emptyScriptGraph,
+ canConnect,
+ coerceValue,
+ defaultForType,
+ type ScriptGraph,
+ type ScriptGraphNode,
+ type ScriptGraphEdge,
+ type ScriptGraphVariable,
+ type ScriptPort,
+ type ScriptValue,
+ type ScriptValueType,
+} from './types';
+
+export {
+ describeNode,
+ sequenceCount,
+ BUILTIN_NODE_KINDS,
+ THEN,
+ type ScriptNodeShape,
+ type ScriptVerbCatalog,
+} from './nodes';
+
+export {
+ compileScriptGraph,
+ createScriptRunState,
+ stepScriptGraph,
+ destroyScriptGraph,
+ fireScriptGraphEvent,
+ DEFAULT_STEP_BUDGET,
+ type CompiledScriptGraph,
+ type ScriptRunState,
+ type ScriptTickContext,
+} from './ScriptGraphRunner';
diff --git a/sdk/src/logic/nodes.ts b/sdk/src/logic/nodes.ts
new file mode 100644
index 000000000..3ecbd1eba
--- /dev/null
+++ b/sdk/src/logic/nodes.ts
@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file nodes.ts
+ * @brief What a node's pins are — the one answer the interpreter and the
+ * canvas both read.
+ *
+ * Only the kinds the registry CANNOT express live here: entries (the interpreter
+ * ignites them), flow (they steer the exec wire), variables and literals (they
+ * read the interpreter's own state). Everything else — maths, comparisons,
+ * reading a component, spawning — is an ordinary registered name, so a project
+ * or a plugin extends the vocabulary exactly the way the engine does. There is
+ * no built-in privilege to reach for.
+ */
+
+import type { AiOutputDef, AiParamDef } from '../ai/fsm/registry';
+import type { ScriptGraph, ScriptGraphNode, ScriptPort, ScriptValueType } from './types';
+
+/**
+ * The registry, narrowed to what a shape needs. An `AiRegistry` satisfies it
+ * structurally; so does the editor's catalog, which knows the names the open
+ * PROJECT registered — names the editor's own realm never executes and so could
+ * never have in a live registry.
+ */
+export interface ScriptVerbCatalog {
+ hasAction(name: string): boolean;
+ getActionParams(name: string): readonly AiParamDef[];
+ getActionOutputs(name: string): readonly AiOutputDef[];
+ isActionPure(name: string): boolean;
+}
+
+/** A node's pins, plus the two facts the interpreter needs to place it. */
+export interface ScriptNodeShape {
+ /** Whether an exec wire can arrive. Pure nodes have none. */
+ execIn: boolean;
+ /** Exec output pins, in display order. */
+ execOut: readonly string[];
+ inputs: readonly ScriptPort[];
+ outputs: readonly ScriptPort[];
+ /** No side effects: may be pulled on demand, in any order. */
+ pure: boolean;
+ /** Set on the nodes a tick ignites, saying which occasion lights them. */
+ entry?: 'start' | 'update' | 'destroy' | 'event';
+}
+
+/** Default exec pin name — the single "and then" every flow-through node has. */
+export const THEN = 'then';
+
+/** An action's declared parameter as a port. `enum` is a string with choices. */
+function portOfParam(p: AiParamDef): ScriptPort {
+ return { name: p.name, type: p.type === 'enum' ? 'string' : p.type, label: p.label };
+}
+
+function portOfOutput(o: AiOutputDef): ScriptPort {
+ return { name: o.name, type: o.type, label: o.label };
+}
+
+const NO_PORTS: readonly ScriptPort[] = [];
+
+function entry(outputs: readonly ScriptPort[], occasion: ScriptNodeShape['entry']): ScriptNodeShape {
+ return { execIn: false, execOut: [THEN], inputs: NO_PORTS, outputs, pure: false, entry: occasion };
+}
+
+/** Literal-valued node kinds → the type they carry. */
+const LITERAL_KINDS: Record<string, ScriptValueType> = {
+ 'lit.number': 'number',
+ 'lit.bool': 'bool',
+ 'lit.string': 'string',
+};
+
+/** The declared type of `name` in this graph, or `any` when it declares none. */
+function variableType(graph: ScriptGraph, name: unknown): ScriptValueType {
+ if (typeof name !== 'string') return 'any';
+ return graph.variables?.find((v) => v.name === name)?.type ?? 'any';
+}
+
+/**
+ * How many exec pins a `flow.sequence` shows. Authored, not inferred from the
+ * wires: a pin the author added and has not wired yet still has to be there to
+ * wire INTO, and inferring the count from edges would delete it on reload.
+ */
+export function sequenceCount(node: ScriptGraphNode): number {
+ const raw = node.literals?.count;
+ const n = typeof raw === 'number' ? Math.floor(raw) : 2;
+ return Math.max(1, Math.min(16, n));
+}
+
+/**
+ * The pins of one node, or null when nothing knows this kind — an unknown node
+ * is reported, never treated as a no-op, because a graph missing a verb is a
+ * graph that does something else.
+ */
+export function describeNode(
+ node: ScriptGraphNode,
+ graph: ScriptGraph,
+ catalog: ScriptVerbCatalog,
+): ScriptNodeShape | null {
+ switch (node.kind) {
+ case 'event.start':
+ return entry(NO_PORTS, 'start');
+ case 'event.update':
+ return entry([{ name: 'dt', type: 'number' }], 'update');
+ case 'event.destroy':
+ return entry(NO_PORTS, 'destroy');
+ case 'event.on':
+ return entry([{ name: 'target', type: 'entity' }], 'event');
+
+ case 'flow.branch':
+ return {
+ execIn: true, execOut: ['true', 'false'],
+ inputs: [{ name: 'cond', type: 'bool' }], outputs: NO_PORTS, pure: false,
+ };
+ case 'flow.sequence':
+ return {
+ execIn: true,
+ execOut: Array.from({ length: sequenceCount(node) }, (_, i) => String(i)),
+ inputs: NO_PORTS, outputs: NO_PORTS, pure: false,
+ };
+ case 'flow.while':
+ return {
+ execIn: true, execOut: ['body', 'done'],
+ inputs: [{ name: 'cond', type: 'bool' }], outputs: NO_PORTS, pure: false,
+ };
+ case 'flow.delay':
+ return {
+ execIn: true, execOut: [THEN],
+ inputs: [{ name: 'seconds', type: 'number' }], outputs: NO_PORTS, pure: false,
+ };
+
+ case 'var.get':
+ return {
+ execIn: false, execOut: [], inputs: NO_PORTS,
+ outputs: [{ name: 'value', type: variableType(graph, node.literals?.name) }],
+ pure: true,
+ };
+ case 'var.set':
+ return {
+ execIn: true, execOut: [THEN],
+ inputs: [{ name: 'value', type: variableType(graph, node.literals?.name) }],
+ outputs: NO_PORTS, pure: false,
+ };
+
+ case 'call': {
+ const ref = node.ref;
+ if (!ref || !catalog.hasAction(ref)) return null;
+ const pure = catalog.isActionPure(ref);
+ return {
+ execIn: !pure,
+ execOut: pure ? [] : [THEN],
+ inputs: catalog.getActionParams(ref).map(portOfParam),
+ outputs: catalog.getActionOutputs(ref).map(portOfOutput),
+ pure,
+ };
+ }
+ }
+
+ const literal = LITERAL_KINDS[node.kind];
+ if (literal) {
+ return {
+ execIn: false, execOut: [], inputs: NO_PORTS,
+ outputs: [{ name: 'value', type: literal }], pure: true,
+ };
+ }
+ return null;
+}
+
+/** Every built-in kind, for the editor palette. `call` is not one — it is a name. */
+export const BUILTIN_NODE_KINDS: readonly string[] = [
+ 'event.start', 'event.update', 'event.destroy', 'event.on',
+ 'flow.branch', 'flow.sequence', 'flow.while', 'flow.delay',
+ 'var.get', 'var.set',
+ 'lit.number', 'lit.bool', 'lit.string',
+];
diff --git a/sdk/src/logic/types.ts b/sdk/src/logic/types.ts
new file mode 100644
index 000000000..f0fe35d6a
--- /dev/null
+++ b/sdk/src/logic/types.ts
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file types.ts
+ * @brief `.esgraph` — the authored shape of a script graph.
+ *
+ * A graph is nodes, wires, and declared variables. It is the RUNTIME definition:
+ * nothing compiles it, so the graph the editor runs and the graph the package
+ * 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.
+ */
+
+/** What a wire carries. `exec` is the control wire; the rest are data. */
+export type ScriptValueType = 'exec' | 'bool' | 'number' | 'string' | 'entity' | 'any';
+
+/** A value flowing through a data wire, and the form a literal is stored in. */
+export type ScriptValue = boolean | number | string | null;
+
+/** One port on a node. */
+export interface ScriptPort {
+ /** Port id, unique within its node and side. Also the fallback label. */
+ name: string;
+ type: ScriptValueType;
+ label?: string;
+}
+
+export interface ScriptGraphNode {
+ id: string;
+ /** Built-in node kind (`flow.branch`, `event.start`, …) or `'call'`. */
+ kind: string;
+ /** For `kind: 'call'` — the registry name this node runs. */
+ ref?: string;
+ /**
+ * Values for input ports nothing is wired into, plus the literals that SHAPE
+ * a node (an `event.on` type, a `flow.sequence` pin count). Keyed by port id.
+ */
+ literals?: Record<string, ScriptValue>;
+ /** Editor canvas position. The interpreter ignores it. */
+ x?: number;
+ y?: number;
+}
+
+export interface ScriptGraphEdge {
+ id: string;
+ from: string;
+ /** Output port id on `from`. */
+ fromPort: string;
+ to: string;
+ /** Input port id on `to`. */
+ toPort: string;
+}
+
+/** A graph-local variable: declared by the asset, valued per entity. */
+export interface ScriptGraphVariable {
+ name: string;
+ type: Exclude<ScriptValueType, 'exec' | 'any'>;
+ default?: ScriptValue;
+}
+
+export interface ScriptGraph {
+ version: string;
+ name?: string;
+ variables?: ScriptGraphVariable[];
+ nodes: ScriptGraphNode[];
+ edges: ScriptGraphEdge[];
+}
+
+export const SCRIPT_GRAPH_VERSION = '1.0';
+
+/** An empty graph, the shape "New Script Graph" writes. */
+export function emptyScriptGraph(name?: string): ScriptGraph {
+ return { version: SCRIPT_GRAPH_VERSION, ...(name ? { name } : {}), nodes: [], edges: [] };
+}
+
+/**
+ * Whether a wire from `from` to `to` is legal. ONE answer, two askers: the
+ * editor refuses the drag, the loader reports the file. `any` accepts and is
+ * accepted; `exec` only ever meets `exec`.
+ */
+export function canConnect(from: ScriptValueType, to: ScriptValueType): boolean {
+ if (from === 'exec' || to === 'exec') return from === to;
+ if (from === 'any' || to === 'any') return true;
+ if (from === to) return true;
+ // Widening only, and only where the reading side cannot be surprised:
+ // every number and bool has a string spelling, and a number is truthy or not.
+ if (to === 'string') return from === 'number' || from === 'bool';
+ if (to === 'bool') return from === 'number';
+ if (to === 'number') return from === 'bool' || from === 'entity';
+ return false;
+}
+
+/** Coerce a value to the port type reading it — the runtime half of {@link canConnect}. */
+export function coerceValue(value: ScriptValue, type: ScriptValueType): ScriptValue {
+ if (value === null || type === 'any' || type === 'exec') return value;
+ switch (type) {
+ case 'number':
+ case 'entity': {
+ if (typeof value === 'number') return value;
+ if (typeof value === 'boolean') return value ? 1 : 0;
+ const n = Number(value);
+ return Number.isFinite(n) ? n : 0;
+ }
+ case 'bool':
+ return typeof value === 'boolean' ? value : Boolean(value);
+ case 'string':
+ return typeof value === 'string' ? value : String(value);
+ }
+}
+
+/** The value a port of `type` holds before anything writes one. */
+export function defaultForType(type: ScriptValueType): ScriptValue {
+ switch (type) {
+ case 'number': return 0;
+ case 'entity': return 0;
+ case 'bool': return false;
+ case 'string': return '';
+ default: return null;
+ }
+}
diff --git a/sdk/tests/ai-action-params.test.ts b/sdk/tests/ai-action-params.test.ts
index f0a3dd898..bc11ed326 100644
--- a/sdk/tests/ai-action-params.test.ts
+++ b/sdk/tests/ai-action-params.test.ts
@@ -16,7 +16,7 @@ import {
type AiParams,
} from '../src/ai/fsm/registry';
import { Blackboard } from '../src/ai/fsm/Blackboard';
-import { aiRegistry, registerAction, type AiContext } from '../src/ai/fsm/AiContext';
+import { aiRegistry, registerAction, registerValue, type AiContext } from '../src/ai/fsm/AiContext';
const PAIR: AiParamDef[] = [
{ name: 'controller', type: 'enum' },
@@ -139,3 +139,61 @@ describe('the public registerAction', () => {
expect(seen).toBe('raw');
});
});
+
+/**
+ * A name declares what it TAKES and what it HANDS BACK. The second half is what
+ * a script graph reads off a wire; the first half was always there.
+ */
+describe('declared outputs', () => {
+ const bb = new Blackboard();
+ const ctx = {} as AiContext;
+
+ it('hands values back through the out record, leaving the return to the BT', () => {
+ registerAction('test.rollDice', {
+ params: [{ name: 'sides', type: 'number' }],
+ outputs: [{ name: 'value', type: 'number' }],
+ run: (_ctx, _bb, _arg, params, out) => {
+ if (out) out.value = Number(params?.sides ?? 0);
+ },
+ });
+
+ expect(aiRegistry.getActionOutputs('test.rollDice')).toEqual([{ name: 'value', type: 'number' }]);
+ const out: Record<string, string | number | boolean> = {};
+ const status = invokeAction(aiRegistry, 'test.rollDice', ctx, bb, { arg: '20' }, out);
+ expect(out).toEqual({ value: 20 });
+ expect(status).toBeUndefined();
+ });
+
+ it('a name with no `out` handed to it still runs — every caller need not want one', () => {
+ let ran = false;
+ registerAction('test.sideEffect', {
+ outputs: [{ name: 'ignored', type: 'bool' }],
+ run: () => { ran = true; },
+ });
+ invokeAction(aiRegistry, 'test.sideEffect', ctx, bb);
+ expect(ran).toBe(true);
+ });
+
+ it('registerValue lands in the SAME store, marked pure', () => {
+ registerValue('test.double', {
+ params: [{ name: 'n', type: 'number' }],
+ outputs: [{ name: 'result', type: 'number' }],
+ evaluate: (_ctx, _bb, params, out) => { out.result = Number(params.n ?? 0) * 2; },
+ });
+
+ expect(aiRegistry.hasAction('test.double')).toBe(true);
+ expect(aiRegistry.actionNames()).toContain('test.double');
+ expect(aiRegistry.isActionPure('test.double')).toBe(true);
+ expect(aiRegistry.isActionPure('test.rollDice')).toBe(false);
+
+ const out: Record<string, string | number | boolean> = {};
+ invokeAction(aiRegistry, 'test.double', ctx, bb, { params: { n: 21 } }, out);
+ expect(out).toEqual({ result: 42 });
+ });
+
+ it('an action that declares nothing declares nothing — not "no outputs, pure"', () => {
+ registerAction('test.bare', () => {});
+ expect(aiRegistry.getActionOutputs('test.bare')).toEqual([]);
+ expect(aiRegistry.isActionPure('test.bare')).toBe(false);
+ });
+});
diff --git a/sdk/tests/script-graph-runner.test.ts b/sdk/tests/script-graph-runner.test.ts
new file mode 100644
index 000000000..48cfdf0a6
--- /dev/null
+++ b/sdk/tests/script-graph-runner.test.ts
@@ -0,0 +1,357 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file script-graph-runner.test.ts
+ * @brief The script-graph interpreter's promises, each pinned on its own.
+ *
+ * These are the claims an author reads off the picture: pin 0 runs before pin 1,
+ * one wire is one value, a loop can end, and a loop that cannot end stops the
+ * instance instead of the frame.
+ */
+import { describe, it, expect } from 'vitest';
+import { AiRegistry } from '../src/ai/fsm/registry';
+import { Blackboard } from '../src/ai/fsm/Blackboard';
+import {
+ compileScriptGraph, createScriptRunState, stepScriptGraph, destroyScriptGraph,
+ fireScriptGraphEvent, type ScriptTickContext,
+} from '../src/logic/ScriptGraphRunner';
+import { SCRIPT_GRAPH_VERSION, type ScriptGraph, type ScriptGraphEdge, type ScriptGraphNode } from '../src/logic/types';
+
+interface TestCtx { log: string[]; }
+
+/** A registry of verbs whose every effect is visible in `ctx.log`. */
+function registry(): { reg: AiRegistry<TestCtx>; evaluations: { n: number } } {
+ const reg = new AiRegistry<TestCtx>();
+ const evaluations = { n: 0 };
+
+ reg.registerAction('test.say', {
+ params: [{ name: 'text', type: 'string' }],
+ run: (ctx, _bb, _arg, params) => { ctx.log.push(String(params?.text ?? '')); },
+ });
+ reg.registerAction('test.spawn', {
+ outputs: [{ name: 'entity', type: 'entity' }],
+ run: (ctx, _bb, _arg, _params, out) => {
+ ctx.log.push('spawn');
+ if (out) out.entity = 40 + ctx.log.length;
+ },
+ });
+ reg.registerValue('test.tick', {
+ outputs: [{ name: 'n', type: 'number' }],
+ evaluate: (_ctx, _bb, _params, out) => { out.n = ++evaluations.n; },
+ });
+ 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); },
+ });
+ reg.registerValue('test.lessThan', {
+ params: [{ name: 'a', type: 'number' }, { name: 'b', type: 'number' }],
+ outputs: [{ name: 'result', type: 'bool' }],
+ evaluate: (_ctx, _bb, params, out) => { out.result = Number(params.a ?? 0) < Number(params.b ?? 0); },
+ });
+ return { reg, evaluations };
+}
+
+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[], variables?: ScriptGraph['variables']): ScriptGraph {
+ return { version: SCRIPT_GRAPH_VERSION, nodes, edges, ...(variables ? { variables } : {}) };
+}
+
+interface Run {
+ log: string[];
+ problems: string[];
+ tick(dt?: number): void;
+ destroy(): void;
+ fire(type: string, target?: number): void;
+ halted(): boolean;
+}
+
+function run(graph: ScriptGraph, reg: AiRegistry<TestCtx>, budget?: number): Run {
+ const compiled = compileScriptGraph(graph, reg);
+ const state = createScriptRunState(compiled);
+ const ctx: TestCtx = { log: [] };
+ const problems: string[] = [...compiled.problems];
+ const tickCtx = (dt: number): ScriptTickContext<TestCtx> => ({
+ ctx, bb: new Blackboard(), registry: reg, dt,
+ onProblem: (m) => problems.push(m),
+ ...(budget === undefined ? {} : { budget }),
+ });
+ return {
+ log: ctx.log,
+ problems,
+ tick: (dt = 1 / 60) => stepScriptGraph(compiled, state, tickCtx(dt)),
+ destroy: () => destroyScriptGraph(compiled, state, tickCtx(0)),
+ fire: (type, target = 7) => fireScriptGraphEvent(compiled, state, tickCtx(0), type, target),
+ halted: () => state.halted,
+ };
+}
+
+describe('exec flows depth-first', () => {
+ it('finishes pin 0s whole chain before pin 1 starts', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('seq', 'flow.sequence', { literals: { count: 2 } }),
+ node('a1', 'call', { ref: 'test.say', literals: { text: 'a1' } }),
+ node('a2', 'call', { ref: 'test.say', literals: { text: 'a2' } }),
+ node('b1', 'call', { ref: 'test.say', literals: { text: 'b1' } }),
+ ], [
+ edge('start', 'then', 'seq', ''),
+ edge('seq', '0', 'a1', ''),
+ edge('a1', 'then', 'a2', ''),
+ edge('seq', '1', 'b1', ''),
+ ]);
+ const r = run(g, reg);
+ r.tick();
+ expect(r.log).toEqual(['a1', 'a2', 'b1']);
+ });
+
+ it('branches on the value its condition wire carries', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('lt', 'call', { ref: 'test.lessThan', literals: { a: 1, b: 2 } }),
+ node('br', 'flow.branch'),
+ node('yes', 'call', { ref: 'test.say', literals: { text: 'yes' } }),
+ node('no', 'call', { ref: 'test.say', literals: { text: 'no' } }),
+ ], [
+ edge('start', 'then', 'br', ''),
+ edge('lt', 'result', 'br', 'cond'),
+ edge('br', 'true', 'yes', ''),
+ edge('br', 'false', 'no', ''),
+ ]);
+ expect(runOnce(g, reg)).toEqual(['yes']);
+ });
+
+ it('runs event.start once and event.update every tick', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('upd', 'event.update'),
+ node('s', 'call', { ref: 'test.say', literals: { text: 'start' } }),
+ node('u', 'call', { ref: 'test.say', literals: { text: 'update' } }),
+ ], [edge('start', 'then', 's', ''), edge('upd', 'then', 'u', '')]);
+ const r = run(g, reg);
+ r.tick();
+ r.tick();
+ expect(r.log).toEqual(['start', 'update', 'update']);
+ });
+
+ it('runs event.destroy only on teardown', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('bye', 'event.destroy'),
+ node('s', 'call', { ref: 'test.say', literals: { text: 'bye' } }),
+ ], [edge('bye', 'then', 's', '')]);
+ const r = run(g, reg);
+ r.tick();
+ expect(r.log).toEqual([]);
+ r.destroy();
+ expect(r.log).toEqual(['bye']);
+ });
+});
+
+describe('data is pulled', () => {
+ it('takes the literal when no wire arrives, the wire when one does', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('sum', 'call', { ref: 'test.add', literals: { a: 2, b: 3 } }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [edge('start', 'then', 'say', ''), edge('sum', 'sum', 'say', 'text')]);
+ expect(runOnce(g, reg)).toEqual(['5']);
+ });
+
+ it('evaluates a pure node once per activation of the node reading it', () => {
+ const { reg, evaluations } = registry();
+ // One `test.tick` feeding BOTH inputs of one add: the author sees one
+ // wire leaving it, so both pins must see the same number.
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('t', 'call', { ref: 'test.tick' }),
+ node('sum', 'call', { ref: 'test.add' }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [
+ edge('start', 'then', 'say', ''),
+ edge('t', 'n', 'sum', 'a'),
+ edge('t', 'n', 'sum', 'b'),
+ edge('sum', 'sum', 'say', 'text'),
+ ]);
+ const r = run(g, reg);
+ r.tick();
+ expect(evaluations.n).toBe(1);
+ expect(r.log).toEqual(['2']);
+ });
+
+ it('re-evaluates a pure node on the next activation', () => {
+ const { reg, evaluations } = registry();
+ const g = graphOf([
+ node('upd', 'event.update'),
+ node('t', 'call', { ref: 'test.tick' }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [edge('upd', 'then', 'say', ''), edge('t', 'n', 'say', 'text')]);
+ const r = run(g, reg);
+ r.tick();
+ r.tick();
+ expect(evaluations.n).toBe(2);
+ expect(r.log).toEqual(['1', '2']);
+ });
+
+ it('reads what an effectful node last handed back', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('sp', 'call', { ref: 'test.spawn' }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [
+ edge('start', 'then', 'sp', ''),
+ edge('sp', 'then', 'say', ''),
+ edge('sp', 'entity', 'say', 'text'),
+ ]);
+ expect(runOnce(g, reg)).toEqual(['spawn', '41']);
+ });
+
+ it('publishes the event target on the entry that heard it', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('on', 'event.on', { literals: { type: 'click' } }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [edge('on', 'then', 'say', ''), edge('on', 'target', 'say', 'text')]);
+ const r = run(g, reg);
+ r.fire('other');
+ expect(r.log).toEqual([]);
+ r.fire('click', 12);
+ expect(r.log).toEqual(['12']);
+ });
+});
+
+describe('variables belong to the instance', () => {
+ it('starts at the declared default and keeps what was written', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('upd', 'event.update'),
+ node('get', 'var.get', { literals: { name: 'count' } }),
+ node('inc', 'call', { ref: 'test.add', literals: { b: 1 } }),
+ node('set', 'var.set', { literals: { name: 'count' } }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [
+ edge('upd', 'then', 'set', ''),
+ edge('get', 'value', 'inc', 'a'),
+ edge('inc', 'sum', 'set', 'value'),
+ edge('set', 'then', 'say', ''),
+ edge('get', 'value', 'say', 'text'),
+ ], [{ name: 'count', type: 'number', default: 10 }]);
+ const r = run(g, reg);
+ r.tick();
+ r.tick();
+ // `say` reads the variable on its OWN activation, after `set` wrote it.
+ expect(r.log).toEqual(['11', '12']);
+ });
+});
+
+describe('a loop can end, and one that cannot is stopped', () => {
+ it('leaves flow.while when its condition goes false', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('i', 'var.get', { literals: { name: 'i' } }),
+ node('lt', 'call', { ref: 'test.lessThan', literals: { b: 3 } }),
+ node('w', 'flow.while'),
+ node('inc', 'call', { ref: 'test.add', literals: { b: 1 } }),
+ node('set', 'var.set', { literals: { name: 'i' } }),
+ node('body', 'call', { ref: 'test.say', literals: { text: 'x' } }),
+ node('done', 'call', { ref: 'test.say', literals: { text: 'done' } }),
+ ], [
+ edge('start', 'then', 'w', ''),
+ edge('i', 'value', 'lt', 'a'),
+ edge('lt', 'result', 'w', 'cond'),
+ edge('w', 'body', 'body', ''),
+ edge('body', 'then', 'set', ''),
+ edge('i', 'value', 'inc', 'a'),
+ edge('inc', 'sum', 'set', 'value'),
+ edge('w', 'done', 'done', ''),
+ ], [{ name: 'i', type: 'number', default: 0 }]);
+ const r = run(g, reg);
+ r.tick();
+ expect(r.log).toEqual(['x', 'x', 'x', 'done']);
+ expect(r.halted()).toBe(false);
+ });
+
+ it('stops the instance at the budget, names the node, and says so once', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('w', 'flow.while', { literals: { cond: true } }),
+ node('body', 'call', { ref: 'test.say', literals: { text: 'x' } }),
+ ], [
+ edge('start', 'then', 'w', ''),
+ edge('w', 'body', 'body', ''),
+ edge('body', 'then', 'w', ''),
+ ]);
+ const r = run(g, reg, 20);
+ r.tick();
+ expect(r.halted()).toBe(true);
+ expect(r.problems).toHaveLength(1);
+ expect(r.problems[0]).toContain('step budget');
+ const after = r.log.length;
+ r.tick();
+ expect(r.log).toHaveLength(after);
+ expect(r.problems).toHaveLength(1);
+ });
+});
+
+describe('flow.delay waits without blocking the frame', () => {
+ it('continues on the tick its time is up', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('d', 'flow.delay', { literals: { seconds: 0.1 } }),
+ node('say', 'call', { ref: 'test.say', literals: { text: 'late' } }),
+ ], [edge('start', 'then', 'd', ''), edge('d', 'then', 'say', '')]);
+ const r = run(g, reg);
+ r.tick(0.06);
+ expect(r.log).toEqual([]);
+ r.tick(0.06);
+ expect(r.log).toEqual(['late']);
+ r.tick(0.06);
+ expect(r.log).toEqual(['late']);
+ });
+});
+
+describe('a graph that asks for what is not there says so', () => {
+ it('reports an unregistered name at compile rather than running past it', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('nope', 'call', { ref: 'test.missing' }),
+ ], [edge('start', 'then', 'nope', '')]);
+ const r = run(g, reg);
+ expect(r.problems.some((p) => p.includes('test.missing'))).toBe(true);
+ });
+
+ it('reports a data cycle instead of recursing forever', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('a', 'call', { ref: 'test.add' }),
+ node('say', 'call', { ref: 'test.say' }),
+ ], [
+ edge('start', 'then', 'say', ''),
+ edge('a', 'sum', 'a', 'a'),
+ edge('a', 'sum', 'say', 'text'),
+ ]);
+ const r = run(g, reg);
+ r.tick();
+ expect(r.problems.some((p) => p.includes('cycle'))).toBe(true);
+ });
+});
+
+function runOnce(g: ScriptGraph, reg: AiRegistry<TestCtx>): string[] {
+ const r = run(g, reg);
+ r.tick();
+ return r.log;
+}
diff --git a/sdk/tests/script-graph-shape.test.ts b/sdk/tests/script-graph-shape.test.ts
new file mode 100644
index 000000000..6c7d0aae2
--- /dev/null
+++ b/sdk/tests/script-graph-shape.test.ts
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file script-graph-shape.test.ts
+ * @brief What a node's pins are, and which wires are legal.
+ *
+ * Both answers have two readers — the interpreter and the canvas — and the
+ * point of pinning them here is that neither reader gets to hold its own copy.
+ */
+import { describe, it, expect } from 'vitest';
+import { AiRegistry } from '../src/ai/fsm/registry';
+import { describeNode, BUILTIN_NODE_KINDS } from '../src/logic/nodes';
+import { canConnect, coerceValue, emptyScriptGraph, type ScriptGraph } from '../src/logic/types';
+
+const catalog = (): AiRegistry<unknown> => {
+ const reg = new AiRegistry<unknown>();
+ reg.registerAction('demo.move', {
+ params: [{ name: 'speed', type: 'number' }, { name: 'mode', type: 'enum' }],
+ run: () => {},
+ });
+ reg.registerValue('demo.distance', {
+ params: [{ name: 'to', type: 'number' }],
+ outputs: [{ name: 'meters', type: 'number' }],
+ evaluate: (_c, _b, _p, out) => { out.meters = 1; },
+ });
+ return reg;
+};
+
+const graph = (over: Partial<ScriptGraph> = {}): ScriptGraph => ({ ...emptyScriptGraph(), ...over });
+
+describe('a call node takes its pins from what the name declared', () => {
+ it('turns declared parameters into inputs and declared outputs into outputs', () => {
+ const shape = describeNode({ id: 'n', kind: 'call', ref: 'demo.move' }, graph(), catalog());
+ expect(shape?.inputs).toEqual([
+ { name: 'speed', type: 'number', label: undefined },
+ // An `enum` is a choice of strings: a control kind, not a wire type.
+ { name: 'mode', type: 'string', label: undefined },
+ ]);
+ expect(shape?.execIn).toBe(true);
+ expect(shape?.execOut).toEqual(['then']);
+ expect(shape?.pure).toBe(false);
+ });
+
+ it('gives a pure name no exec pins at all', () => {
+ const shape = describeNode({ id: 'n', kind: 'call', ref: 'demo.distance' }, graph(), catalog());
+ expect(shape?.pure).toBe(true);
+ expect(shape?.execIn).toBe(false);
+ expect(shape?.execOut).toEqual([]);
+ expect(shape?.outputs).toEqual([{ name: 'meters', type: 'number', label: undefined }]);
+ });
+
+ it('is null for a name nothing registered — an unknown node is not an empty one', () => {
+ expect(describeNode({ id: 'n', kind: 'call', ref: 'demo.nope' }, graph(), catalog())).toBeNull();
+ expect(describeNode({ id: 'n', kind: 'no.such.kind' }, graph(), catalog())).toBeNull();
+ });
+});
+
+describe('the built-in kinds', () => {
+ it('all describe themselves', () => {
+ for (const kind of BUILTIN_NODE_KINDS) {
+ expect(describeNode({ id: 'n', kind }, graph(), catalog()), kind).not.toBeNull();
+ }
+ });
+
+ it('sizes flow.sequence from its authored pin count, not from its wires', () => {
+ const shape = (count?: number) => describeNode(
+ { id: 'n', kind: 'flow.sequence', ...(count === undefined ? {} : { literals: { count } }) },
+ graph(), catalog(),
+ );
+ expect(shape()?.execOut).toEqual(['0', '1']);
+ expect(shape(4)?.execOut).toEqual(['0', '1', '2', '3']);
+ // A pin count out of range is clamped, never zero pins or a runaway.
+ expect(shape(0)?.execOut).toEqual(['0']);
+ expect(shape(999)?.execOut).toHaveLength(16);
+ });
+
+ it('types a variable pin from the declaration, and `any` without one', () => {
+ const g = graph({ variables: [{ name: 'hp', type: 'number' }] });
+ const get = describeNode({ id: 'n', kind: 'var.get', literals: { name: 'hp' } }, g, catalog());
+ expect(get?.outputs).toEqual([{ name: 'value', type: 'number' }]);
+ const missing = describeNode({ id: 'n', kind: 'var.get', literals: { name: 'gone' } }, g, catalog());
+ expect(missing?.outputs).toEqual([{ name: 'value', type: 'any' }]);
+ });
+});
+
+describe('canConnect', () => {
+ it('keeps the exec wire to itself', () => {
+ expect(canConnect('exec', 'exec')).toBe(true);
+ expect(canConnect('exec', 'number')).toBe(false);
+ expect(canConnect('number', 'exec')).toBe(false);
+ });
+
+ it('widens only where the reading side cannot be surprised', () => {
+ expect(canConnect('number', 'string')).toBe(true);
+ expect(canConnect('bool', 'number')).toBe(true);
+ expect(canConnect('entity', 'number')).toBe(true);
+ expect(canConnect('string', 'number')).toBe(false);
+ expect(canConnect('number', 'entity')).toBe(false);
+ });
+
+ it('lets `any` meet anything, in both directions', () => {
+ expect(canConnect('any', 'number')).toBe(true);
+ expect(canConnect('string', 'any')).toBe(true);
+ });
+});
+
+describe('coerceValue is the runtime half of canConnect', () => {
+ it('converts what canConnect allows', () => {
+ expect(coerceValue(3, 'string')).toBe('3');
+ expect(coerceValue(true, 'number')).toBe(1);
+ expect(coerceValue(0, 'bool')).toBe(false);
+ expect(coerceValue('nonsense', 'number')).toBe(0);
+ });
+
+ it('leaves null alone — an unset port is not a zero anyone wrote', () => {
+ expect(coerceValue(null, 'number')).toBeNull();
+ });
+});
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index 52f010b1a..4cd3ea4f3 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -252,6 +252,16 @@ export const SUBSYSTEMS = [
whyZh: '刻意排在后面:0.50 冻的是「一个游戏由什么构成」,建立在其上的层要等下面这些定下来',
entry: ['Nav', 'NavAgent', 'StateMachineAgent', 'BehaviorTreeAgent', 'Perception'],
},
+ {
+ id: 'script-graph',
+ title: 'Script graphs — visual logic',
+ titleZh: '脚本图 —— 可视化逻辑',
+ source: ['logic'],
+ tier: 'experimental',
+ why: 'the node vocabulary is still growing: a name that gains an output changes what an authored graph can read, so the shape is not one to freeze yet',
+ whyZh: '节点词汇表还在长:一个名字多一个输出就改变了已画好的图能读到什么,形状还不到冻结的时候',
+ entry: ['compileScriptGraph', 'stepScriptGraph', 'describeNode', 'canConnect'],
+ },
{
id: 'networking',
title: 'Networking & replication',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 7099043f5..fe7914463 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(logic): a graph is nodes, wires, and one vocabulary it shares':
+ { internal: 'The script-graph core and the registry half it needs. Nothing authors one yet — no asset type, no component, no panel.' },
+
'fix(platform): a mini-game reads the file the package actually carries':
{ note: 'A mini-game package can read its own prefabs and materials.' },