Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.0

3D Object Placement

Click-to-place on a GridMap, snap families, CELL/EDGE/FACE/CORNER mounts, and ground snapping.

Status
Current
Version
v6.0
Source updated
2026-09-04
Generated on
2026-09-06

Grid Placement 6.0 supports 3D object placement on GridMap in two coordinate modes:

  • GRID — cell- and mount-aligned placement for structures and other grid-aligned objects.
  • SMOOTH — free world-space placement with optional world-space sockets.

3D terrain editing/painting is not supported in 6.0.

Choose the placement mode first

Use GRID for floors, walls, fences, windows, modular structures, or anything else that must align to cells or structural mounts.

Use SMOOTH for clutter, organic props, furniture, or object-to-object joins that should not be tied to GridMap cells.

See Grid vs Smooth Placement for the detailed tradeoff.

GRID placement lifecycle

A normal GRID placement follows this path:

  1. Select a ScenePlacementEntry.
  2. Target a GridMap cell or mount.
  3. Show the placement preview and validation feedback.
  4. Rotate yaw when the entry allows it.
  5. Confirm placement.
  6. Record occupancy, mount data, transform, and stable placement identity.
  7. Move, remove, save, or restore the object through the same placement world.

Preview and commit use the same placement result. If the world changes before confirmation, the final validation result decides whether placement succeeds.

CELL, EDGE, FACE, and CORNER

PlacementSnapProfile3D.SnapMode controls where a GRID entry attaches.

Mode Meaning Typical use
CELL Occupies a GridMap cell or footprint floor, foundation, crate
EDGE Occupies a canonical edge between neighboring cells wall, fence panel, door frame
FACE Mounts to a supported provider face window, shutter, wall decoration
CORNER Occupies a canonical XZ grid intersection structural corner post

EDGE and FACE mounts use canonical keys, so the same physical mount cannot be reserved twice by targeting it from opposite neighboring cells.

CORNER uses the shared grid intersection. A CORNER entry needs two perpendicular hosts at that intersection. Their saved yaw directions must differ by an odd number of quarter turns, so one host runs along X and the other along Z. One host or two parallel hosts is invalid.

FACE providers

A provider must explicitly expose mountable faces. The consumer's snap profile must accept the provider family. FACE save data preserves the provider, mount identity, and orientation so restore can rebuild the same relationship.

Preview object vs mount indicator

The placement preview (sometimes called the ghost) shows where the object will be placed.

The indicator shows what is being validated:

  • CELL — the evaluated cell or footprint support;
  • EDGE — the claimed edge at its structural height;
  • FACE — the provider face;
  • CORNER — the claimed grid intersection.

Both come from the same placement result. An elevated mount should therefore be highlighted at its actual height instead of pointing at unrelated ground below it.

Use the shipped 3D demo as the reference for floor → CELL wall → FACE-mounted piece placement and for House Corner placement at wall intersections.

Snap families

PlacementSnapProfile3D lets entries describe what they provide and what they can attach to.

Field Purpose
family Category published by the placed object.
snaps_with Provider families this entry may attach to.
attachment_requirement INHERIT (default, uses the settings default), OPTIONAL (free placement), or REQUIRED (must satisfy the mount's normal compatible-attachment rule).
corner_host_topology CORNER-only: INHERIT (default), ANY_ONE (one compatible host), or TWO_ORTHOGONAL (strict two-host contract).

The consumer decides what it accepts. You can keep names broad (wall, floor) or use project-specific families without changing plugin code.

Attachment strictness is one shared policy across CELL/EDGE/FACE/CORNER and SMOOTH socket consumption: mount identity (where the piece sits) never changes with the policy — only whether a compatible provider must be present. The legacy require_adjacent_snap boolean is deprecated but still resolves identically (false → OPTIONAL, true → REQUIRED); set attachment_requirement explicitly on new profiles.

Setting up a placeable 3D object

A basic GRID placeable needs three pieces of setup:

  1. Packed scene — the object scene used when placement commits. Use the shipped demos/3d/objects/ scenes as component-layout references.
  2. ScenePlacementEntry — points to the packed scene and defines its placement data.
  3. Catalog registration — add the entry to the PlacementCatalog used by the session so it can be selected.

For the ScenePlacementEntry, configure the fields that apply to the object:

  • footprint_3d — occupied cells for each yaw step;
  • snap_profile_3d — family, snaps_with, attachment_requirement, and snap_mode;
  • seam_bounds_3d — only when the snap profile enables seam_close_to_partner and the asset needs mesh-aware seam closure.

Choose the mount mode from the object's actual placement behavior: CELL for cell/footprint pieces, EDGE for edge panels, FACE for provider-mounted pieces, and CORNER for intersection posts.

The shipped demo provides copyable references in demos/3d/placement/placeables/*.tres, demos/3d/config/3d_catalog.tres, and demos/3d/demo_3d.tscn. When adapting one, replace the scene and update its footprint, snap profile, and seam bounds for your own asset instead of only swapping the mesh.

In the demo, selecting an entry shows the preview and mount-aware indicator. You can then rotate, place, move, demolish, save, and restore the committed object through the normal placement workflow.

Footprints and rotation

ScenePlacementEntry.footprint_3d defines the GRID footprint. Occupancy and support validation apply to the complete rotated footprint, not only the targeted cell.

GRID structures use discrete yaw rotation. Structural pieces remain world-up by default; terrain slope does not automatically tilt walls or foundations.

Ground, slope, and partial support

GRID placement can validate the support below a footprint. Different placeables can use different support rules.

Typical controls include:

  • maximum allowed ground slope;
  • support, height, and planarity tolerance;
  • minimum support coverage;
  • optional center or edge support requirements;
  • stricter physics-required support when the project needs it.

For example, a small prop can allow some overhang while a building foundation requires stronger coverage. Configure that policy on the relevant entry instead of weakening support rules globally.

See 3D Surface & Slope Support.

Fences and modular structures

GRID CELL/EDGE/FACE/CORNER is the supported path for cell-aligned modular structures.

A structure can combine:

  • CELL floor or foundation pieces;
  • CELL wall, door, or window pieces;
  • EDGE walls, fences, or door pieces;
  • CORNER posts mounted at wall intersections;
  • FACE-mounted pieces such as windows or shutters;
  • removal and re-placement;
  • save → clear → restore → continue.

The shipped 3D demo's modular house kit uses these placement paths for its floor deck, walls, door, shuttered windows, and corner posts.

Roofs and gables

There is no dedicated generic GRID TOP/roof mount in the 6.0 API. Roof or gable entries authored as CELL entries follow CELL occupancy and validation rules; that is not the same as a top-of-wall mount.

The shipped 3D demo's second story uses the CELL-overlay pattern: roof and gable entries set occupy_columns = false so they overlay the built footprint, and every piece still travels the same ghost → preview → click → commit path as ground-story pieces (proven per-beat by the honest-input house film). Overlay is a demo composition choice on top of CELL semantics, not a mount.

Do not use an arbitrary snap-family name to imply a new mount type.

SMOOTH world-space sockets

SMOOTH can optionally publish and consume world-space sockets for joins that should not use GRID CELL/EDGE/FACE/CORNER keys.

Common socket roles include ends, perimeter points, faces, and upward points. A consumer still uses family and snaps_with to choose compatible providers.

The default SMOOTH behavior remains free placement. Socket snapping is opt-in through the entry/profile configuration.

GRID mounts and SMOOTH sockets use different occupancy identities:

  • GRID mounts use canonical cell, edge, face, or corner keys.
  • SMOOTH sockets use provider identity plus world-space socket identity.

See Smooth Placement.

Validation failures

A 3D placement can reject for reasons such as:

  • missing or invalid active entry;
  • occupied footprint or mount;
  • unhosted or occupied corner intersection;
  • incompatible snap family or provider;
  • missing required ground or support;
  • slope/support policy failure;
  • collision or overlap conflict;
  • missing physics evidence when a physics-required policy is selected.

Use the report-producing placement APIs when your UI or game needs typed failure information. Keep surface/support failures distinct from occupancy failures so the player receives the correct feedback.

Persistence

Supported 3D placements keep stable placement identity plus the transform, occupancy, and mount data needed to restore the same world state. GRID, SMOOTH, CELL/EDGE/FACE/CORNER mounts, sockets, and shared occupancy are restored together.

See Save and Load.

Supported boundaries

  • 3D object placement: supported.
  • GRID + SMOOTH: supported.
  • CELL / EDGE / FACE / CORNER structure workflows: supported.
  • Configurable GRID slope/support validation: supported.
  • Automatic structural GRID pitch/roll to follow terrain: not supported by default.
  • 3D terrain editing/painting: not supported.
  • Generic GRID TOP/roof mount: not supported.