unity-tilemap-2d

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. Rule Tiles, Animated Tiles, and Tile Palette brushes live in the separate "2D Tilemap Extras" package (com.unity.2d.tilemap.extras) — 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

1. 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.
2. Open the Tile Palette (Window → 2D → Tile Palette), drag in a sliced sprite sheet to create Tile assets, then paint with the brush tools.
3. 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 enable Used By Composite on the tilemap collider.
4. Auto-tile with Rule Tiles (2D Tilemap Extras) so edges/corners pick the right sprite automatically instead of hand-placing every variant.
5. Edit at runtime via script with cell coordinates (Vector3Int): SetTile, GetTile, SetTilesBlock, converting world↔cell with the Grid/Tilemap.
6. 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 Used By Composite to merge the whole layer into one smooth shape.
• 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, and the 2D Tilemap Extras package manual (https://docs.unity3d.com/Packages/[email protected]/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.