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): the edits a script-graph editor makes, and the rules they obey
esengine6867888dfe3f
diff --git a/desktop b/desktopindex db35feb00..910573d65 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit db35feb009ae30f5b91acad220b026c98fffe092+Subproject commit 910573d65ea267a490201b6460b0bb3e032562d2diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mdindex 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>): FsmDefinitiondiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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>): FsmDefinitiondiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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>): FsmDefinitiondiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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>): FsmDefinitiondiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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>): FsmDefinitiondiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 062fe4a09..8f29c3f7d 100644Binary files a/sdk/src/logic/ScriptGraphRunner.ts and b/sdk/src/logic/ScriptGraphRunner.ts differdiff --git a/sdk/src/logic/graphOps.ts b/sdk/src/logic/graphOps.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.mjsindex 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.' },