Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.0

3D Object Placement

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

Status
Current
Version
v6.0
Source updated
Active v6.0 guide line from Grid Placement repo
Generated on
2026-09-01

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

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

3D terrain editing/painting is not part of the 6.0 contract.

Choose the placement mode first

Use GRID when cells and mount keys are part of the gameplay rule: floors, walls, fences, windows, modular structures, or any object that must line up predictably.

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/mount.
  3. Show the preview and validation feedback.
  4. Rotate yaw when the entry allows it.
  5. Confirm placement.
  6. Record occupancy, mount evidence, transform, and stable placement identity.
  7. Later move/remove/save/restore through the same placement world state.

Preview and commit must use the same placement decision. If the world changes between preview and confirm, final validation wins.

CELL, EDGE, and FACE

PlacementSnapProfile3D.SnapMode controls where a GRID entry attaches.

Mode Meaning Typical use
CELL Occupies a GridMap cell/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

EDGE/FACE occupancy is canonical from either neighboring cell, so the same physical edge cannot be double-booked by addressing it from the other side.

FACE providers

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

Use the 3D shipped demo as the reference for a floor → EDGE wall → FACE-mounted piece sequence.

Snap families

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

Field Purpose
family Category published by the placed object.
snaps_with Provider families this entry may attach to.
require_adjacent_snap Require at least one compatible adjacent provider.

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

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/foundations.

Ground, slope, and partial support

GRID placement can validate the support below the footprint. The 6.0 support model is configurable so different placeables can use different rules.

Typical policy controls include:

  • maximum allowed ground slope;
  • support/height/planarity tolerance;
  • minimum support coverage;
  • optional center/edge support requirements;
  • stricter physics-required support when a project chooses it.

This means a small prop can allow some overhang while a building foundation can require stronger coverage. The rule belongs to the entry/policy rather than being hard-coded globally.

See 3D Surface & Slope Support.

Fences and modular structures

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

A representative supported structure can combine:

  • CELL floor/foundation pieces;
  • EDGE walls/fences/door pieces;
  • a 90-degree EDGE corner;
  • FACE-mounted pieces such as windows/shutters;
  • removal and re-placement;
  • save → clear → restore → continue.

The 6.0 GRID contract does not include a generic roof/top structural mount. Do not treat an arbitrary snap-family name as a new mount type.

SMOOTH world-space sockets

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

Common socket roles include ends, perimeter points, faces, and upward points. A consumer still uses family/snaps_with to decide which providers it accepts.

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

GRID and SMOOTH socket occupancy are different contracts:

  • GRID mounts use canonical cell/edge/face keys.
  • SMOOTH sockets use provider identity + world-space socket identity.

See Smooth Placement.

Validation failures

A 3D placement can reject for reasons such as:

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

Prefer the report-producing placement APIs when your UI/game needs typed failure information. Do not map surface/support failures to generic occupancy errors.

Persistence

Supported 3D placements keep stable placement identity plus enough transform/occupancy/mount evidence to restore the same world state. GRID, SMOOTH, CELL/EDGE/FACE mounts, and shared occupancy are restored as one coordinated placement world rather than independent competing registries.

See Save and Load.

Supported boundaries

  • 3D object placement: supported.
  • GRID + SMOOTH: supported.
  • CELL / EDGE / FACE/socket structure workflows: supported.
  • Configurable slope/support validation: supported after the final 6.0 slope implementation is certified.
  • Structural GRID pitch/roll following terrain: not the default/supported structural contract.
  • 3D terrain editing/painting: not supported.
  • Generic GRID roof/top mount: not supported.