Blacksite/.cursor/plans/physics_placement_2026-07-12.plan.md

Physics Placement Tool - 2026-07-12

Historical plan — not current implementation guidance. Use the documentation index for current behavior and architecture.

Issue: Gitea #25 (BS-JD-304)

Outcome

Selected authored props can be released into deterministic Avian gravity, preview their settled transforms in the Scene viewport, and either commit the result as one undoable transform operation or cancel back to the exact pre-placement state.

Contract

• Physics is paused during normal Edit mode and while Play mode is paused.
• Placement runs only in Edit mode and owns a transactional physics session.
• Selected mutable level objects must have active rigid-body and non-trigger collider authoring. Invalid selections produce a precise, non-destructive diagnostic.
• Selected bodies are temporarily dynamic with clean motion state.
• Other movable bodies are temporarily static so they remain collision surfaces without advancing unrelated authored state.
• Commit restores all temporary runtime overrides and records only changed local transforms as one grouped history command.
• Cancel restores transforms and runtime physics state exactly and creates no history entry.
• Escape cancels. Enter commits once the session has reached rest. A bounded timeout keeps unstable scenes controllable.

Work

• Establish Edit/Play ownership of Time<Physics> and preserve paused single-step PIE.
• Implement placement validation, runtime snapshots, deterministic stepping, settling, timeout, commit, and cancel.
• Add the placement action and session controls to the existing horizontal viewport toolbar plus a compact status HUD.
• Add unit/integration coverage for prerequisites, settling, cancel, commit, and history.
• Update editor workflow documentation and implementation checklist.
• Run source gates and live Wayland acceptance; packaged tests remain skipped by request.
• Commit, push, attach native Gitea evidence, and close #25.