Blacksite/docs/adr/0041-transactional-editor-physics-placement.md

ADR 0041: Transactional Editor Physics Placement

Status

Accepted

Context

The editor and game share one Bevy world and one Avian physics instance. Authored rigid bodies are hydrated in Edit mode so collider visualization and queries remain available, but advancing the shared simulation while editing mutates scene transforms outside history. A physics-placement tool must use the real runtime colliders while preventing unrelated dynamic bodies, PIE state, or authored physics settings from changing.

Running a second physics world would duplicate hydration, imported-mesh collider cooking, and hierarchy mapping. Advancing the existing world without isolation would make placement dependent on every other movable body in the scene and would violate cancel safety.

Decision

The editor owns Avian's Time<Physics> clock:

• normal Edit mode and paused Play mode keep physics paused;
• active Play mode unpauses physics;
• paused Play single-step advances the physics clock by one fixed tick;
• the placement tool advances bounded 120 Hz steps while Edit mode remains paused.

Physics placement is a transactional preview in the shared world. It snapshots the selected bodies' local transforms and runtime motion components, temporarily makes them dynamic, and temporarily makes every other movable rigid body static. Static bodies and all colliders stay in the same world, preserving production collision fidelity. Commit restores every temporary runtime override and writes only the final local transforms through one grouped history command. Cancel restores the full snapshot and writes no history.

Consequences

• Edit mode no longer permits authored dynamic bodies to drift outside undo history.
• Placement uses the exact hydrated collider geometry used by PIE and the standalone game.
• Kinematic and dynamic non-selected bodies behave as fixed collision surfaces during the preview; simulating interacting piles is deliberately outside this tool's contract.
• A placement session cannot cross the Edit/Play boundary and is cancelled on mode exit.
• Future editor physics previews should reuse this clock ownership and transactional-session model instead of introducing independent ad hoc simulation loops.