Skip to content
YouTubeBrowse pluginsPlugins
Menu

Grid Placement v6.2.2

Hex 2D Placement

Adapt the Getting Started setup to hex-grid 2D levels: hexagon TileSet cells, the shared template bundle, and hex cell-snap behavior.

Status
Current
Version
v6.2.2
Source updated
2026-10-22
Generated on
2026-10-22

This tutorial adapts the Getting Started setup to a hex-grid 2D game. If you have not completed Getting Started yet, do that first — this guide only covers what changes for hex cells.

What changes for hex

Only cell geometry. The plugin snaps to whatever cells your TileMapLayer defines, so hex support is a TileSet configuration question, not a wiring question:

  1. The TileSet uses hexagon cells. Shape, layout, offset axis, and cell size define the hex lattice.
  2. Everything else reuses the shared setup. There is no hex-specific bundle in the template set — targeting, session, host, and level wiring are the same as Getting Started, using the top-down bundle.

1. Configure the TileSet

On your level's TileSet resource:

Property Value
tile_shape Hexagon (in the Inspector: Square / Isometric / Half-Offset Square / Hexagon)
tile_layout Pick the orientation your art uses (Stacked, Stairs, Diamond variants)
tile_offset_axis Horizontal Offset or Vertical Offset, matching the art
tile_size Your hex art's cell size, e.g. Vector2i(64, 64)

Set these in the Inspector rather than hand-editing raw integers in the .tres text — the tile_shape enum's numeric values changed between Godot releases, and the Inspector always shows the right label for your editor version.

Layout and offset axis describe flat-top versus pointy-top lattices; match them to your hex art or the snap pattern will not line up with the painted cells.

2. Use the shared template bundle

Hex changes cell geometry, not input behavior, so the top-down bundle fits:

  • Bundle: res://templates/grid_placement_templates/resources/top_down/td_placement_bundle.tres

Assign the bundle to PlacementSession.grid_placement_bundle and to GridPlacementHost.grid_placement_bundle, exactly as Getting Started step 4 describes. The validation rules the bundle carries (collision check, tilemap bounds check) apply per cell regardless of cell shape.

Terrain is optional for this tutorial. Leave the bundle's terrain_palette empty unless you use terrain painting.

3. Wire the scene

Use the scene tree from Getting Started section 3 unchanged:

  • Instance the positioner stack from res://templates/grid_placement_templates/grid_positioner/grid_positioner_stack.tscn.
  • PlacementLevelContext.target_map → your hex TileMapLayer.
  • PlacementLevelContext.objects_parent → a dedicated Node2D for placed objects, never the map itself.
  • Keep a current Camera2D — the 2D commit path resolves through the camera projection and fails closed without one.

4. Place your first hex object

Create a placeable exactly as Getting Started step 5 describes (packed_scene, display_name, and a profiles entry so the selection UI shows it). Hex-specific authoring notes:

  • Anchor the scene root to the cell center so objects sit inside their hex; diamond-oriented art reads as offset when anchored to a corner.
  • The top-down template bundle includes collision checks, so give the object collision shapes or its placement is rejected.
  • Multi-cell hex structures follow the same footprint rules as any 2D object; see 2D Object Scene Setup.

Learn from the hex demo

The repository ships a complete hex reference demo at res://demos/hex/ — a hex tileset (res://demos/hex/art/hex_tileset.tres), map-bounds and collision rules, and a working catalog. The demos live only in a repository checkout. A consumer project receives only res://addons/grid_placement/ and res://templates/grid_placement_templates/, so treat the demo as read-only reference material to compare against, not something your project imports from.

The portable equivalent of everything the demo wires up is the shared bundle from step 2 plus your own hex art. Game-specific hex rules in the demo (map bounds, per-terrain checks) are written as placement rules — see Custom Placement Rules when you need your own.

Troubleshooting this genre

  • Snaps do not line up with painted hexes — tile_layout / tile_offset_axis do not match the art's flat-top or pointy-top orientation.
  • Cells are half-scale or double-scale — tile_size disagrees with the hex art dimensions.
  • Nothing places at all — check for the missing Camera2D and re-run the diagnostic in Validation.
  • Placement works in the demo but not in your project — the demo lives in a repository checkout; port the wiring from steps 2–3 rather than copying demo resources, which are absent from consumer projects.