Transactions and undo

Project operations produce versioned history. A standalone operation normally creates one undo entry. Group related operations in a transaction when users should undo them together.

Temporary scene shapes and camera actions do not become project history.

Python transaction

import spatialengine

with spatialengine.connect() as client:
    with spatialengine.Transaction(client, mode="Private") as txn:
        parent = txn.submit(client.std.object.unsafe.create_id_node, name="Group")
        child = txn.submit(client.std.object.unsafe.create_id_node, name="Child")
        txn.submit(client.std.object.append_child, node=parent, child=child)
        txn.commit()
    client.std.project.undo()

One undo removes the whole group. Leaving the context without committing cancels it. An exception also triggers cancellation.

TypeScript transaction

import { Transaction } from "@fslabs/spatialengine";

const txn = await Transaction.begin(client, { mode: "Private" });
try {
  const parent = await txn.submit(client.std.object.unsafe.createIdNode, { name: "Group" });
  const child = await txn.submit(client.std.object.unsafe.createIdNode, { name: "Child" });
  await txn.submit(client.std.object.appendChild, { node: parent, child });
  await txn.commit();
} catch (error) {
  try {
    await txn.cancel();
  } catch {}
  throw error;
}

For TypeScript code with explicit resource management enabled, await using disposes an uncommitted transaction by canceling it.

Shared and private transactions

A shared transaction is the default. It absorbs operations submitted while it is open, including untagged operations from other clients.

A private transaction admits only operations tagged with its ID. Use txn.submit to tag calls. Unrelated operations are rejected while it is open.

Choose the mode deliberately when more than one client controls an engine.

Completion and leases

Await every submitted operation before committing. Operations still in flight when the transaction ends are refused.

SDK transaction helpers renew a lease while the transaction is active. If the client disappears, the engine cancels the transaction when the lease expires. The default lease is 60 seconds.

A completed operation is not a committed transaction. Use the commit result as the completion of the batch.

Saving and collaboration

Undo history does not replace saving a project. Use the local project API for disk persistence or the remote project API for SpatialDrive. Shared project access is controlled by the server.

Client integration.