Manipulation: Service vs Parent

Manipulation changes objects that are already committed to the placement world.

Supported operations depend on the object's Manipulatable / ManipulatableSettings configuration and can include:

• move;
• rotate;
• flip where the dimensional/object workflow supports it;
• demolish.

Core rule

Do not directly change a committed object's transform from UI/game code when Grid Placement owns its occupancy/mount state.

Use the manipulation path so these remain synchronized:

• transform;
• GRID/SMOOTH occupancy;
• CELL/EDGE/FACE/CORNER/TOP/socket relationships;
• validation;
• stable placement identity;
• persistence;
• optional refund behavior.

What an object needs

For supported manipulation:

1. Add/configure Manipulatable.
2. Configure ManipulatableSettings for allowed operations.
3. Make sure the object can be targeted by the relevant 2D/3D manipulation targeting path.
4. Keep object-side scripts from overwriting the transform after the manipulation result commits.

Move

A move is a new placement decision for an existing object:

select committed object
→ begin temporary manipulation preview
→ target new location/mount
→ validate with source object excluded
→ commit new placement state OR cancel

On cancel/failure, the original committed placement/occupancy stays authoritative.

The source object must not block itself during destination validation.

Rotate

Rotation must update the same footprint/mount/occupancy model used by placement.

• 2D GRID can rotate/flip according to the object's manipulation settings.
• 3D GRID structures use supported yaw/mount orientation rather than arbitrary terrain-follow pitch/roll.
• SMOOTH rotation must update the world-space occupancy bounds used for overlap checks.

Directional 2D sprites

Top-down games often have authored N/E/S/W art that should change frame without visibly spinning the sprite.

ManipulatableSettings.disable_rotation_transform supports that presentation pattern: logical/cardinal rotation can still advance for placement/footprint behavior while the consumer swaps the visible art.

The important rule is that the logical footprint/placement orientation must still change correctly for non-square objects. Per-cell rule indicators stay axis-aligned regardless: they show the claimed cells, while your preview communicates facing. The full authoring pattern and demo-file references now live in 2D Object Scene Setup.

Demolish

Demolition should remove the committed placement and free its occupancy/mount/socket state through the supported manipulation/placement lifecycle.

If your game refunds resources, use the refund integration after/with successful demolition rather than separately freeing the node and then trying to repair placement state.

See Refund on Demolish.

Drag-box multi-demolish and cancel

In object demolish mode, press-drag-release selects objects with a screen-space marquee and removes the selected demolishable objects on release. In 3D, any visible part of an object's projected pick bounds can select it; in 2D, selection uses the object's canvas origin. Selected 3D objects are highlighted while the box covers them; in 2D, the marquee is the visual feedback. A press and release without a drag removes the clicked object. Press off_mode (Escape by default) during a drag to cancel the box; outside a drag, the action works as usual.

Each selected object goes through the same demolish checks as a single click, including the global enable flag, per-object setting, pre_demolish vetoes, socket dependents, and refunds. Roots without a Manipulatable component or whose settings disallow demolition are skipped.

Set ManipulationSettings.demolish_drag_box_enabled = false to remove objects as soon as they are clicked, with no drag gesture.

Temporary manipulation visuals

Manipulation may use temporary preview/parent nodes to show the candidate transform. Treat those as transient presentation, not committed placement objects and not save targets.

Cleanly cancel manipulation when:

• changing modes/scenes;
• removing the source object for another reason;
• unregistering the owning session/controller.

Do not free arbitrary helper children and leave manipulation state active.

Common failures

Symptom	Check
Move/demolish cannot select object	Targeting collision/layers and Manipulatable.
Operation does nothing	Corresponding ManipulatableSettings flag.
Move collides with itself	Source exclusion/stale preview cleanup.
Rotation looks right but occupancy is wrong	Logical footprint/orientation was bypassed by custom transform code.
3D mount reusable after demolish	Mount/socket occupancy was not removed transactionally.
Save contains ghost/manipulation copy	Save layer is capturing transient helpers.
Refund occurs twice	Game handler and refund service both apply it.

Related guides

• Placement Workflow
• 2D Object Scene Setup
• Targeting Flow
• 3D Object Placement
• Refund on Demolish
• Save and Load