Tilemaps

A tilemap is a grid of cells, each painted from a tileset. Tilemaps are how you build large worlds without placing thousands of sprites — paint a hundred grass cells in a few seconds, then drop trees and chests on top.

Configure a tileset

Before painting, the asset has to be a configured tileset.

You can also do this in chat: "Configure water_tiles.png as a 16×16 tileset 4 cols by 1 row."

Create a tilemap entity

In the Scene tab palette (World mode), drag the Tilemap primitive onto the canvas. The Create Tilemap modal asks for:

• Tileset asset — pick the configured tileset.
• Grid dimensions — map cols × rows (cell-units).
• Cell size — usually inherited from the tileset.
• Layer name — defaults to Ground.

Submit. An empty tilemap appears. Select it to open the Tilemap Inspector in the Float Inspector.

The Tilemap Inspector

When a tilemap is selected, the Inspector shows:

• Layers list — current layers with visibility / rename / delete / reorder buttons.
• Active layer indicator and a + button to add new layers (each layer has its own tileset).
• Tile palette — every tile in the active layer's tileset. Click a tile to arm it for painting. Click again to disarm (Figma convention).
• Tools — Brush / Eraser / Rectangle / Bucket fill / Picker.
• Terrain mode (when the tileset has autotile presets) — terrain cards instead of individual tiles; paint a region and the autotile engine picks per-cell variants.
• Resize — handles on the tilemap's bounds + a number input panel for precise resize. The handles are 8-way (corners + edges).

Paint operations

The active tile has a primary-blue outline in the palette. Click it again to disarm; with no active tile, canvas clicks fall through to entity-drag — useful for moving the tilemap without an explicit Move tool.

Multiple layers

You can stack layers (ground, walls, decorations, foreground) — each is its own paintable surface with its own tileset and its own Z order.

• Add a layer: + button in the layers list, pick the tileset.
• Reorder: drag in the layers list.
• Per-layer visibility: the eye icon.
• Rename: double-click the layer name.
• Delete: trash icon.

The map's collision is computed per-layer, so you can keep visual decoration on a layer with solid: false tiles and gameplay collision on a separate layer.

Tile metadata + auto-collision

Right-click any tile in the palette (or use the Inspector) to open the Tile Metadata Editor. Per-tile fields:

Save the modal → metadata stamps onto the tile's properties → the collision wiring rebuilds in the running iframe (no scene reload needed).

Multi-rect sub-tile collision

For tiles that are visually half-wall + half-floor (a corner piece, a column, an L-shape), use the Collision shape sub-panel inside the Tile Metadata Editor.

• Drag on the zoomed tile preview to define a sub-rect.
• Drag corners to resize, drag the body to move.
• Multiple rects per tile are supported (L / U / frame shapes).
• Click "Clear all" to revert to default cell-rect collision.

Each rect becomes an invisible static Arcade body at runtime.

Autotile (paint terrain, not tiles)

For tilesets with autotile presets (Sprout Lands, Kenney's standard 47- blob, many itch.io packs), the Tilemap Inspector adds a Terrain mode toggle.

In Terrain mode:

• The palette shows terrain cards (Grass, Soil, Stone, Water, Sand) instead of individual tiles.
• You paint with a terrain, and the autotile engine picks the right variant per cell based on neighbors — corners stay corner-tiles, edges stay edge-tiles, isolated cells stay isolated-tiles.

Configure autotile via the asset's Tileset & autotile editor → 📦 Preset ▾ → pick a built-in preset (STANDARD_47_BLOB_11x7 covers most itch.io packs). Or paint the 3×3 bitmask grid manually for non- standard layouts.

Wiring player collision

Per-tile solid: true automatically registers a Phaser collider. If the agent wrote your player using the standard pattern, this Just Works. If not, ask the agent:

Wire collision between the player and the Walls tilemap layer.

The SDK exports addTilemapCollider(scene, entityId, target) which wires both the cell-rect colliders and the sub-rect static groups in one call. The agent uses this for you.

Animated tiles

Tilesets can declare animations — painted cells with tile.index === rootTileIndex cycle through frames at runtime. See Animated tiles for the full walkthrough.

Common workflows

"Make a small grass field with a few trees"

1. Library → Sprout Lands pack → Add all.
2. Drag the Tilemap palette item → pick the grass tileset → 20×15 grid.
3. Terrain mode → paint Grass over the whole map.
4. Switch layers / add a decoration layer → paint tree tiles where you want them.

"I want this tile to deal damage"

1. Right-click the tile in the palette → Tile Metadata Editor.
2. Set damage: 1 (or whatever).
3. Save. Tell the agent: "Use the damage metadata on tilemap cells to damage the player on contact." The agent reads getTilemapAt and wires it.

Next steps