gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-tilemap-2d
unity-tilemap-2d
VerifiedUnity 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,TileandTilemapCollider2Dare 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
GridwithTilemapchildren, collision for the map, auto-tiling with Rule Tiles, generating or editing tiles from script. - Scenes contain a
GridwithTilemapchildren, or there are tile and palette.assetfiles.
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
- Gate on packages. Before writing
RuleTileorAnimatedTilecode, confirmcom.unity.2d.tilemap.extrasis inPackages/packages-lock.json; ask before adding it. - Set up the grid. One
Gridwith oneTilemap(plusTilemapRenderer) per layer: background, ground, foreground. TheGrid's Cell Layout is Rectangle, Hexagon, Isometric or Isometric Z As Y. Give eachTilemapRendereran explicit Sorting Layer and Order. - Make tiles. Designers drag a sliced sprite sheet into the Tile Palette. From code, an
editor script can create
Tileassets from the sheet's sprites (pattern 3). - Add collision to the solid layer.
TilemapCollider2D, plus aCompositeCollider2D(which adds aRigidbody2D: set it toStatic), and set the tilemap collider's Composite Operation to Merge. One merged shape is cheaper and has no seams. - Edit at runtime in cell coordinates (
Vector3Int):WorldToCell,SetTile,GetTile,SetTilesBlock, thenRefreshTilefor the edited cells only. - 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 underm_Tiles:(- first: {x: 0, y: 8, z: 0}), and aTilemapCollider2Dset to merge hasm_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
GridandTilemapin code, callSetTilesBlock, and assertGetUsedTilesCount()andGetSpriteresults (setup inunity-csharp-scripting). -
Looks: ask the user to enter Play mode and report any visible seams or sorting problems, with a screenshot if possible.
Gotchas
RuleTiletype 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
CompositeCollider2Dwith a staticRigidbody2Dand Composite Operation = Merge. - No "Used By Composite" checkbox, or an obsolete warning on
usedByComposite. Unity 6 replaced it withCollider2D.compositeOperation;usedByComposite = truebecomesCompositeOperation.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/GetTiletake aVector3Intcell. Convert withWorldToCell/CellToWorld(orGetCellCenterWorldfor 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. cellBoundsis larger than the painted area. Bounds do not shrink when tiles are erased until you callCompressBounds().- 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 toSetTilesBlock.unity-physics:Rigidbody2Dmovement 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.
- 2D Tilemap Extras 6.0.3 (2026-08-12) is the newest release of the 6.0.x line, which targets Unity 6000.3; 4.1.x targets 6000.0 and 10.0.x targets 6000.7. Source: Unity package registry, https://packages.unity.com/com.unity.2d.tilemap.extras. Package manual: https://docs.unity3d.com/Packages/com.unity.2d.tilemap.extras@6.0/manual/index.html
Collider2D.CompositeOperation(Merge = 1),usedByCompositedeprecation,Tilemap.GetUsedTilesCount,CompressBounds,GetSpriteandCompositeCollider2D.pathCountwere checked in the Unity C# reference source at tag 6000.3.28f1 (Modules/Physics2D/,Modules/Tilemap/).- Manual: https://docs.unity.com/en-us/engine/6000.3/manual/unity2d/tilemaps/reference/tilemap
script evalis acom.unity.pipeline1.0.0-pre.1 command (pre-release): https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |