Tilemaps

A tilemap layer is painted with tiles: small pictures, all the same size, kept in the layer's tileset. The layer itself only records which tile sits in each cell of its grid (and whether it's flipped or rotated). Repaint a tile and every cell that uses it changes, which is what makes tiles good for walls, floors and terrain.

Making a tilemap layer

• New: Layer > New Tilemap Layer... asks for a name and a tile width and height (16×16 unless you change it). It starts with an empty tileset. If the sprite already has a tileset, you can choose Use existing to share it (below).
• From an image layer: Layer > Tilemap > Convert to Tilemap... cuts the layer's art, on every frame, into tiles and replaces it with tile placements. Share identical tiles makes repeated squares one tile; Also share flipped and rotated tiles catches mirrored copies too. The grid starts at the canvas's top-left corner, and art past the canvas edges is kept as tiles too. Each cel keeps its opacity, z-index and user data, which you can change in Cel properties (right-click the cel), as on any layer.
• Back to pixels: Layer > Tilemap > Convert to Normal Layer turns the tiles into ordinary pixels on every frame, tiles outside the canvas included.

The three modes

With a tilemap layer active, the tool options bar shows Tiles, Pixels: Auto and Pixels: Edit, and a Tile grid checkbox that draws the tile boundaries. Press Alt+T to switch between Tiles and the pixel mode you used last. (Aseprite uses Tab for this; here Tab only moves between controls.)

Choosing Tiles switches to the Tile Stamp, and picking a drawing tool switches back to a pixel mode, so the tool and the mode always match.

The Tileset panel

The Tileset panel shows the active tilemap layer's tiles, with how many cells use each. Click a tile to select it: the selected tile is the one the Tile Stamp places. Tile 0 is the empty tile and is always there.

• The buttons add an empty tile, duplicate the selected tile (the copy goes at the end), clear it to transparent, or delete it (if cells use it, you're asked first, and those cells are emptied). Every change can be undone.
• Drag a tile, or press Alt with an arrow key, to reorder the tileset. Cells keep showing the same pictures.
• Auto match (Flip H, Flip V, Rotate) lets Pixels: Auto reuse a tile when the new picture matches it flipped or rotated.
• Stamp (Flip H, Flip V, Rotate 90°) flips or turns the tile the Tile Stamp places. Only square tiles can be rotated.
• Layer > Tilemap > Tileset Properties... names the tileset and sets its Base Index: the number shown for the first tile (1, as in Aseprite; from -32768 to 32767). It only changes the numbering. Its User Data section holds a color, a note and custom properties for the tileset (User data and custom properties).

Stamping tiles

With the Tile Stamp, click or drag across the layer to put the selected tile in each cell you pass over. Hold Alt as you start to remove tiles instead. A whole drag is one undo step. The layer must be visible and unlocked.

Placing tiles with other tools

With a tilemap layer active, the pencil, eraser, line, rectangle, ellipse, triangle, hexagon, star and bucket have a Place tiles checkbox. With it on, they place the selected tile (and its Flip and Rotate settings, as set for the Tile Stamp) on tilemap cells instead of painting pixels, whatever the Tiles / Pixels mode:

• A cell is covered when any pixel the tool would paint lies inside it: a one-pixel pencil dot places one tile, an outline rectangle the cells its outline crosses, a filled one every cell it fills. Brush size counts. The eraser empties the cells it touches.
• The bucket fills the connected cells (up and down, left and right) that hold the same tile as the one you click, with the selected tile. An empty cell counts as tile 0. Global fills every cell holding that tile instead. It stays inside the canvas's grid of cells, so on an empty layer it fills the visible grid and no further.
• Symmetry mirrors the placement. A cell goes to the cell holding the mirror of its center, and the tile is flipped to match: a vertical axis toggles Flip H, a horizontal axis Flip V, and a diagonal axis turns the tile (Rotate 90° plus a flip, square tiles only). A cell on an axis keeps the tile as you placed it. The bucket fills again from each mirrored click.
• A selection limits the placement to cells with at least one selected pixel (the bucket also stops at the others).
• Each stroke or fill is one undo step, and one that changes nothing leaves none.

The Tile Stamp follows symmetry and the selection too.

Sharing a tileset

Several tilemap layers can use the same tileset: choose Use existing in Layer > New Tilemap Layer.... Editing, adding, removing or reordering tiles then reaches every layer that shares it, which is how you keep a background layer and a foreground layer in step. The panel's header shows how many layers share the tileset. Locking one of them protects it: a tile it shows can't be repainted, cleared or deleted (or edited with Pixels: Edit) through another layer until you unlock it.

Importing tiles

Layer > Tilemap > Import Tiles from Image... cuts a picture into tiles of the tileset's size and adds them. The picture can be an image file, the active frame, or the selection on it. It can skip duplicate tiles (also flipped and rotated ones), skip empty tiles, and place the tiles on the active frame as well.

Animated tilemaps

Each frame has its own tile placements, so a tilemap can animate. Frames can be linked on a tilemap layer too (Frame > New Linked Frame, Edit > Cel > Link Cels): linked frames share their placements. Remember that Pixels: Edit changes the tiles themselves, so it shows on every frame that uses them, linked or not.

Exporting

File > Export... with the type Tilemap (JSON / Tiled) writes a PNG image of each tileset plus either:

• Tiled (.tmj map with .tsj tilesets), for the Tiled editor and engines that read its format. Tiled maps have no frames, so only the selected frame is exported.
• JSON (all frames), a simple file with every frame's tile numbers and durations.

In both, a cell of 0 is empty, and flips and rotation are stored in the top bits of the number, as Tiled does. Tilemaps are also kept in Aseprite files, shared tilesets included.