Unity 2D Tilemap
Author and script tile-based 2D levels in Unity 6.3 LTS with the Grid/Tilemap system, the Tile
Palette, colliders, and runtime painting. Targets Unity 6.3 LTS (6000.3).
Package note: the core Tilemap (Grid, Tilemap, Tile, TilemapCollider2D) is
built in, and so is the Tile Palette with its default brush. Rule Tiles, Animated Tiles,
and the extra brushes (Random, Line, GameObject, Group) live in the separate "2D Tilemap
Extras" package (com.unity.2d.tilemap.extras, 6.0.x for Unity 6.3) — install it via
Package Manager before using RuleTile.
When to use
- Use when laying out a 2D level by painting tiles, setting up a
Grid + Tilemap, adding
collision to the map, using auto-tiling Rule Tiles, or generating/editing tiles from script.
- Use when scenes contain a
Grid with Tilemap children, or *.asset tile/palette files.
When not to use: level design practice (pacing, blockout, layout principles) →
level-design. 3D tile/grid placement → Unity's own 3D tooling (ProBuilder / grid brushes; no dedicated skill here). The platformer character that
moves over the tiles → platformer / unity-physics.
Core workflow
- Create the grid: GameObject → 2D Object → Tilemap → Rectangular (the
Grid's Cell
Layout also offers Hexagonal and Isometric for hex/iso levels). This makes a Grid
with a child Tilemap (+ TilemapRenderer). Use one Tilemap per layer (background,
ground, foreground) and set each renderer's sorting.
- Open the Tile Palette (Window → 2D → Tile Palette), drag in a sliced sprite sheet to
create
Tile assets, then paint with the brush tools.
- Add collision to the solid layer:
TilemapCollider2D. For one merged collider (far
cheaper and gap-free), also add CompositeCollider2D (+ a Rigidbody2D set to Static)
and set the tilemap collider's Composite Operation to Merge.
- Auto-tile with Rule Tiles (2D Tilemap Extras) so edges/corners pick the right sprite
automatically instead of hand-placing every variant.
- Edit at runtime via script with cell coordinates (
Vector3Int): SetTile, GetTile,
SetTilesBlock, converting world↔cell with the Grid/Tilemap.
- Verify in Play mode: confirm collisions (Physics Debugger), sorting order, and that
RefreshAllTiles ran after bulk edits.
Patterns
1. Painting tiles at runtime (cell coordinates)
using UnityEngine;
using UnityEngine.Tilemaps;
public class TilePainter : MonoBehaviour
{
[SerializeField] private Tilemap tilemap; // assign the target Tilemap
[SerializeField] private TileBase groundTile;
// World position -> cell, then place a tile.
public void PaintAt(Vector3 worldPos)
{
Vector3Int cell = tilemap.WorldToCell(worldPos);
tilemap.SetTile(cell, groundTile);
}
public bool IsSolid(Vector3 worldPos)
=> tilemap.GetTile(tilemap.WorldToCell(worldPos)) != null;
}
2. Bulk fill a region (faster than per-cell SetTile)
// SetTilesBlock writes a whole BoundsInt in one call — use it for procedural rooms/floors.
public void FillFloor(Tilemap map, TileBase tile, int width, int height)
{
var bounds = new BoundsInt(0, 0, 0, width, height, 1);
var tiles = new TileBase[width * height];
for (int i = 0; i < tiles.Length; i++) tiles[i] = tile;
map.SetTilesBlock(bounds, tiles);
}
3. Clearing and refreshing
tilemap.SetTile(cell, null); // null erases the tile at that cell
tilemap.RefreshTile(cell); // re-evaluate just this cell's rule/animated neighbors (cheap)
// RefreshAllTiles() re-evaluates the ENTIRE map — reserve it for full regenerations, not per-edit.
Pitfalls
RuleTile type not found — it's not built in. Install the 2D Tilemap Extras package
(com.unity.2d.tilemap.extras) via Package Manager.
- A collider per tile tanks performance / leaves seams — add a
CompositeCollider2D with a
static Rigidbody2D and set Composite Operation to Merge to merge the whole layer into
one smooth shape.
- No "Used By Composite" checkbox, or an obsolete warning on
usedByComposite — Unity 6
replaced it with Composite Operation (Collider2D.compositeOperation). Old
usedByComposite = true maps to CompositeOperation.Merge; write that instead.
- Small gaps remain between merged tiles — raise the Tilemap Collider 2D's Extrusion
Factor so neighbouring tile shapes fall within the Composite Collider 2D's Vertex Distance.
- Confusing world and cell coordinates —
SetTile/GetTile take a Vector3Int cell,
not a world position. Always convert with WorldToCell / CellToWorld.
- Tiles render behind/in front of sprites unexpectedly — set each
TilemapRenderer's
Sorting Layer and Order in Layer; multiple tilemaps need explicit ordering.
- Rule/animated tiles don't update after script edits — refresh after writes, but prefer
the targeted
RefreshTile(cell) for a few edits; RefreshAllTiles() re-evaluates every tile
on the map and stalls large levels. Reserve the full refresh for whole-map regenerations.
- Painting onto the wrong layer — the active target Tilemap in the Tile Palette determines
where paint lands; check the "Active Tilemap" dropdown.
References
- Primary docs: Unity Manual "Tilemaps"
(
https://docs.unity3d.com/Manual/tilemaps/work-with-tilemaps/tilemap-reference.html),
ScriptReference/Tilemaps.Tilemap, ScriptReference/Collider2D-compositeOperation, the
Manual "Tilemap Collider 2D component reference", and the 2D Tilemap Extras package manual
(https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@6.0/manual/index.html) for
Rule Tiles. (@6.0 is the version that ships with Unity 6.3 LTS; the old @1.6 docs are
for Unity 2021-era projects.)
Related skills
level-design — engine-agnostic blockout, pacing, and tile layout practice.
procedural-gen — generating the tile data (noise, RNG, dungeons) you feed to SetTilesBlock.
platformer / roguelike — genres that compose this skill with movement and generation.
1---2name: unity-tilemap-2d3description: >4 Build and script 2D tilemaps in Unity 6.3 LTS: the Grid + Tilemap components, the Tile Palette,5 tilemap colliders, rule tiles, and runtime SetTile/GetTile painting. Use when painting tile6 levels, adding a TilemapCollider2D, using rule or animated tiles, generating tilemaps from7 code, or when the user mentions Unity tilemap, tile palette, rule tile, or Grid.8metadata:9 source: https://skillmd.com/skills/junmystery/unity-tilemap-2d10---1112# Unity 2D Tilemap1314Author and script tile-based 2D levels in Unity 6.3 LTS with the `Grid`/`Tilemap` system, the Tile15Palette, colliders, and runtime painting. Targets **Unity 6.3 LTS (6000.3)**.1617> **Package note:** the core Tilemap (`Grid`, `Tilemap`, `Tile`, `TilemapCollider2D`) is18> built in, and so is the Tile Palette with its default brush. **Rule Tiles, Animated Tiles,19> and the extra brushes (Random, Line, GameObject, Group) live in the separate "2D Tilemap20> Extras" package (`com.unity.2d.tilemap.extras`, 6.0.x for Unity 6.3)** — install it via21> Package Manager before using `RuleTile`.2223## When to use2425- Use when laying out a 2D level by painting tiles, setting up a `Grid` + `Tilemap`, adding26 collision to the map, using auto-tiling Rule Tiles, or generating/editing tiles from script.27- Use when scenes contain a `Grid` with `Tilemap` children, or `*.asset` tile/palette files.2829**When _not_ to use:** level _design_ practice (pacing, blockout, layout principles) →30`level-design`. 3D tile/grid placement → Unity's own 3D tooling (ProBuilder / grid brushes; no dedicated skill here). The platformer character that31moves over the tiles → `platformer` / `unity-physics`.3233## Core workflow34351. **Create the grid:** GameObject → 2D Object → Tilemap → Rectangular (the `Grid`'s **Cell36 Layout** also offers Hexagonal and Isometric for hex/iso levels). This makes a `Grid`37 with a child `Tilemap` (+ `TilemapRenderer`). Use one Tilemap per layer (background,38 ground, foreground) and set each renderer's sorting.392. **Open the Tile Palette** (Window → 2D → Tile Palette), drag in a sliced sprite sheet to40 create `Tile` assets, then paint with the brush tools.413. **Add collision** to the solid layer: `TilemapCollider2D`. For one merged collider (far42 cheaper and gap-free), also add `CompositeCollider2D` (+ a `Rigidbody2D` set to **Static**)43 and set the tilemap collider's **Composite Operation** to **Merge**.444. **Auto-tile with Rule Tiles** (2D Tilemap Extras) so edges/corners pick the right sprite45 automatically instead of hand-placing every variant.465. **Edit at runtime via script** with cell coordinates (`Vector3Int`): `SetTile`, `GetTile`,47 `SetTilesBlock`, converting world↔cell with the `Grid`/`Tilemap`.486. **Verify** in Play mode: confirm collisions (Physics Debugger), sorting order, and that49 `RefreshAllTiles` ran after bulk edits.5051## Patterns5253### 1. Painting tiles at runtime (cell coordinates)5455```csharp56using UnityEngine;57using UnityEngine.Tilemaps;5859public class TilePainter : MonoBehaviour60{61 [SerializeField] private Tilemap tilemap; // assign the target Tilemap62 [SerializeField] private TileBase groundTile;6364 // World position -> cell, then place a tile.65 public void PaintAt(Vector3 worldPos)66 {67 Vector3Int cell = tilemap.WorldToCell(worldPos);68 tilemap.SetTile(cell, groundTile);69 }7071 public bool IsSolid(Vector3 worldPos)72 => tilemap.GetTile(tilemap.WorldToCell(worldPos)) != null;73}74```7576### 2. Bulk fill a region (faster than per-cell `SetTile`)7778```csharp79// SetTilesBlock writes a whole BoundsInt in one call — use it for procedural rooms/floors.80public void FillFloor(Tilemap map, TileBase tile, int width, int height)81{82 var bounds = new BoundsInt(0, 0, 0, width, height, 1);83 var tiles = new TileBase[width * height];84 for (int i = 0; i < tiles.Length; i++) tiles[i] = tile;85 map.SetTilesBlock(bounds, tiles);86}87```8889### 3. Clearing and refreshing9091```csharp92tilemap.SetTile(cell, null); // null erases the tile at that cell93tilemap.RefreshTile(cell); // re-evaluate just this cell's rule/animated neighbors (cheap)94// RefreshAllTiles() re-evaluates the ENTIRE map — reserve it for full regenerations, not per-edit.95```9697## Pitfalls9899- **`RuleTile` type not found** — it's not built in. Install the **2D Tilemap Extras** package100 (`com.unity.2d.tilemap.extras`) via Package Manager.101- **A collider per tile tanks performance / leaves seams** — add a `CompositeCollider2D` with a102 static `Rigidbody2D` and set Composite Operation to **Merge** to merge the whole layer into103 one smooth shape.104- **No "Used By Composite" checkbox, or an obsolete warning on `usedByComposite`** — Unity 6105 replaced it with **Composite Operation** (`Collider2D.compositeOperation`). Old106 `usedByComposite = true` maps to `CompositeOperation.Merge`; write that instead.107- **Small gaps remain between merged tiles** — raise the Tilemap Collider 2D's **Extrusion108 Factor** so neighbouring tile shapes fall within the Composite Collider 2D's Vertex Distance.109- **Confusing world and cell coordinates** — `SetTile`/`GetTile` take a `Vector3Int` _cell_,110 not a world position. Always convert with `WorldToCell` / `CellToWorld`.111- **Tiles render behind/in front of sprites unexpectedly** — set each `TilemapRenderer`'s112 Sorting Layer and Order in Layer; multiple tilemaps need explicit ordering.113- **Rule/animated tiles don't update after script edits** — refresh after writes, but prefer114 the targeted `RefreshTile(cell)` for a few edits; `RefreshAllTiles()` re-evaluates every tile115 on the map and stalls large levels. Reserve the full refresh for whole-map regenerations.116- **Painting onto the wrong layer** — the active target Tilemap in the Tile Palette determines117 where paint lands; check the "Active Tilemap" dropdown.118119## References120121- Primary docs: Unity Manual "Tilemaps"122 (`https://docs.unity3d.com/Manual/tilemaps/work-with-tilemaps/tilemap-reference.html`),123 `ScriptReference/Tilemaps.Tilemap`, `ScriptReference/Collider2D-compositeOperation`, the124 Manual "Tilemap Collider 2D component reference", and the 2D Tilemap Extras package manual125 (`https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@6.0/manual/index.html`) for126 Rule Tiles. (`@6.0` is the version that ships with Unity 6.3 LTS; the old `@1.6` docs are127 for Unity 2021-era projects.)128129## Related skills130131- `level-design` — engine-agnostic blockout, pacing, and tile layout practice.132- `procedural-gen` — generating the tile data (noise, RNG, dungeons) you feed to `SetTilesBlock`.133- `platformer` / `roguelike` — genres that compose this skill with movement and generation.