How to snap objects to a 3D grid in Godot

This recipe snaps 3D objects to a grid the way building bricks snap together: pick a piece, hover the grid, watch a live preview lock to cells and faces, rotate it into place, and confirm. Grid Placement 6.2 owns the whole loop (targeting, preview, validation, commit, save) so your game only supplies the placeable pieces and any house rules on top.

1. Pick GRID, not SMOOTH

Grid Placement 6.2 places 3D objects in two coordinate modes. GRID aligns to cells and structural mounts: floors, walls, fences, crates, and anything that must sit on the lattice. SMOOTH places at free world-space positions for clutter, rocks, and organic props where the grid should not decide.

Snapping to a 3D grid is GRID mode by definition. If your objects need brick alignment, do not start in SMOOTH and round positions by hand: you would rebuild occupancy, mount validity, and save identity that GRID already provides. The detailed tradeoff lives in Grid vs Smooth Placement.

2. Choose the mount for each piece

PlacementSnapProfile3D.SnapMode controls where a GRID entry attaches. Match each placeable to the mount that fits its shape:

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
TOP	Occupies the top of a host EDGE, or the cell-centered ridge	roof plane, gable, ridge cap

EDGE and FACE occupancy is canonical from either neighboring cell, so the same physical edge cannot be double-booked from the other side. A FACE provider must explicitly expose mountable faces, and the consumer profile must accept that provider family. Author these relationships in the ScenePlacementEntry and its snap profile up front; placement then enforces them every time.

3. Run the placement loop

A normal GRID placement follows one path:

1. Select a ScenePlacementEntry.
2. Target a GridMap cell or mount (surface scanning resolves the hovered surface into a placement position; see 3D Surface Scanning).
3. Show the placement preview with validation feedback.
4. Rotate yaw when the entry allows it.
5. Confirm placement.
6. Record occupancy, mount data, transform, and stable placement identity.

Preview and commit use the same placement result. If the world changes before confirmation, the final validation result decides. Core validation (footprint occupancy, mount validity, snap and provider rules, ground, support, and slope policy) runs inside the plugin; the UI consumes the current placement result instead of duplicating any check. Game-side policy such as costs, unlocks, or protected zones layers on top through game-authored rules, as Placement Rules describes.

4. Save placements, not previews

Committed objects use PlaceableInstance for stable placement identity and base serialization data: node name, transform, originating entry, and placement id. Occupancy and mount data are not on that component — they are projections of the committed placement world, kept in the world save record and rebuilt through the restore coordinator. Preserve the world record too, or the same object comes back visually correct with an empty lattice behind it.

The reliable order is: clear the committed placement world, load the saved records, restore the scenes and stable ids, then rebuild GRID, SMOOTH, mount, and socket occupancy together with PlacementWorldRestoreCoordinator3D before validating. Keep game-owned data alongside in your own save wrapper. Never save placement previews or temporary manipulation copies as committed objects. The full contract is in Save and Load.

Upgrading from 6.1

6.2 keeps scenes and resources loading, but code that calls changed API fails at runtime. Work through 6.1 to 6.2 Migration Guide before touching a 6.1 project — it lists every removed and renamed symbol with its replacement.

Common mistakes

• Rounding SMOOTH positions to fake snapping. Use GRID and get occupancy, mounts, and stable ids with it.
• Rebuilding occupancy or slope checks in UI code. Read the placement result; the plugin already validated.
• Saving preview nodes. Only committed PlaceableInstance records restore.
• Skipping the snap profile and validating mounts by hand. Author the profile; placement enforces it.
• Treating terrain painting as object placement. Terrain cells paint by catalog name (see 3D Terrain Painting); objects place by entry.

Try the demo

The Grid Placement demo runs this loop live: entry selection, surface targeting, ghost preview with validation feedback, rotation, commit, and save-safe restore. Try it in your browser on the Grid Placement itch.io page before wiring your own pieces.