# Physics Placement

The Physics Placement tool releases selected authored props into the same Avian collision world
used by Play mode. It is intended for arranging loose objects on floors, terrain, brushes, and
other hydrated colliders without hand-tuning every final transform.

## Workflow

1. Select one or more mutable level objects. Each object needs an enabled **Rigid Body** and an
   enabled, non-trigger **Collider** component.
2. Press the hand/down-arrow button in the existing horizontal Scene viewport toolbar.
3. The selected props become dynamic and fall under gravity. The viewport HUD reports simulation
   time and whether the group is still moving, settled, or stopped at the preview limit.
4. Press the check button to commit the current transforms, or **Escape** / the X button to cancel.
   **Enter** commits after the group has settled.

Commit creates one `Move Selection` undo entry for the whole group. Cancel restores the exact
pre-placement local transforms and runtime motion components and creates no history entry.

## Isolation And Diagnostics

Normal Edit mode keeps Avian physics paused, so authored dynamic bodies cannot drift outside
history. During placement, every non-selected dynamic or kinematic body is temporarily treated as
a static collision surface. The tool restores those bodies exactly when the preview ends. Entering
Play mode cancels an active placement preview.

The start action is non-destructive when prerequisites are missing. It consumes the shared
[collider health service](collider-authoring.md), so the viewport, inspector, Diagnostics panel,
and placement status agree about missing, invalid, stale, disabled, or trigger collision. A
ten-second simulated-time limit stops unstable previews while
leaving explicit commit and cancel available.

`assets/levels/physics_placement_showcase.scn.ron` is the Physics Placement entry in the committed
[sample regression pack](sample-regression-pack.md). Select **Placement Cuboid**, **Placement
Sphere**, and **Placement Capsule** together, start physics placement, and verify that the three
distinct collider cases settle on **Placement Floor** as one commit/cancel transaction.

The clock and transaction boundary are specified by
[ADR 0041](../adr/0041-transactional-editor-physics-placement.md).
