Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(logic): the edits a script-graph editor makes, and the rules they obey

esengine6867888dfe3f
diff --git a/desktop b/desktop
index db35feb00..910573d65 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit db35feb009ae30f5b91acad220b026c98fffe092
+Subproject commit 910573d65ea267a490201b6460b0bb3e032562d2
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 2031b27aa..54dd574cc 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": 1950,
+ "experimental": 1962,
"deprecated": 3
},
- "total": 2165,
+ "total": 2177,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 5d5735d7e..3d696e9a0 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 · 1789 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1801 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2519,6 +2519,7 @@ nodes: Map<string, ScriptGraphNode>
problems: string[]
shapes: Map<string, ScriptNodeShape>
starts: string[]
+starvedInputs: Map<string, string[]>
updates: string[]
```
@@ -11051,6 +11052,16 @@ TransformData
(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void
```
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
## addStartupSystem — function @public
```
(system: SystemDef): void
@@ -11441,6 +11452,11 @@ BtPlugin
(from: ScriptValueType, to: ScriptValueType): boolean
```
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11681,6 +11697,11 @@ BtPlugin
(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph
```
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
## contentHashHex — function @experimental
```
(data: Uint8Array): string
@@ -12011,6 +12032,16 @@ DiagnosticsPlugin
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
```
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
## discoverSceneAssets — function @experimental
```
(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs
@@ -13031,6 +13062,11 @@ MeshRendererPlugin
(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph
```
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
## moveState — function @experimental
```
(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
@@ -13626,6 +13662,21 @@ PrefabsPlugin
(g: MaterialGraph, id: string): MaterialGraph
```
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
## removeState — function @experimental
```
(def: FsmDefinition, name: string): FsmDefinition
@@ -13641,6 +13692,11 @@ PrefabsPlugin
(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
## renameState — function @experimental
```
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
@@ -14026,6 +14082,11 @@ ServicesPlugin
(active: boolean): void
```
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
## setStateHook — function @experimental
```
(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7f447c676..8c125349e 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 · 1808 experimental · 3 deprecated
+Symbols: 114 public · 99 beta · 1820 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2519,6 +2519,7 @@ nodes: Map<string, ScriptGraphNode>
problems: string[]
shapes: Map<string, ScriptNodeShape>
starts: string[]
+starvedInputs: Map<string, string[]>
updates: string[]
```
@@ -11244,6 +11245,16 @@ TransformData
(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void
```
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
## addStartupSystem — function @public
```
(system: SystemDef): void
@@ -11649,6 +11660,11 @@ BtPlugin
(from: ScriptValueType, to: ScriptValueType): boolean
```
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11889,6 +11905,11 @@ BtPlugin
(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph
```
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
## contentHashHex — function @experimental
```
(data: Uint8Array): string
@@ -12244,6 +12265,16 @@ DiagnosticsPlugin
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
```
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
## discoverSceneAssets — function @experimental
```
(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs
@@ -13274,6 +13305,11 @@ MeshRendererPlugin
(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph
```
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
## moveState — function @experimental
```
(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
@@ -13869,6 +13905,21 @@ PrefabsPlugin
(g: MaterialGraph, id: string): MaterialGraph
```
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
## removeState — function @experimental
```
(def: FsmDefinition, name: string): FsmDefinition
@@ -13884,6 +13935,11 @@ PrefabsPlugin
(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
## renameState — function @experimental
```
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
@@ -14269,6 +14325,11 @@ ServicesPlugin
(active: boolean): void
```
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
## setStateHook — function @experimental
```
(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ed3d92952..2135ab6be 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 · 1788 experimental · 3 deprecated
+Symbols: 114 public · 96 beta · 1800 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2514,6 +2514,7 @@ nodes: Map<string, ScriptGraphNode>
problems: string[]
shapes: Map<string, ScriptNodeShape>
starts: string[]
+starvedInputs: Map<string, string[]>
updates: string[]
```
@@ -11046,6 +11047,16 @@ TransformData
(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void
```
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
## addStartupSystem — function @public
```
(system: SystemDef): void
@@ -11436,6 +11447,11 @@ BtPlugin
(from: ScriptValueType, to: ScriptValueType): boolean
```
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11676,6 +11692,11 @@ BtPlugin
(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph
```
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
## contentHashHex — function @experimental
```
(data: Uint8Array): string
@@ -12006,6 +12027,16 @@ DiagnosticsPlugin
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
```
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
## discoverSceneAssets — function @experimental
```
(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs
@@ -13031,6 +13062,11 @@ MeshRendererPlugin
(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph
```
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
## moveState — function @experimental
```
(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
@@ -13631,6 +13667,21 @@ PrefabsPlugin
(g: MaterialGraph, id: string): MaterialGraph
```
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
## removeState — function @experimental
```
(def: FsmDefinition, name: string): FsmDefinition
@@ -13646,6 +13697,11 @@ PrefabsPlugin
(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
## renameState — function @experimental
```
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
@@ -14031,6 +14087,11 @@ ServicesPlugin
(active: boolean): void
```
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
## setStateHook — function @experimental
```
(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7c1f0bd88..f33c37a9b 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 · 1810 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1822 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2514,6 +2514,7 @@ nodes: Map<string, ScriptGraphNode>
problems: string[]
shapes: Map<string, ScriptNodeShape>
starts: string[]
+starvedInputs: Map<string, string[]>
updates: string[]
```
@@ -11300,6 +11301,16 @@ TransformData
(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void
```
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
## addStartupSystem — function @public
```
(system: SystemDef): void
@@ -11690,6 +11701,11 @@ BtPlugin
(from: ScriptValueType, to: ScriptValueType): boolean
```
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11930,6 +11946,11 @@ BtPlugin
(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph
```
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
## contentHashHex — function @experimental
```
(data: Uint8Array): string
@@ -12265,6 +12286,16 @@ DiagnosticsPlugin
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
```
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
## discoverSceneAssets — function @experimental
```
(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs
@@ -13295,6 +13326,11 @@ MeshRendererPlugin
(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph
```
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
## moveState — function @experimental
```
(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
@@ -13890,6 +13926,21 @@ PrefabsPlugin
(g: MaterialGraph, id: string): MaterialGraph
```
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
## removeState — function @experimental
```
(def: FsmDefinition, name: string): FsmDefinition
@@ -13905,6 +13956,11 @@ PrefabsPlugin
(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
## renameState — function @experimental
```
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
@@ -14290,6 +14346,11 @@ ServicesPlugin
(active: boolean): void
```
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
## setStateHook — function @experimental
```
(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index c170483b5..b93239b57 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 · 1800 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1812 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2514,6 +2514,7 @@ nodes: Map<string, ScriptGraphNode>
problems: string[]
shapes: Map<string, ScriptNodeShape>
starts: string[]
+starvedInputs: Map<string, string[]>
updates: string[]
```
@@ -11074,6 +11075,16 @@ TransformData
(acc: Pose, layer: Pose, reference: Pose, weight: number, world: PoseWorld, reach: LayerReach | null): void
```
+## addScriptNode — function @experimental
+```
+(graph: ScriptGraph, kind: string, x: number, y: number, ref?: string): { graph: ScriptGraph; id: string; }
+```
+
+## addScriptVariable — function @experimental
+```
+(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph
+```
+
## addStartupSystem — function @public
```
(system: SystemDef): void
@@ -11464,6 +11475,11 @@ BtPlugin
(from: ScriptValueType, to: ScriptValueType): boolean
```
+## canConnectPorts — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): boolean
+```
+
## canHaveChildren — function @experimental
```
(type: BtNodeType): boolean
@@ -11704,6 +11720,11 @@ BtPlugin
(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph
```
+## connectScriptNodes — function @experimental
+```
+(graph: ScriptGraph, catalog: ScriptVerbCatalog, from: string, fromPort: string, to: string, toPort: string): ScriptGraph
+```
+
## contentHashHex — function @experimental
```
(data: Uint8Array): string
@@ -12034,6 +12055,16 @@ DiagnosticsPlugin
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
```
+## disconnectScriptExec — function @experimental
+```
+(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph
+```
+
+## disconnectScriptInput — function @experimental
+```
+(graph: ScriptGraph, to: string, toPort: string): ScriptGraph
+```
+
## discoverSceneAssets — function @experimental
```
(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs
@@ -13059,6 +13090,11 @@ MeshRendererPlugin
(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph
```
+## moveScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph
+```
+
## moveState — function @experimental
```
(def: FsmDefinition, name: string, x: number, y: number): FsmDefinition
@@ -13654,6 +13690,21 @@ PrefabsPlugin
(g: MaterialGraph, id: string): MaterialGraph
```
+## removeScriptEdge — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptNode — function @experimental
+```
+(graph: ScriptGraph, id: string): ScriptGraph
+```
+
+## removeScriptVariable — function @experimental
+```
+(graph: ScriptGraph, name: string): ScriptGraph
+```
+
## removeState — function @experimental
```
(def: FsmDefinition, name: string): FsmDefinition
@@ -13669,6 +13720,11 @@ PrefabsPlugin
(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
+## renameScriptVariable — function @experimental
+```
+(graph: ScriptGraph, from: string, to: string): ScriptGraph
+```
+
## renameState — function @experimental
```
(def: FsmDefinition, oldName: string, newName: string): FsmDefinition
@@ -14054,6 +14110,11 @@ ServicesPlugin
(active: boolean): void
```
+## setScriptNodeLiteral — function @experimental
+```
+(graph: ScriptGraph, id: string, port: string, value: ScriptValue): ScriptGraph
+```
+
## setStateHook — function @experimental
```
(def: FsmDefinition, name: string, hook: "onEnter" | "onUpdate" | "onExit", action: string, arg?: string, params?: Record<string, AiParamValue>): FsmDefinition
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 148df5a4b..9f5bd5e31 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -1035,6 +1035,18 @@ export {
stepScriptGraphs,
scriptGraphTouches,
ensureBuiltinScriptNodes,
+ addScriptNode,
+ moveScriptNode,
+ removeScriptNode,
+ setScriptNodeLiteral,
+ canConnectPorts,
+ connectScriptNodes,
+ disconnectScriptInput,
+ disconnectScriptExec,
+ removeScriptEdge,
+ addScriptVariable,
+ removeScriptVariable,
+ renameScriptVariable,
type ScriptGraphAgentData,
} from './logic';
diff --git a/sdk/src/logic/ScriptGraphRunner.ts b/sdk/src/logic/ScriptGraphRunner.ts
index 062fe4a09..8f29c3f7d 100644
Binary files a/sdk/src/logic/ScriptGraphRunner.ts and b/sdk/src/logic/ScriptGraphRunner.ts differ
diff --git a/sdk/src/logic/graphOps.ts b/sdk/src/logic/graphOps.ts
new file mode 100644
index 000000000..b9caccc87
--- /dev/null
+++ b/sdk/src/logic/graphOps.ts
@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file graphOps.ts
+ * @brief Immutable edits on a ScriptGraph — the editor's model.
+ *
+ * Pure functions returning new graphs (never mutating), so the panel drives them
+ * through AssetDocument.edit for free undo, mirroring fsmGraph and btGraph. The
+ * wire rules live here rather than in the panel, because the loader has to apply
+ * the same ones to a file somebody wrote by hand.
+ */
+
+import { canConnect, type ScriptGraph, type ScriptGraphEdge, type ScriptGraphVariable, type ScriptValue } from './types';
+import { describeNode, type ScriptVerbCatalog } from './nodes';
+
+function clone(graph: ScriptGraph): ScriptGraph {
+ return JSON.parse(JSON.stringify(graph)) as ScriptGraph;
+}
+
+/** A node id nothing in the graph uses. Short and stable enough to read in a diff. */
+function freshId(graph: ScriptGraph, kind: string): string {
+ const stem = kind.replace(/[^a-z0-9]+/gi, '_').toLowerCase();
+ const taken = new Set(graph.nodes.map((n) => n.id));
+ for (let i = 1; ; i++) {
+ const id = `${stem}_${i}`;
+ if (!taken.has(id)) return id;
+ }
+}
+
+const edgeId = (from: string, fromPort: string, to: string, toPort: string): string =>
+ `${from}.${fromPort}->${to}.${toPort}`;
+
+/** Add a node of `kind` (a `call` carries the name it runs) at a canvas point. */
+export function addScriptNode(
+ graph: ScriptGraph, kind: string, x: number, y: number, ref?: string,
+): { graph: ScriptGraph; id: string } {
+ const next = clone(graph);
+ const id = freshId(graph, ref ?? kind);
+ next.nodes.push({ id, kind, ...(ref ? { ref } : {}), x, y });
+ return { graph: next, id };
+}
+
+export function moveScriptNode(graph: ScriptGraph, id: string, x: number, y: number): ScriptGraph {
+ const next = clone(graph);
+ const node = next.nodes.find((n) => n.id === id);
+ if (node) { node.x = x; node.y = y; }
+ return next;
+}
+
+/** Remove a node and every wire that touched it — a dangling wire is not a graph. */
+export function removeScriptNode(graph: ScriptGraph, id: string): ScriptGraph {
+ const next = clone(graph);
+ next.nodes = next.nodes.filter((n) => n.id !== id);
+ next.edges = next.edges.filter((e) => e.from !== id && e.to !== id);
+ return next;
+}
+
+export function setScriptNodeLiteral(
+ graph: ScriptGraph, id: string, port: string, value: ScriptValue,
+): ScriptGraph {
+ const next = clone(graph);
+ const node = next.nodes.find((n) => n.id === id);
+ if (node) (node.literals ??= {})[port] = value;
+ return next;
+}
+
+/**
+ * Whether a wire may be drawn. Both halves of the answer live here: the ports
+ * must exist and their types must meet.
+ */
+export function canConnectPorts(
+ graph: ScriptGraph, catalog: ScriptVerbCatalog,
+ from: string, fromPort: string, to: string, toPort: string,
+): boolean {
+ if (from === to) return false;
+ const fromNode = graph.nodes.find((n) => n.id === from);
+ const toNode = graph.nodes.find((n) => n.id === to);
+ if (!fromNode || !toNode) return false;
+ const fromShape = describeNode(fromNode, graph, catalog);
+ const toShape = describeNode(toNode, graph, catalog);
+ if (!fromShape || !toShape) return false;
+
+ if (fromShape.execOut.includes(fromPort)) return toShape.execIn && toPort === '';
+ const out = fromShape.outputs.find((p) => p.name === fromPort);
+ const inp = toShape.inputs.find((p) => p.name === toPort);
+ return !!out && !!inp && canConnect(out.type, inp.type);
+}
+
+/**
+ * Draw a wire, replacing whatever occupied the pin.
+ *
+ * An input takes ONE value and an exec pin hands control to ONE node: both ends
+ * of a replaced wire are unambiguous, and a second wire into either would make
+ * the picture stop saying what happens.
+ */
+export function connectScriptNodes(
+ graph: ScriptGraph, catalog: ScriptVerbCatalog,
+ from: string, fromPort: string, to: string, toPort: string,
+): ScriptGraph {
+ if (!canConnectPorts(graph, catalog, from, fromPort, to, toPort)) return graph;
+ const next = clone(graph);
+ const isExec = toPort === '';
+ next.edges = next.edges.filter((e) => (isExec
+ ? !(e.from === from && e.fromPort === fromPort)
+ : !(e.to === to && e.toPort === toPort)));
+ next.edges.push({ id: edgeId(from, fromPort, to, toPort), from, fromPort, to, toPort });
+ return next;
+}
+
+/** Cut the wire arriving at one input port. */
+export function disconnectScriptInput(graph: ScriptGraph, to: string, toPort: string): ScriptGraph {
+ const next = clone(graph);
+ next.edges = next.edges.filter((e) => !(e.to === to && e.toPort === toPort));
+ return next;
+}
+
+/** Cut the wire leaving one exec pin. */
+export function disconnectScriptExec(graph: ScriptGraph, from: string, fromPort: string): ScriptGraph {
+ const next = clone(graph);
+ next.edges = next.edges.filter((e) => !(e.from === from && e.fromPort === fromPort));
+ return next;
+}
+
+export function removeScriptEdge(graph: ScriptGraph, id: string): ScriptGraph {
+ const next = clone(graph);
+ next.edges = next.edges.filter((e) => e.id !== id);
+ return next;
+}
+
+/** Every wire, as the canvas wants them — exec wires land on the `''` input pin. */
+export function scriptGraphEdges(graph: ScriptGraph): readonly ScriptGraphEdge[] {
+ return graph.edges;
+}
+
+export function addScriptVariable(graph: ScriptGraph, variable: ScriptGraphVariable): ScriptGraph {
+ const next = clone(graph);
+ next.variables ??= [];
+ if (!next.variables.some((v) => v.name === variable.name)) next.variables.push(variable);
+ return next;
+}
+
+/**
+ * Drop a variable. The nodes naming it stay, and `describeNode` types their pin
+ * `any` — a delete that silently removed the nodes reading it would lose work
+ * the author can still see is wrong.
+ */
+export function removeScriptVariable(graph: ScriptGraph, name: string): ScriptGraph {
+ const next = clone(graph);
+ next.variables = (next.variables ?? []).filter((v) => v.name !== name);
+ return next;
+}
+
+/** Rename a variable, carrying every node that names it along with it. */
+export function renameScriptVariable(graph: ScriptGraph, from: string, to: string): ScriptGraph {
+ if (!to || from === to) return graph;
+ const next = clone(graph);
+ const variable = (next.variables ?? []).find((v) => v.name === from);
+ if (!variable || (next.variables ?? []).some((v) => v.name === to)) return graph;
+ variable.name = to;
+ for (const node of next.nodes) {
+ if ((node.kind === 'var.get' || node.kind === 'var.set') && node.literals?.name === from) {
+ node.literals.name = to;
+ }
+ }
+ return next;
+}
diff --git a/sdk/src/logic/index.ts b/sdk/src/logic/index.ts
index ce4930ffa..8493b58e5 100644
--- a/sdk/src/logic/index.ts
+++ b/sdk/src/logic/index.ts
@@ -69,3 +69,19 @@ export {
} from './ScriptGraphPlugin';
export { ensureBuiltinScriptNodes } from './builtinNodes';
+
+export {
+ addScriptNode,
+ moveScriptNode,
+ removeScriptNode,
+ setScriptNodeLiteral,
+ canConnectPorts,
+ connectScriptNodes,
+ disconnectScriptInput,
+ disconnectScriptExec,
+ removeScriptEdge,
+ scriptGraphEdges,
+ addScriptVariable,
+ removeScriptVariable,
+ renameScriptVariable,
+} from './graphOps';
diff --git a/sdk/tests/script-graph-ops.test.ts b/sdk/tests/script-graph-ops.test.ts
new file mode 100644
index 000000000..a3660b7cb
--- /dev/null
+++ b/sdk/tests/script-graph-ops.test.ts
@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file script-graph-ops.test.ts
+ * @brief The editor's edits, and the wire rules they enforce.
+ *
+ * The rules are here rather than in the panel because a hand-written file has to
+ * meet the same ones: an input takes one value, an exec pin hands control to one
+ * node, and a wire's ends have to agree on what they carry.
+ */
+import { describe, it, expect } from 'vitest';
+import { AiRegistry } from '../src/ai/fsm/registry';
+import {
+ addScriptNode, moveScriptNode, removeScriptNode, setScriptNodeLiteral,
+ canConnectPorts, connectScriptNodes, disconnectScriptInput, removeScriptEdge,
+ addScriptVariable, removeScriptVariable, renameScriptVariable,
+} from '../src/logic/graphOps';
+import { emptyScriptGraph, type ScriptGraph } from '../src/logic/types';
+import { describeNode } from '../src/logic/nodes';
+
+function catalog(): AiRegistry<unknown> {
+ const reg = new AiRegistry<unknown>();
+ reg.registerAction('demo.say', {
+ params: [{ name: 'text', type: 'string' }],
+ run: () => {},
+ });
+ reg.registerValue('demo.count', {
+ outputs: [{ name: 'n', type: 'number' }],
+ evaluate: (_c, _b, _p, out) => { out.n = 1; },
+ });
+ reg.registerValue('demo.flag', {
+ outputs: [{ name: 'on', type: 'bool' }],
+ evaluate: (_c, _b, _p, out) => { out.on = true; },
+ });
+ return reg;
+}
+
+/** start → say, with a count feeding the text. */
+function scene(): { graph: ScriptGraph; reg: AiRegistry<unknown> } {
+ const reg = catalog();
+ let graph = emptyScriptGraph('demo');
+ graph = addScriptNode(graph, 'event.start', 0, 0).graph;
+ graph = addScriptNode(graph, 'call', 200, 0, 'demo.say').graph;
+ graph = addScriptNode(graph, 'call', 60, 120, 'demo.count').graph;
+ return { graph, reg };
+}
+
+describe('adding and removing', () => {
+ it('gives each node an id nothing else has', () => {
+ let graph = emptyScriptGraph();
+ const a = addScriptNode(graph, 'flow.branch', 0, 0);
+ graph = a.graph;
+ const b = addScriptNode(graph, 'flow.branch', 0, 0);
+ expect(b.id).not.toBe(a.id);
+ expect(b.graph.nodes).toHaveLength(2);
+ });
+
+ it('takes every wire that touched a removed node with it', () => {
+ const { graph: g0, reg } = scene();
+ let graph = connectScriptNodes(g0, reg, 'event_start_1', 'then', 'demo_say_1', '');
+ graph = connectScriptNodes(graph, reg, 'demo_count_1', 'n', 'demo_say_1', 'text');
+ expect(graph.edges).toHaveLength(2);
+
+ graph = removeScriptNode(graph, 'demo_say_1');
+ expect(graph.edges).toEqual([]);
+ });
+
+ it('never mutates the graph it was handed', () => {
+ const { graph, reg } = scene();
+ const before = JSON.stringify(graph);
+ connectScriptNodes(graph, reg, 'event_start_1', 'then', 'demo_say_1', '');
+ moveScriptNode(graph, 'demo_say_1', 9, 9);
+ removeScriptNode(graph, 'demo_say_1');
+ setScriptNodeLiteral(graph, 'demo_say_1', 'text', 'hi');
+ expect(JSON.stringify(graph)).toBe(before);
+ });
+});
+
+describe('the wire rules', () => {
+ it('refuses a data wire whose ends disagree', () => {
+ const { graph: g0, reg } = scene();
+ let graph = addScriptNode(g0, 'call', 60, 240, 'demo.flag').graph;
+ graph = addScriptNode(graph, 'flow.branch', 320, 0).graph;
+
+ // A bool into a branch condition is the wire it is for.
+ expect(canConnectPorts(graph, reg, 'demo_flag_1', 'on', 'flow_branch_1', 'cond')).toBe(true);
+ // A number widens to a bool, a string does not.
+ expect(canConnectPorts(graph, reg, 'demo_count_1', 'n', 'flow_branch_1', 'cond')).toBe(true);
+ // And an exec pin never meets a data pin.
+ expect(canConnectPorts(graph, reg, 'event_start_1', 'then', 'flow_branch_1', 'cond')).toBe(false);
+ });
+
+ it('refuses a wire to a port that does not exist', () => {
+ const { graph, reg } = scene();
+ expect(canConnectPorts(graph, reg, 'demo_count_1', 'nope', 'demo_say_1', 'text')).toBe(false);
+ expect(connectScriptNodes(graph, reg, 'demo_count_1', 'nope', 'demo_say_1', 'text').edges).toEqual([]);
+ });
+
+ it('refuses a node wired to itself', () => {
+ const { graph, reg } = scene();
+ expect(canConnectPorts(graph, reg, 'demo_say_1', 'then', 'demo_say_1', '')).toBe(false);
+ });
+
+ it('replaces the wire on an input rather than stacking a second one', () => {
+ const { graph: g0, reg } = scene();
+ let graph = addScriptNode(g0, 'call', 60, 240, 'demo.flag').graph;
+ graph = connectScriptNodes(graph, reg, 'demo_count_1', 'n', 'demo_say_1', 'text');
+ graph = connectScriptNodes(graph, reg, 'demo_flag_1', 'on', 'demo_say_1', 'text');
+ expect(graph.edges).toHaveLength(1);
+ expect(graph.edges[0].from).toBe('demo_flag_1');
+ });
+
+ it('replaces the target of an exec pin rather than forking it', () => {
+ const { graph: g0, reg } = scene();
+ let graph = addScriptNode(g0, 'flow.branch', 320, 0).graph;
+ graph = connectScriptNodes(graph, reg, 'event_start_1', 'then', 'demo_say_1', '');
+ graph = connectScriptNodes(graph, reg, 'event_start_1', 'then', 'flow_branch_1', '');
+ expect(graph.edges).toHaveLength(1);
+ expect(graph.edges[0].to).toBe('flow_branch_1');
+ });
+
+ it('lets one exec pin per node keep its own target', () => {
+ const { graph: g0, reg } = scene();
+ let graph = addScriptNode(g0, 'flow.branch', 320, 0).graph;
+ graph = addScriptNode(graph, 'call', 500, 120, 'demo.say').graph;
+ graph = connectScriptNodes(graph, reg, 'flow_branch_1', 'true', 'demo_say_1', '');
+ graph = connectScriptNodes(graph, reg, 'flow_branch_1', 'false', 'demo_say_2', '');
+ expect(graph.edges).toHaveLength(2);
+ });
+
+ it('cuts one wire without disturbing the rest', () => {
+ const { graph: g0, reg } = scene();
+ let graph = connectScriptNodes(g0, reg, 'event_start_1', 'then', 'demo_say_1', '');
+ graph = connectScriptNodes(graph, reg, 'demo_count_1', 'n', 'demo_say_1', 'text');
+ graph = disconnectScriptInput(graph, 'demo_say_1', 'text');
+ expect(graph.edges).toHaveLength(1);
+ graph = removeScriptEdge(graph, graph.edges[0].id);
+ expect(graph.edges).toEqual([]);
+ });
+});
+
+describe('variables', () => {
+ it('renames every node that names it, and refuses a name already taken', () => {
+ const reg = catalog();
+ let graph = addScriptVariable(emptyScriptGraph(), { name: 'hp', type: 'number', default: 3 });
+ graph = addScriptVariable(graph, { name: 'shield', type: 'number' });
+ graph = addScriptNode(graph, 'var.get', 0, 0).graph;
+ graph = setScriptNodeLiteral(graph, 'var_get_1', 'name', 'hp');
+
+ graph = renameScriptVariable(graph, 'hp', 'health');
+ expect(graph.variables?.[0].name).toBe('health');
+ expect(graph.nodes[0].literals?.name).toBe('health');
+ expect(describeNode(graph.nodes[0], graph, reg)?.outputs[0].type).toBe('number');
+
+ // A collision leaves the graph exactly as it was.
+ expect(renameScriptVariable(graph, 'health', 'shield')).toBe(graph);
+ });
+
+ it('leaves the nodes behind when the variable goes, typed `any`', () => {
+ const reg = catalog();
+ let graph = addScriptVariable(emptyScriptGraph(), { name: 'hp', type: 'number' });
+ graph = addScriptNode(graph, 'var.get', 0, 0).graph;
+ graph = setScriptNodeLiteral(graph, 'var_get_1', 'name', 'hp');
+
+ graph = removeScriptVariable(graph, 'hp');
+ expect(graph.nodes).toHaveLength(1);
+ expect(describeNode(graph.nodes[0], graph, reg)?.outputs[0].type).toBe('any');
+ });
+});
diff --git a/sdk/tests/script-graph-runner.test.ts b/sdk/tests/script-graph-runner.test.ts
index 48cfdf0a6..d5323e90b 100644
--- a/sdk/tests/script-graph-runner.test.ts
+++ b/sdk/tests/script-graph-runner.test.ts
@@ -333,6 +333,26 @@ describe('a graph that asks for what is not there says so', () => {
expect(r.problems.some((p) => p.includes('test.missing'))).toBe(true);
});
+ it('does not run a node whose input wire has no source', () => {
+ const { reg } = registry();
+ const g = graphOf([
+ node('start', 'event.start'),
+ node('gone', 'call', { ref: 'test.missing' }),
+ node('say', 'call', { ref: 'test.say', literals: { text: 'fallback' } }),
+ node('after', 'call', { ref: 'test.say', literals: { text: 'after' } }),
+ ], [
+ edge('start', 'then', 'say', ''),
+ edge('gone', 'n', 'say', 'text'),
+ edge('say', 'then', 'after', ''),
+ ]);
+ const r = run(g, reg);
+ r.tick();
+ // Not `fallback`: the port's zero is a value nobody authored, and a node
+ // that runs on one writes nonsense downstream instead of stopping here.
+ expect(r.log).toEqual([]);
+ expect(r.problems.some((p) => p.includes('no source'))).toBe(true);
+ });
+
it('reports a data cycle instead of recursing forever', () => {
const { reg } = registry();
const g = graphOf([
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index f3f2868ff..94ffc0d0e 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,15 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(logic): a node starved of its input does not run on an invented value':
+ { internal: 'Inside the script graph, which no shipped corpus authors yet.' },
+
+ 'feat(logic): a script graph is something you can draw':
+ { internal: 'The editor half of the script graph. The whole feature gets one note once a shipped example authors a graph.' },
+
+ 'feat(logic): the edits a script-graph editor makes, and the rules they obey':
+ { internal: 'The graph ops the panel drives. No creator meets them except through that panel.' },
+
'feat(assets): a script graph is a live asset like the other authored graphs':
{ internal: 'The .esgraph asset slot. Nothing authors one yet — no panel, no new-asset entry.' },