Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.0

Manipulation: Service vs Parent

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

Status
Draft
Version
v6.0
Updated
Development docs generated from GDScript source

This is unreleased documentation in active development. APIs, class names, and behavior may change before the final release.

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.

Related guides