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(sdk): Transaction / TransactionManager for editor undo-redo
esengineb474ae9e10ce
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 6c1997a68..f615e00e2 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -70,6 +70,7 @@ export {remapEntityFields,updateCameraAspectRatio,findEntityByName,+ serializeScene,getComponentAssetFields,getComponentAssetFieldDescriptors,getComponentSpineFieldDescriptor,diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 1fbcf8f42..3a20ebe63 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -209,6 +209,17 @@ export {type CommandsDescriptor,} from './commands';+// =============================================================================+// Transactions (editor undo/redo)+// =============================================================================++export {+ Transaction,+ TransactionManager,+ type TransactionOp,+ type TransactionManagerOptions,+} from './transaction';+// =============================================================================// System// =============================================================================diff --git a/sdk/src/transaction.ts b/sdk/src/transaction.tsnew file mode 100644index 000000000..b2aec5464--- /dev/null+++ b/sdk/src/transaction.ts@@ -0,0 +1,212 @@+/**+ * @file transaction.ts+ * @brief Undo/redo primitive for editor-driven mutation gestures+ *+ * The editor wraps one user gesture (a property edit, a drag, a paste) in+ * a Transaction. Each op in the transaction carries both its forward and+ * reverse closures so the pair can be replayed in either direction without+ * re-deriving state. TransactionManager holds the undo/redo stacks.+ */++import { log } from './logger';++// =============================================================================+// Types+// =============================================================================++/**+ * A single reversible mutation. `forward` applies the change; `reverse`+ * restores the pre-change state. Both closures are invoked at most once+ * per direction, and the pair is expected to be symmetric.+ */+export interface TransactionOp {+ forward(): void;+ reverse(): void;+}++// =============================================================================+// Transaction+// =============================================================================++export class Transaction {+ readonly id: string;+ readonly label: string;+ readonly timestamp: number;+ private readonly ops_: TransactionOp[] = [];++ constructor(label: string, id?: string) {+ this.id = id ?? genTransactionId();+ this.label = label;+ this.timestamp = Date.now();+ }++ /**+ * Appends an op to this transaction and runs its `forward` closure+ * immediately. Use `addDeferred` if the caller has already applied the+ * mutation and just wants to register a reverse.+ */+ add(op: TransactionOp): void {+ this.ops_.push(op);+ op.forward();+ }++ /**+ * Registers the reverse/forward pair without calling `forward` —+ * caller has already applied the mutation and just wants it undoable.+ */+ addDeferred(op: TransactionOp): void {+ this.ops_.push(op);+ }++ get opCount(): number {+ return this.ops_.length;+ }++ undo(): void {+ // Reverse in LIFO order so ops can legitimately depend on the+ // state left by earlier ops in the same transaction.+ for (let i = this.ops_.length - 1; i >= 0; i--) {+ try {+ this.ops_[i].reverse();+ } catch (e) {+ log.warn('transaction', `undo op ${i} of "${this.label}" threw`, e);+ }+ }+ }++ redo(): void {+ for (let i = 0; i < this.ops_.length; i++) {+ try {+ this.ops_[i].forward();+ } catch (e) {+ log.warn('transaction', `redo op ${i} of "${this.label}" threw`, e);+ }+ }+ }+}++// =============================================================================+// Transaction Manager+// =============================================================================++export interface TransactionManagerOptions {+ /** Hard cap on undo history. Oldest entries drop first. Default: 200. */+ historyLimit?: number;+}++export class TransactionManager {+ private readonly undoStack_: Transaction[] = [];+ private readonly redoStack_: Transaction[] = [];+ private readonly historyLimit_: number;+ private active_: Transaction | null = null;++ constructor(options?: TransactionManagerOptions) {+ this.historyLimit_ = options?.historyLimit ?? 200;+ }++ /**+ * Opens a transaction and returns it. Caller adds ops, then calls+ * `commit(tx)`. Only one transaction is active at a time — nested+ * begins throw, keeping the LIFO invariant clean.+ */+ begin(label: string): Transaction {+ if (this.active_ !== null) {+ throw new Error(+ `TransactionManager.begin("${label}"): transaction "${this.active_.label}" is already open`,+ );+ }+ this.active_ = new Transaction(label);+ return this.active_;+ }++ /**+ * Commits the active transaction onto the undo stack. Empty+ * transactions are dropped silently (keeps the stack uncluttered+ * when a gesture ends up being a no-op).+ */+ commit(tx: Transaction): void {+ if (tx !== this.active_) {+ throw new Error('TransactionManager.commit: transaction is not the active one');+ }+ this.active_ = null;++ if (tx.opCount === 0) return;++ this.undoStack_.push(tx);+ if (this.undoStack_.length > this.historyLimit_) {+ this.undoStack_.shift();+ }+ // Any new mutation invalidates the redo path.+ this.redoStack_.length = 0;+ }++ /**+ * Aborts the active transaction without committing. Ops that have+ * already been `add`-ed are reversed so the world returns to the+ * pre-begin state.+ */+ rollback(tx: Transaction): void {+ if (tx !== this.active_) {+ throw new Error('TransactionManager.rollback: transaction is not the active one');+ }+ this.active_ = null;+ tx.undo();+ }++ undo(): Transaction | null {+ if (this.active_) {+ log.warn('transaction', `undo called while transaction "${this.active_.label}" is open`);+ return null;+ }+ const tx = this.undoStack_.pop();+ if (!tx) return null;+ tx.undo();+ this.redoStack_.push(tx);+ return tx;+ }++ redo(): Transaction | null {+ if (this.active_) {+ log.warn('transaction', `redo called while transaction "${this.active_.label}" is open`);+ return null;+ }+ const tx = this.redoStack_.pop();+ if (!tx) return null;+ tx.redo();+ this.undoStack_.push(tx);+ return tx;+ }++ canUndo(): boolean {+ return this.active_ === null && this.undoStack_.length > 0;+ }++ canRedo(): boolean {+ return this.active_ === null && this.redoStack_.length > 0;+ }++ peekUndo(): Transaction | null {+ return this.undoStack_.length > 0 ? this.undoStack_[this.undoStack_.length - 1] : null;+ }++ peekRedo(): Transaction | null {+ return this.redoStack_.length > 0 ? this.redoStack_[this.redoStack_.length - 1] : null;+ }++ /** Clears both undo and redo stacks. Use on scene load / project switch. */+ clear(): void {+ this.undoStack_.length = 0;+ this.redoStack_.length = 0;+ this.active_ = null;+ }+}++// =============================================================================+// Helpers+// =============================================================================++let nextTxSeq_ = 0;+function genTransactionId(): string {+ nextTxSeq_++;+ return `tx-${Date.now().toString(36)}-${nextTxSeq_.toString(36)}`;+}