# Tilemaps

Build levels and repeating art from tiles: tilemap layers, tilesets, the three tile modes, shared tilesets, and exporting to Tiled and game engines.

_Shortcuts are written for Windows and Linux. On a Mac, use ⌘ Cmd where they say Ctrl, and ⌥ Option for Alt._

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.)

| Mode | What painting does |
| - | - |
| **Tiles** | Place whole tiles with the Tile Stamp. The pixel tools don't paint in this mode. |
| **Pixels: Auto** | Paint pixels as on any layer; only the cells you touch change. A cell that ends up identical to an existing tile reuses it; a new picture becomes a new tile; a tile used elsewhere is copied for this cell, so the other cells keep theirs. A cell you erase completely becomes empty again. Tiles your edit leaves unused are removed. |
| **Pixels: Edit** | Paint straight into the tiles themselves: every cell, on every frame, that uses a tile changes with it. Empty cells stay empty. |

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](https://pxstud.io/docs/manual/guides/document.md#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.