Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-tilemap-2d

unity-tilemap-2d

Verified

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 corner, edge and centre cells.

  • No CLI: a PlayMode or EditMode test can build a Grid and Tilemap in code, call SetTilesBlock, and assert GetUsedTilesCount() and GetSprite results (setup in unity-csharp-scripting).

  • Looks: ask the user to enter Play mode and report any visible seams or sorting problems, with a screenshot if possible.

Gotchas

  • RuleTile type not found. 2D Tilemap Extras is not installed or not resolved yet.
  • A collider per tile is slow and catches characters on seams. Merge through a CompositeCollider2D with a static Rigidbody2D and Composite Operation = Merge.
  • No "Used By Composite" checkbox, or an obsolete warning on usedByComposite. Unity 6 replaced it with Collider2D.compositeOperation; usedByComposite = true becomes CompositeOperation.Merge.
  • Small gaps remain after merging. Raise the Tilemap Collider 2D's Extrusion Factor so neighbouring shapes fall within the composite's Vertex Distance.
  • World and cell coordinates mixed up. SetTile/GetTile take a Vector3Int cell. Convert with WorldToCell/CellToWorld (or GetCellCenterWorld for a tile's centre).
  • Tiles draw over or under sprites unexpectedly. Set each TilemapRenderer's Sorting Layer and Order in Layer explicitly; several tilemaps need explicit ordering.
  • Rule or animated tiles do not update after script edits. Refresh the edited cells with RefreshTile; RefreshAllTiles() on a large map stalls.
  • cellBounds is larger than the painted area. Bounds do not shrink when tiles are erased until you call CompressBounds().
  • Paint lands on the wrong layer. The Tile Palette paints into its Active Tilemap; check that dropdown, or set the tilemap reference explicitly in code.

Related skills

  • level-design: blockout, pacing and layout practice.
  • procedural-gen: generating the tile data you feed to SetTilesBlock.
  • unity-physics: Rigidbody2D movement and 2D queries against the merged collider.
  • platformer, roguelike, puzzle: genres that combine this with movement and generation.

Version notes

Last verified: 2026-11-11, against Unity 6000.3.28f1.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall