Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.1.0

Manipulation: Service vs Parent

Move, rotate, flip, and demolish architecture for placed objects.

Status
Current
Version
v6.1.0
Source updated
2026-09-24
Generated on
2026-09-23

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 sweeps a screen-space marquee and deletes every demolishable object inside at once on release. Every victim glows demolish-red while the marquee covers it, so the release never surprises. A press+release without a drag is a plain click and deletes exactly the clicked object. Pressing the cancel command (off_mode, Escape by default) while a drag is in progress aborts the whole deletion and stays in demolish mode; with no drag active it exits the mode as before.

Each boxed object goes through the same single-confirm demolish gate (enable flag, pre_demolish vetoes, socket dependents, refunds), so the box can never remove what a click could not. Non-demolishable objects inside the marquee are skipped silently.

Set ManipulationSettings.demolish_drag_box_enabled = false to restore immediate delete-on-press 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.