/unity-tilemap-2d

name: unity-tilemap-2d
description: >
  Unity 6.3 LTS 2D tilemaps: the Tile Palette, Tilemap Collider 2D with a Composite Collider, Rule
  Tiles and runtime SetTile. Use for painting or generating a tile level, seams between tile
  colliders, RuleTile not found, or hex and isometric grids. Not for level design
  (`level-design`), generation (`procedural-gen`), movement (`unity-physics`) or Godot
  (`godot-tilemap`).

Unity 2D Tilemap

Author and script tile-based 2D levels in Unity 6.3 LTS (6000.3) with `Grid` and `Tilemap`, merged colliders and runtime painting, and check the result by reading the map back.

> **Package note:** `Grid`, `Tilemap`, `Tile` and `TilemapCollider2D` are built in. The Tile > Palette window and default brush come from the 2D Tilemap Editor package > (`com.unity.2d.tilemap`, included in the 2D templates). Rule Tiles, Animated Tiles and the > extra brushes (Random, Line, GameObject, Group) are in **2D Tilemap Extras** > (`com.unity.2d.tilemap.extras`, the 6.0.x line for Unity 6.3).

When to use

• Laying out a 2D level with tiles, a `Grid` with `Tilemap` children, collision for the map,

auto-tiling with Rule Tiles, generating or editing tiles from script.

• Scenes contain a `Grid` with `Tilemap` children, or there are tile and palette `.asset`

files.

**When not to use:** layout and pacing → `level-design`; noise, rooms and dungeon generation that produce the tile data → `procedural-gen`; the character that walks on the tiles → `unity-physics`; 3D grids have no skill here. If Unity's official `create-tile-palette-or-rule-tiles` skill is installed and an Editor is connected, use it to build palettes and Rule Tile assets; this skill owns runtime code and colliders.

Workflow

1. **Gate on packages.** Before writing `RuleTile` or `AnimatedTile` code, confirm `com.unity.2d.tilemap.extras` is in `Packages/packages-lock.json`; ask before adding it. 2. **Set up the grid.** One `Grid` with one `Tilemap` (plus `TilemapRenderer`) per layer: background, ground, foreground. The `Grid`'s Cell Layout is Rectangle, Hexagon, Isometric or Isometric Z As Y. Give each `TilemapRenderer` an explicit Sorting Layer and Order. 3. **Make tiles.** Designers drag a sliced sprite sheet into the Tile Palette. From code, an editor script can create `Tile` assets from the sheet's sprites (pattern 3). 4. **Add collision to the solid layer.** `TilemapCollider2D`, plus a `CompositeCollider2D` (which adds a `Rigidbody2D`: set it to `Static`), and set the tilemap collider's Composite Operation to Merge. One merged shape is cheaper and has no seams. 5. **Edit at runtime in cell coordinates** (`Vector3Int`): `WorldToCell`, `SetTile`, `GetTile`, `SetTilesBlock`, then `RefreshTile` for the edited cells only. 6. **Verify** with the checks below.

Patterns

1. Paint and query at runtime

using UnityEngine;
using UnityEngine.Tilemaps;

public class TilePainter : MonoBehaviour
{
    [SerializeField] private Tilemap tilemap;
    [SerializeField] private TileBase groundTile;

    public void PaintAt(Vector3 worldPos) => tilemap.SetTile(tilemap.WorldToCell(worldPos), groundTile);

    public bool IsSolid(Vector3 worldPos) => tilemap.HasTile(tilemap.WorldToCell(worldPos));
}

2. Fill a region in one call

// SetTilesBlock writes a whole BoundsInt at once: use it for generated rooms and floors.
public static 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);
}

`SetTile(cell, null)` erases a cell. `RefreshTile(cell)` re-evaluates that cell and its rule neighbours; `RefreshAllTiles()` re-evaluates the whole map, so keep it for full regenerations.

3. Create Tile assets from a sliced sheet (editor code)

Put this in an `Editor` folder; run it from the menu, through `unity command script eval --code 'TileAssets.FromSheet("Assets/Art/terrain.png", "Assets/Tiles");'`, or with `-executeMethod` from a wrapper with no parameters.

using System.Linq;
using UnityEditor;
using UnityEngine;
using UnityEngine.Tilemaps;

public static class TileAssets
{
    public static void FromSheet(string sheetPath, string outFolder)
    {
        if (!AssetDatabase.IsValidFolder(outFolder))   // e.g. "Assets/Tiles"; the parent must exist
        {
            int slash = outFolder.LastIndexOf('/');
            AssetDatabase.CreateFolder(outFolder.Substring(0, slash), outFolder.Substring(slash + 1));
        }

        foreach (Sprite sprite in AssetDatabase.LoadAllAssetsAtPath(sheetPath).OfType<Sprite>())
        {
            var tile = ScriptableObject.CreateInstance<Tile>();
            tile.sprite = sprite;
            AssetDatabase.CreateAsset(tile, $"{outFolder}/{sprite.name}.asset");
        }
        AssetDatabase.SaveAssets();
    }
}

The sheet must already be imported as Sprite (Multiple) and sliced; the slices are the sprite sub-assets.

Verify

• **No Editor needed:** the scene YAML holds the map. A `Tilemap:` document lists painted

cells under `m_Tiles:` (`- first: {x: 0, y: 8, z: 0}`), and a `TilemapCollider2D` set to merge has `m_CompositeOperation: 1`. Grep these to confirm the layer has tiles and the collider merges.

• **Unity CLI with a ready Editor:**

  unity command script eval --code 'var t = GameObject.Find("Ground").GetComponent<UnityEngine.Tilemaps.Tilemap>(); t.CompressBounds(); return t.GetUsedTilesCount() + " tiles, bounds " + t.cellBounds;'
  unity command script eval --code 'var c = GameObject.Find("Ground").GetComponent<CompositeCollider2D>(); return "paths=" + c.pathCount;'

A merged layer of one connected area should report a handful of paths, not one per tile. For Rule Tiles, paint a small block into a throwaway tilemap and read `GetSprite(cell)` for the corne