TileMap & GridMap

Modify tile-based layouts for 2D and 3D worlds.

TileMap (2D)

TileMap is Godot's 2D tile system. Director can set, get, and fill tiles using tile coordinates (column, row).

tilemap_set_cells

Set one or more specific tiles.

{
  "op": "tilemap_set_cells",
  "project_path": "/home/user/my-game",
  "scene": "scenes/level_01.tscn",
  "node": "World/TileMap",
  "cells": [
    { "position": [0, 0], "source_id": 0, "atlas_coords": [0, 0], "layer": 0 },
    { "position": [1, 0], "source_id": 0, "atlas_coords": [0, 0], "layer": 0 }
  ]
}

Parameter	Type	Required	Description
cells	object[]	required	Cells to set. Each cell specifies coords, source_id, and atlas_coords.
node_path	string	required	Path to the TileMapLayer node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Scene file containing the TileMapLayer (relative to project).

To erase a tile, set atlas_coords to [-1, -1].

Response:

{
  "op": "tilemap_set_cells",
  "cells_set": 4,
  "result": "ok"
}

tilemap_get_cells

Read tile data from a region.

{
  "op": "tilemap_get_cells",
  "project_path": "/home/user/my-game",
  "scene": "scenes/level_01.tscn",
  "node": "World/TileMap",
  "region": { "min": [0, -5], "max": [20, 5] },
  "layer": 0
}

Parameter	Type	Required	Description
node_path	string	required	Path to the TileMapLayer node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
region	any	optional default: null	Optional region to filter cells. Only cells within this rectangle are returned. Omit to get all used cells.
scene_path	string	required	Scene file containing the TileMapLayer (relative to project).
source_id	number	optional default: null	Optional filter: only return cells from this TileSet source.

Response:

{
  "op": "tilemap_get_cells",
  "region": { "min": [0, -5], "max": [20, 5] },
  "cells": [
    { "position": [0, 0], "source_id": 0, "atlas_coords": [0, 0] }
  ]
}

Only non-empty tiles are returned.

tilemap_clear

Remove all tiles from a layer.

{
  "op": "tilemap_clear",
  "project_path": "/home/user/my-game",
  "scene": "scenes/level_01.tscn",
  "node": "World/TileMap",
  "layer": 0
}

Parameter	Type	Required	Description
node_path	string	required	Path to the TileMapLayer node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
region	any	optional default: null	Optional region to clear. Only cells within this rectangle are erased. Omit to clear all cells.
scene_path	string	required	Scene file containing the TileMapLayer (relative to project).

GridMap (3D)

GridMap is Godot's 3D tile system, using a 3D integer grid. Director can set individual cells or regions.

gridmap_set_cells

Set one or more cells in a GridMap.

{
  "op": "gridmap_set_cells",
  "project_path": "/home/user/my-game",
  "scene": "scenes/dungeon.tscn",
  "node": "World/GridMap",
  "cells": [
    { "position": [0, 0, 0], "item": 0, "orientation": 0 },
    { "position": [1, 0, 0], "item": 0, "orientation": 0 }
  ]
}

Parameter	Type	Required	Description
cells	object[]	required	Cells to set. Each cell specifies position and mesh library item index.
node_path	string	required	Path to the GridMap node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Scene file containing the GridMap (relative to project).

Orientation values: Godot's GridMap uses integer orientations 0-23 for each of the 24 possible orthogonal rotations. Common values: 0=default, 10=rotated 90° around Y, 16=rotated 180° around Y, 22=rotated 270° around Y.

Response:

{
  "op": "gridmap_set_cells",
  "cells_set": 5,
  "result": "ok"
}

gridmap_get_cells

Read cells in a region.

{
  "op": "gridmap_get_cells",
  "project_path": "/home/user/my-game",
  "scene": "scenes/dungeon.tscn",
  "node": "World/GridMap",
  "region": { "min": [-5, 0, -5], "max": [5, 2, 5] }
}

Parameter	Type	Required	Description
bounds	any	optional default: null	Optional bounding box to filter cells. Only cells within these bounds are returned. Omit to get all used cells.
item	number	optional default: null	Optional filter: only return cells with this MeshLibrary item.
node_path	string	required	Path to the GridMap node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Scene file containing the GridMap (relative to project).

gridmap_clear

Remove all cells from the GridMap.

{
  "op": "gridmap_clear",
  "project_path": "/home/user/my-game",
  "scene": "scenes/dungeon.tscn",
  "node": "World/GridMap"
}

Parameter	Type	Required	Description
bounds	any	optional default: null	Optional bounding box to clear. Only cells within these bounds are removed. Omit to clear all cells.
node_path	string	required	Path to the GridMap node within the scene tree.
project_path	string	required	Absolute path to the Godot project directory.
scene_path	string	required	Scene file containing the GridMap (relative to project).

Example conversation: Building a platformer level

Build a simple platformer level in the TileMap. A floor at row 0 from columns 0-30, and three floating platforms.

Floor placed (30 tiles). Adding the three platforms.

Done. Floor (columns 0-30, row 0) and three platforms at rows -3, -6, and -9 placed. Total: 38 tiles.

Tips

Know your atlas coordinates first. Open the TileSet resource in the Godot editor to find the source_id and atlas_coords for each tile type before calling Director.

Use tilemap_set_cells with all cells in one call. Batching all tile placements into a single tilemap_set_cells call is one round-trip regardless of how many tiles are set.

Use tilemap_get_cells to audit existing levels. Before modifying a level, read the existing tile layout to understand what is there.

GridMap orientations: When building 3D levels with GridMap, use spatial_snapshot after applying changes to verify that walls and floors are facing the right direction.