Aseprite Tilemap Guide: Grid Sizes, Modes, and the Gotchas Nobody Explains
What Aseprite’s Tilemap Actually Does
Aseprite’s tilemap support has been part of the tool since v1.3, and the core idea is simple: a tilemap layer is a grid where each cell points to a tile in a tileset, rather than storing pixel data directly. Think of it like indexed color — the tileset is your palette, and the tilemap is the image that references entries from it. Every tile has an index, with 0 reserved for the empty/transparent tile that cannot be drawn on or deleted.
The feature is genuinely useful once you understand the mental model. The problem is that the official documentation assumes you already do, and skips over several things that trip people up on first contact.
The Grid Size Is Fixed at Creation — on Purpose
The single most common frustration: you try to change the tile grid size after creating a tilemap layer, and nothing happens. This is not a bug. Tile dimensions are baked into the tileset at the moment you create it, because every tile in a tileset must share the same size. Changing that retroactively would mean resizing all existing tiles, a destructive operation Aseprite does not automate.
The fix is boring but real: start a new tilemap layer with the correct dimensions. Go to Layer > New > New Tilemap Layer (or Space+N). The dialog that appears is the one and only place to set tile width and height. Do it there, before drawing anything.
A workaround circulates in community discussions: right-click the layer, convert it to a normal layer, adjust the grid under View > Grid > Grid Settings, then convert it back to a tilemap layer. This works inconsistently. If the layer already has content, results can be unpredictable. If it is empty or early-stage, scrapping it and creating a new one with correct dimensions is faster and cleaner.
Two Modes, Three Submodes
The tilemap system has two separate mode layers, and their interaction is what confuses most new users. The top-level toggle is Space+Tab.
Draw Pixels vs. Draw Tiles
Draw Pixels lets you paint directly into individual tile images. Any change to a tile is reflected everywhere that tile is used across the canvas, because the tileset stores the actual pixel data and the tilemap only stores references to it.
Draw Tiles lets you place tiles from your tileset onto the grid cells. You are not editing what tiles look like — you are arranging which tile goes in which cell. This is the mode for building out your map layout.
If your tools are not behaving as expected, check this toggle first. It is the most common source of confusion for new users.
The Three Tileset Submodes
Inside Draw Pixels mode, Space+1, Space+2, and Space+3 switch between three submodes that control how the tileset itself changes as you draw:
- Manual (Space+1): You control the tileset entirely. Drawing modifies an existing tile without creating or removing others. Use this when your tileset is finalized and you are touching up pixel art without wanting the tile structure to shift.
- Auto (Space+2): The default mode. Aseprite creates a new tile when you paint something unique, and removes tiles that no longer appear anywhere on the canvas. Best for early drafting when tile count is still in flux.
- Stack (Space+3): Every stroke creates a new tile, even if an identical one already exists in the set. It grows the tileset fast. Useful when you specifically need each grid cell to hold an independent, unshared tile image.
Auto mode surprises people: if you draw something and then erase it, that tile disappears from the tileset because it has zero remaining references. That is correct behavior, not a glitch. If tile preservation matters, switch to Manual before editing.
Aseprite Tilemaps Are Not a Replacement for Tiled
Artists in game dev circles often steer newcomers toward Tiled Map Editor, and that recommendation is fair for a specific reason: Tiled is a dedicated map editor built for assembling tiles into full game levels, with multi-layer support, object layers, isometric and hexagonal grid modes, custom properties, and direct export pipelines to engines like Godot and Unity.
Aseprite’s tilemap feature is doing something different. It lets you draw, iterate on, and preview tile art inside the same tool you are already using to create it — without needing to export a spritesheet and reimport it elsewhere to check how tiles fit together visually. The intended workflow for most projects is: create and refine tiles in Aseprite, then arrange them into levels in Tiled or your engine’s built-in editor. Aseprite has shipped as the art tool of record on games like Celeste, Wargroove, and Pizza Tower, and in each case the actual level layout happened elsewhere.
If you are trying to use Aseprite’s tilemap as a full level editor, you will hit walls. Used as a tile-creation and in-context preview workspace, it handles that job well.
Practical Notes Before You Start
- Decide on tile size before drawing anything. Whether it is 16×16, 32×32, or something custom — set it in the layer creation dialog and do not expect to change it later.
- Canvas dimensions that are exact multiples of your tile size will avoid partial-tile artifacts at the edges. A 16×16 tile grid works cleanly on a 160×96 canvas; a 160×100 canvas leaves a 4-pixel orphaned row at the bottom.
- You can share a tileset across multiple tilemap layers. In the layer creation dialog, look for the option to select an existing tileset rather than generating a new one. Useful when different layers should draw from the same pool of tiles.
- The keyboard shortcuts for mode switching — Space+Tab, Space+1/2/3 — are not labeled anywhere obvious in the default UI. Writing them down until they become muscle memory will save a lot of head-scratching.
- Tile 0 is always the empty tile. The blank slot at the start of the tileset panel is permanent and cannot be replaced.
Sources