Skip to content
ctChrisTutorials
Plugins
Menu

Grid Placement v6.0

Getting Started

Install Grid Placement 6.0 and place the first object in a Godot project.

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

This is the shortest supported path from a fresh install to one successful placement.

Requirements: Grid Placement 6.0, Godot 4.5.x minimum, GDScript.

The beginner path uses 2D TileMapLayer object placement because it has the fewest moving parts. 3D GridMap GRID/SMOOTH placement is also supported; once the runtime model makes sense, use 3D Object Placement.

1. Install

  1. Copy addons/grid_placement into your project.
  2. Copy templates/grid_placement_templates if you want the starter scenes/UI.
  3. Enable Grid Placement in Project Settings → Plugins.
  4. Run Project → Tools → Grid Placement / Setup Default Input Actions.
  5. Restart the editor.

Confirm the placement actions appear in Project Settings → Input Map.

2. Understand the minimum runtime

GridPlacementHost
  └─ PlacementSession

Level
  └─ PlacementLevelContext

Player/controller
  └─ PlacementOwner
Piece Purpose
GridPlacementHost Runtime coordinator and session registry.
PlacementSession Per-player/per-controller selection, targeting, settings, and interaction state.
PlacementLevelContext Connects the active level surface and placed-object parent.
PlacementOwner Identifies who owns the placement interaction.
GridPositioner2D Tracks the current 2D grid target for human input.

The shipped starter systems scene already wires most of this. Use it for the first pass unless you specifically need manual composition.

3. Connect the 2D level

Add/configure PlacementLevelContext in the level:

Field Assign
target_map The TileMapLayer used for grid targeting.
objects_parent The Node2D that receives committed scene objects.

These are different responsibilities: the map defines the grid surface; the object parent owns placed scene instances.

4. Connect the player/controller

Add PlacementOwner and assign owner_root to the player/controller root.

Use GridPositioner2D for mouse/controller grid targeting. If the starter indicator does not visually match your tile size, adjust its presentation; do not change placement coordinates just to make a cursor graphic line up.

5. Create one placeable

Create a simple object scene, then a ScenePlacementEntry resource that points at it.

For the first object:

  1. Assign packed_scene.
  2. Add display metadata only if your selection UI needs it.
  3. Assign a PlacementProfile if the object needs category/tool/rule behavior.
  4. Keep custom rules minimal until basic placement works.

If you use collision-based validation/manipulation, configure collision layers/masks deliberately.

6. Select and place it

Use the shipped selection UI or your own consumer to select the entry.

A healthy first placement looks like this:

  1. Entry becomes active.
  2. Preview follows the target cell.
  3. Preview reports valid/blocked state.
  4. Confirm commits one object under objects_parent.
  5. No missing-context/configuration errors appear in Output.

If the preview works but commit fails, read the placement failure/report before changing code. Common causes are missing context, occupancy, rules, or collision masks.

7. Add features one at a time

After one object works, add only the feature you need next:

  • 2D terrain painting: SINGLE, then LINE/rectangle/flood brushes.
  • Object LINE placement: enable it through the entry/profile that should support it.
  • Manipulation: move/rotate/flip/demolish supported objects.
  • Persistence: save → restore → continue.
  • Custom rules/world facts: connect game-owned restrictions.
  • Multiple sessions: split-screen/multiplayer/controller-specific state.
  • 3D GRID: cell-aligned structures and CELL/EDGE/FACE mounts.
  • 3D SMOOTH: free world-space placement and optional sockets.
  • 3D slope/support: configure support tolerance for GRID structures.

Do not add all of these just because they exist.

2D terrain vs 3D terrain

Terrain painting in 6.0 means 2D TileMapLayer terrain painting.

3D GridMap terrain editing/painting is not a supported 6.0 feature. 3D slope/support settings validate where objects may sit; they do not modify terrain.

Common first-run failures

  • Plugin not enabled.
  • Default input actions not installed.
  • Session not registered/configured.
  • PlacementLevelContext.target_map or objects_parent missing.
  • PlacementOwner.owner_root missing.
  • Positioner not connected to the active interaction.
  • UI Control consuming clicks intended for placement.
  • Collision layers/masks inconsistent with targeting or validation.

See Troubleshooting before building a workaround.

Next guides