2D Object Scene Setup

This is the source of truth for authoring a 2D ScenePlacementEntry's packed scene. Use Getting Started for runtime wiring and Troubleshooting for symptom-driven diagnosis.

Scene root is the placement origin

Grid Placement seats the packed scene's root on the targeted cell. Placement replaces the root's saved position, so moving the root in the .tscn is not a reliable placement offset.

Author deliberate visual or collision offsets on child nodes instead:

keep the root at the scene origin;
position/offset Sprite2D children around the intended placement origin;
position collision children to match the gameplay footprint;
keep sprite and collision transforms consistent unless the mismatch is intentional.

Child transforms are preserved through preview and commit.

Cell anchor modes

ScenePlacementEntry.cell_anchor_mode controls where the root sits inside the targeted 2D cell. Entries default to INHERIT, which follows PlacementSettings.default_cell_anchor_mode (historically CELL_CENTER). An explicit entry mode overrides that setting.

For centered, unscaled artwork whose dimensions are whole grid cells, choose the seat independently on each axis:

odd number of cells on an axis → seat that axis at the cell center;
even number of cells on an axis → seat that axis at the minimum cell edge.

On a 32×32 grid:

Artwork size	Cell span	`cell_anchor_mode`
32×32	1×1	`CELL_CENTER`
96×96	3×3	`CELL_CENTER`
96×32	3×1	`CELL_CENTER`
64×64	2×2	`CELL_TOP_LEFT`
256×96	8×3	`CELL_CENTER_LEFT`
96×256	3×8	`CELL_TOP_CENTER`

CELL_CENTER_LEFT shifts only X by half a cell. CELL_TOP_CENTER shifts only Y. CELL_TOP_LEFT shifts both axes.

That is why a centered 256×96 sprite on a 32px grid cannot be fixed by CELL_TOP_LEFT: it corrects the even X span but introduces a half-cell error on the odd Y span. This is an even/odd-per-axis rule, not a square-versus-rectangle rule.

After changing cell_anchor_mode, re-select the entry so the preview is rebuilt.

What anchor modes do not infer

Anchor modes do not inspect a texture and do not guess a collision footprint. The table above applies when the visible bounds are centered, unscaled, and span exact whole cells.

For transparent padding, asymmetric art, overhangs, non-centered sprites, scaling, or a gameplay footprint that differs from the texture bounds, author the child transforms around the intended placement origin instead of trying to encode the difference in the root position.

Collision and visual alignment

Treat visual bounds and collision bounds as separate inputs that should normally describe the same placement footprint.

A sprite can overhang its gameplay footprint; keep the collision shape on the cells that should actually block placement.
Collision layers/masks determine targeting and validation, not the anchor mode.
If the indicator is grid-aligned but only the object art is offset, inspect scene authoring and cell_anchor_mode before changing grid coordinates.

Directional N/E/S/W artwork

For authored cardinal sprites, logical placement rotation can change while the bitmap stays visually upright and swaps frames.

ManipulatableSettings.disable_rotation_transform supports this presentation pattern. It suppresses the normal visual rotation transform; it does not disable logical/cardinal rotation. The footprint and placement orientation must still rotate correctly, especially for non-square objects.

Per-cell rule indicators are footprint markers, not transformed art: they mark which cells the object claims and stay axis-aligned (no rotation, mirror, or skew inherited from the preview). With transform rotation suppressed, the plugin derives the claimed cells from the logical rotation, so a non-square footprint still turns while the markers stay upright. Your game draws the facing — either with a rotated node or by swapping authored frames.

The top-down demo's Directional Wizard is the reference pattern:

demos/top_down/objects/directional_sprite_rotation_demo.gd
demos/top_down/objects/directional_wizard.tscn
demos/top_down/placement/placeables/placeable_directional_wizard.tres

Use the supported rotation/cardinal callback to swap presentation frames. Do not manually rewrite placement occupancy or footprint state from the art callback.

Quick diagnosis

Symptom	First check
Preview is half a cell off while indicator is correct	`cell_anchor_mode` versus odd/even cell span.
Moving the scene root changes editor layout but runtime still snaps wrong	Root position is replaced by placement; move/offset children instead.
Sprite aligns but collision blocks neighboring cells	Collision child transform/shape does not match the intended footprint.
Directional art looks right but occupancy is wrong after rotate	Presentation changed without preserving logical footprint/orientation.
Indicator tiles skew, rotate, or mirror with the object	Overlay art must stay axis-aligned; keep the per-cell marker art on the indicator's child nodes.