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(editor): scoped edit transactions (commit/abort) over the gesture

esenginecdcf7e485c75
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 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.ts
index 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.ts
new file mode 100644
index 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
+ });
+});