Authoring Command Bus And Transaction History

The authoring command bus is the shared path for dry-run, apply, report, undo, redo, and rollback behavior across editor surfaces. It keeps scene repair, tile painting, dock actions, migrations, and NPC authoring from inventing incompatible command lifecycles.

Purpose

Use this page when adding an editor command, a batch repair, a migration action, or a content mutation that needs predictable reports and undo history.

Steps

Model the user intent as an authoring command with transaction metadata. Implement dry-run output before apply output. Return a command report that names changed records, skipped records, warnings, and fatal errors. Register the command with the surface that invokes it, then route successful apply operations into the relevant history lane.

For batch operations, keep each item result visible in the report. Authors should be able to tell which records changed and which were skipped.

Expected Outputs

A dry run should describe the planned mutation without changing content. Apply should mutate content, emit a report, and record a reversible transaction when the surface supports history. Undo/redo should restore content through the same lane rather than by re-running validation.

Command reports should be suitable for event-console routing and for validation follow-up.

Common Mistakes

Do not mutate content during dry run. Do not bypass transaction metadata because a command is "small". Do not attach a tile command to scene history if it has its own tile history lane. Do not discard skipped-item details in batch repair reports.

Avoid adding editor-only state changes to a command that should be replayable against content files.

Recovery Paths

If undo fails, inspect the lane history and transaction payload before changing the command body. If a command changes content but the UI does not refresh, inspect the surface registry and event/report emission. If dry run and apply disagree, compare the selection/filter logic in both paths.

For migration mistakes, prefer rollback through the transaction history when available, then rerun validation and bake.