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(editor): scoped edit transactions (commit/abort) over the gesture
esenginecdcf7e485c75
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex ba79df558..401d4ec0e 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -25,7 +25,7 @@ import type {} from '@/types';import type { SceneData, SubsystemStatus } from 'esengine';import { EngineHost } from './EngineHost';-import type { SceneCommandsImpl } from './SceneCommands';+import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';import type { SceneQueryImpl } from './SceneQuery';import type { SceneModelImpl } from './SceneModel';import type { EditorHistoryImpl } from './EditorHistory';@@ -135,6 +135,15 @@ export class EditorControlSurfaceImpl {endGesture(): void {this.s.commands.endGesture();}+ /** Open a scoped edit transaction (commit as one undo step, or abort to roll+ * back live). The handle form of begin/endGesture, with cancel support. */+ transaction(label: string): EditorTransaction {+ return this.s.commands.transaction(label);+ }+ /** Run `fn` inside a transaction: commit on return, abort + rethrow on throw. */+ transact(label: string, fn: () => void): void {+ this.s.commands.transact(label, fn);+ }// =========================================================================// Queries — read-only reflection of the session's scene model (the truth)diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 155b160be..15e069746 100644--- a/desktop/src/engine/SceneCommands.ts+++ b/desktop/src/engine/SceneCommands.ts@@ -25,6 +25,17 @@ export interface TilePaint {tileId: number;}+/**+ * A scoped edit transaction (the editor's FScopedTransaction). A burst of field+ * writes between open and `commit` collapses into one undo step; `abort` reverts+ * them live and records nothing. Hand it to a tool's drag so the stroke is one+ * undoable step with cancel support.+ */+export interface EditorTransaction {+ commit(): void;+ abort(): void;+}+// — Model-authoritative commands —//// Every mutation edits the SceneModel ONLY (the session's source of truth). The@@ -179,6 +190,44 @@ export class SceneCommandsImpl {);}+ /**+ * Cancel the current gesture: restore each touched field to its captured BEFORE+ * value (live — the viewport snaps back via the Reconciler) and discard it with+ * no undo step. Powers a tool drag's Esc-to-cancel.+ */+ abortGesture(): void {+ const g = this.gesture;+ this.gesture = null;+ if (!g) return;+ for (const e of g.touched.values()) this.model.setField(e.sourceId, e.comp, e.key, e.before);+ }++ /**+ * Open a scoped edit transaction over the coalescing gesture — the modern+ * handle form of {@link beginGesture}/{@link endGesture} with cancel support.+ * One transaction is active at a time (one stroke); the handle is idempotent.+ */+ transaction(label: string): EditorTransaction {+ this.beginGesture(label);+ let done = false;+ return {+ commit: () => { if (!done) { done = true; this.endGesture(); } },+ abort: () => { if (!done) { done = true; this.abortGesture(); } },+ };+ }++ /** Run `fn` inside a transaction: commit on return, abort + rethrow on throw. */+ transact(label: string, fn: () => void): void {+ const tx = this.transaction(label);+ try {+ fn();+ tx.commit();+ } catch (e) {+ tx.abort();+ throw e;+ }+ }+/*** Write a single inspector field to the model (the Reconciler re-projects it* to the World). Always undoable: coalesced into an open gesture, else its own step.diff --git a/desktop/tests/transaction.test.ts b/desktop/tests/transaction.test.tsnew file mode 100644index 000000000..b44025415--- /dev/null+++ b/desktop/tests/transaction.test.ts@@ -0,0 +1,93 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file SceneCommands transaction API — a scoped edit batches into one undo step+ * on commit, reverts live (no step) on abort. Pure TS (the model + undo+ * plumbing are real; no WASM).+ */+import { describe, it, expect, beforeEach } from 'vitest';+import type { SceneData } from 'esengine';+import { SceneModelImpl } from '@/engine/SceneModel';+import { EditorHistoryImpl } from '@/engine/EditorHistory';+import { SceneCommandsImpl } from '@/engine/SceneCommands';++function scene(): SceneData {+ return {+ version: '1.0',+ name: 't',+ entities: [+ {+ id: 1,+ name: 'E',+ parent: null,+ children: [],+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } } },+ ],+ },+ ],+ } as unknown as SceneData;+}++const posX = (m: SceneModelImpl): number =>+ ((m.entityBySource(1)!.components.find((c) => c.type === 'Transform')!.data as Record<string, { x: number }>).position).x;++describe('SceneCommands transaction', () => {+ let model: SceneModelImpl;+ let history: EditorHistoryImpl;+ let cmds: SceneCommandsImpl;++ beforeEach(() => {+ model = new SceneModelImpl();+ history = new EditorHistoryImpl();+ cmds = new SceneCommandsImpl(model, history);+ model.adopt(scene(), new Map([[1, 100]]));+ });++ it('commit coalesces a burst of edits into one undo step', () => {+ const tx = cmds.transaction('Move');+ cmds.setEntityXY(1, 5, 0);+ cmds.setEntityXY(1, 9, 0);+ tx.commit();+ expect(posX(model)).toBe(9);+ expect(history.canUndo()).toBe(true);+ history.undo();+ expect(posX(model)).toBe(0); // one step reverts the whole burst+ expect(history.canUndo()).toBe(false);+ });++ it('abort reverts live edits and records nothing', () => {+ const tx = cmds.transaction('Move');+ cmds.setEntityXY(1, 7, 0);+ expect(posX(model)).toBe(7); // applied live during the stroke+ tx.abort();+ expect(posX(model)).toBe(0); // restored to the captured BEFORE+ expect(history.canUndo()).toBe(false); // no undo step recorded+ });++ it('transact commits on return and aborts (rethrows) on throw', () => {+ cmds.transact('Batch', () => cmds.setEntityXY(1, 3, 0));+ expect(posX(model)).toBe(3);+ expect(history.canUndo()).toBe(true);++ expect(() =>+ cmds.transact('Bad', () => {+ cmds.setEntityXY(1, 8, 0);+ throw new Error('boom');+ }),+ ).toThrow('boom');+ expect(posX(model)).toBe(3); // aborted → back to the pre-transact value+ });++ it('handle is idempotent (double commit/abort is a no-op)', () => {+ const tx = cmds.transaction('Move');+ cmds.setEntityXY(1, 4, 0);+ tx.commit();+ tx.commit(); // no-op+ tx.abort(); // no-op+ expect(posX(model)).toBe(4);+ history.undo();+ expect(posX(model)).toBe(0);+ expect(history.canUndo()).toBe(false); // exactly one step was recorded+ });+});