A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(logic): a graph 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.jsonindex 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.mdindex 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: AdsAPIbb: 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[] | undefinedparams: readonly AiParamDef[] | undefined+pure: boolean | undefinedrun: AiAction<Ctx>separator: string | undefinedtouches: AiTouchesSource | undefined@@ -216,6 +219,19 @@ world: WorldResourceDef<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: () => voidconditionNames: () => string[]conditionTouches: (name: string) => AiTouches | undefinedgetAction: (name: string) => AiAction<Ctx> | undefined+getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]getActionSeparator: (name: string) => stringgetCondition: (name: string) => AiCondition<Ctx> | undefinedhasAction: (name: string) => booleanhasCondition: (name: string) => boolean+isActionPure: (name: string) => booleanregisterAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => voidregisterCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void+registerValue: (name: string, spec: AiValueSpec<Ctx>) => voidstatic 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: stringstates: 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 | undefinedscaleMode: 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): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: AdsAPIbb: 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[] | undefinedparams: readonly AiParamDef[] | undefined+pure: boolean | undefinedrun: AiAction<Ctx>separator: string | undefinedtouches: AiTouchesSource | undefined@@ -216,6 +219,19 @@ world: WorldResourceDef<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: () => voidconditionNames: () => string[]conditionTouches: (name: string) => AiTouches | undefinedgetAction: (name: string) => AiAction<Ctx> | undefined+getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]getActionSeparator: (name: string) => stringgetCondition: (name: string) => AiCondition<Ctx> | undefinedhasAction: (name: string) => booleanhasCondition: (name: string) => boolean+isActionPure: (name: string) => booleanregisterAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => voidregisterCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void+registerValue: (name: string, spec: AiValueSpec<Ctx>) => voidstatic 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: stringstates: 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 | undefinedscaleMode: 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): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: AdsAPIbb: 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[] | undefinedparams: readonly AiParamDef[] | undefined+pure: boolean | undefinedrun: AiAction<Ctx>separator: string | undefinedtouches: AiTouchesSource | undefined@@ -211,6 +214,19 @@ world: WorldResourceDef<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: () => voidconditionNames: () => string[]conditionTouches: (name: string) => AiTouches | undefinedgetAction: (name: string) => AiAction<Ctx> | undefined+getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]getActionSeparator: (name: string) => stringgetCondition: (name: string) => AiCondition<Ctx> | undefinedhasAction: (name: string) => booleanhasCondition: (name: string) => boolean+isActionPure: (name: string) => booleanregisterAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => voidregisterCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void+registerValue: (name: string, spec: AiValueSpec<Ctx>) => voidstatic 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: stringstates: 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 | undefinedscaleMode: 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): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: AdsAPIbb: 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[] | undefinedparams: readonly AiParamDef[] | undefined+pure: boolean | undefinedrun: AiAction<Ctx>separator: string | undefinedtouches: AiTouchesSource | undefined@@ -211,6 +214,19 @@ world: WorldResourceDef<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: () => voidconditionNames: () => string[]conditionTouches: (name: string) => AiTouches | undefinedgetAction: (name: string) => AiAction<Ctx> | undefined+getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]getActionSeparator: (name: string) => stringgetCondition: (name: string) => AiCondition<Ctx> | undefinedhasAction: (name: string) => booleanhasCondition: (name: string) => boolean+isActionPure: (name: string) => booleanregisterAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => voidregisterCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void+registerValue: (name: string, spec: AiValueSpec<Ctx>) => voidstatic 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: stringstates: 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 | undefinedscaleMode: 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): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: AdsAPIbb: 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[] | undefinedparams: readonly AiParamDef[] | undefined+pure: boolean | undefinedrun: AiAction<Ctx>separator: string | undefinedtouches: AiTouchesSource | undefined@@ -211,6 +214,19 @@ world: WorldResourceDef<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: () => voidconditionNames: () => string[]conditionTouches: (name: string) => AiTouches | undefinedgetAction: (name: string) => AiAction<Ctx> | undefined+getActionOutputs: (name: string) => readonly AiOutputDef[]getActionParams: (name: string) => readonly AiParamDef[]getActionSeparator: (name: string) => stringgetCondition: (name: string) => AiCondition<Ctx> | undefinedhasAction: (name: string) => booleanhasCondition: (name: string) => boolean+isActionPure: (name: string) => booleanregisterAction: (name: string, fn: AiAction<Ctx> | AiActionSpec<Ctx>) => voidregisterCondition: (name: string, fn: AiCondition<Ctx> | AiConditionSpec<Ctx>) => void+registerValue: (name: string, spec: AiValueSpec<Ctx>) => voidstatic 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: stringstates: 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 | undefinedscaleMode: 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): voiddiff --git a/sdk/src/ai/fsm/AiContext.ts b/sdk/src/ai/fsm/AiContext.tsindex 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> | AiActionSexport 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 000000000..062fe4a09Binary files /dev/null and b/sdk/src/logic/ScriptGraphRunner.ts differdiff --git a/sdk/src/logic/index.ts b/sdk/src/logic/index.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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.mjsindex 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.' },