Manual

Manual

Tilemaps

A Tilemap is a grid of tiles, each a slice of one image, drawn among sprites. This page covers the Tilemap component and its tile set, painting tiles in the Scene panel from the Tile Palette, the shape of each tile for physics and shadows, collision with the Tilemap Collider 2D, and setting tiles from code.

How a level is made of Tilemaps

A tile set is an image cut into a grid of slices in the Sprite Editor: each slice is one tile. A Tilemap draws tiles of one tile set, each in a cell of its grid, and a cell can hold any slice, flipped across or up, or nothing.

A level is usually several Tilemaps, one entity each: a background, the ground the player walks on, and a foreground drawn in front of the player. Each has its own Sorting Layer and Order in Layer, so they are drawn in order among the sprites (see Draw order). Each can carry its own components too: a Tilemap Collider 2D on the ground alone, a Shadow Caster 2D on the walls, Unlit 2D on a far background.

Make a Tilemap

  1. Prepare the tile set. Pick the image in the Project panel, set its Texture Type to Sprite (2D and UI), its Sprite Mode to Multiple, and its Pixels Per Unit to the size of a tile in pixels if one tile should be one unit. For pixel art, set Filter Mode to Point. Click Apply.
  2. Click Sprite Editor, open the Slice menu, choose Grid By Cell Size with your tile size, click Slice, then Apply. See Sprite sheets and the Sprite Editor.
  3. Choose Entity ▸ 2D Object ▸ Tilemap, or Tilemap in the Hierarchy's + menu.
  4. Drop the image on the Tilemap's Tile Set slot in the Inspector.
  5. With the Tilemap picked, choose Paint (B) in the Scene panel's row, pick a tile in the Tile Palette, and click or drag in the Scene panel.

The Scene panel's 2D view (press 2) is the easiest place to paint, and a 2D camera draws the Tilemap in the game, as it draws sprites.

Tilemap

FieldWhat it does
Tile SetThe image its tiles are slices of. Drop an image cut into a grid in the Sprite Editor on it, or pick one with its button. Click the slot to find the image in the Project panel.
Tile SizeHow wide and tall a cell is, in units. 0 each way, the default, is the tile set's own size: a tile's pixels over the image's Pixels Per Unit, so a 16-pixel tile at 32 pixels per unit is half a unit. A tile set whose slices are not known yet draws a unit a tile.
ColorA tint over every tile, alpha included. White draws them as they are.
Sorting LayerThe sorting layer it is drawn on among sprites.
Order in LayerIts order on that layer; a higher one is drawn over a lower one.

A cell is a whole number of tiles along X and up Y from the Tilemap's entity: the cell at 0, 0 fills the square from the entity's origin to one tile along each. Move, turn or scale the entity and the grid goes with it.

Each tile is drawn from its slice of the image and never a pixel past it, so tiles do not bleed into their neighbors at any zoom, and they are sampled as the image's import says. A tile keeps its slice by the slice's identity, so cutting the tile set again, renaming its slices or putting them in another order leaves every tile on its slice.

The Tile Palette

Window ▸ Tile Palette shows the tile set of the picked Tilemap, to pick the brush you paint with. It opens docked beside the Logs, and comes forward by itself when you choose one of the painting tools.

  • Click a tile to make it the brush.
  • Drag over several tiles to take them as a block, placed as they are in the image. A tree cut into two by four tiles is painted as a tree.
  • The wheel zooms about the pointer, the middle or right button drags the tile set about, and F fits it again. It opens at the largest whole zoom that fits, so pixel art stays crisp.
  • The two buttons at the top right flip the brush across and up, each tile flipped with it.

Picking a tile chooses Paint where no painting tool, Erase or Pick was chosen. The tiles of the brush are outlined in blue, and the Brush line under the tile set says what it is: a tile's name, and how it is flipped, or the size of a block, such as 2 × 4 tiles.

On the line beside it, Collision and Shape set how the brush's tiles are met by physics and what of their cell they fill (see Tile shapes and Collision). Both are the slices' own, written into the image's sidecar at once, so every Tilemap using the tile set follows. Where the brush's tiles differ, the list shows a dash.

The tile set shows each slice's collision: dimmed where it is met by nothing, with a band along its top where it is one-way, and its shape outlined in green where it is not the whole cell. A Tilemap with no tile set, or one whose image is not cut into tiles, says so, the latter with a Sprite Editor button.

Painting tools

While exactly one entity with a Tilemap is picked, the Scene panel's row of tools has six more after Move, Rotate, Scale and Rect:

ToolKeyWhat it does
SelectSDrag to pick a rectangle of cells; see Select, move and copy tiles.
PaintBClick to lay the brush with its bottom left on the cell under the pointer. Drag to lay it at every cell you pass, with no gaps however fast you move.
RectangleUDrag from corner to corner to fill a rectangle of cells with the brush, repeated from its bottom left.
FillGClick to fill the cells joined by their sides to the one clicked, and holding what it holds, with the brush's tile. A fill of empty cells goes no further than the rectangle round the Tilemap's tiles and the cell clicked.
EraseDClick to take away the tile under the pointer. Drag to take away every tile you pass.
PickIClick to take the tile under the pointer as the brush, or drag to take a rectangle of tiles, then Paint is chosen.

With one of them chosen, a press in the Scene panel paints instead of picking entities, and the Move, Rotate and Scale handles are hidden. Choose a transform tool, with its button or W, E, R or T, to put the painting tools aside.

Before you press, the brush is drawn faint where it would go, and the cells a press would take are outlined: red for Erase. A right-click, the right button pressed and let go without moving, takes the tile under the pointer as the brush with any tool, so you can pick tiles without leaving the Scene panel. The right button still flies and pans the view when you drag it.

Each stroke, from press to release, is one step of Ctrl+Z. Escape during a stroke puts the tiles back as they were. The painting tools work while the game is edited, not while it plays.

Select, move and copy tiles

With Select (S), drag a rectangle to pick its cells, empty or not, or click to pick one. Hold Shift to add to the cells picked, or Ctrl to take from them. The cells picked are tinted and outlined. While the Scene panel has the keyboard:

  • Drag from a picked cell to move their tiles. They are laid over what is there as you go, and what they covered comes back as they pass. Escape puts them back.
  • Delete takes their tiles away (Cmd+Backspace on a Mac).
  • Ctrl+C takes their tiles up as the brush, placed as they are; Ctrl+X does the same and takes them away.
  • Ctrl+V chooses Paint to lay the brush, so you paste where you click.
  • Ctrl+A picks every cell holding a tile.
  • Escape lets go of the cells.
  • The Tile Palette's flip buttons mirror the picked tiles across or up, each tile flipped too.

While Select is chosen these keys act on the tiles, and so do Edit ▸ Cut, Copy, Paste, Delete and Select All, so Delete never takes the Tilemap itself away. Undoing a move or a flip picks the cells again where they were.

Tile shapes

A tile's shape is what of its cell it fills, as physics meets it and as light casts its shadow. A wall seven pixels wide down one side of its cell should stop a character at the wall, not at the edge of the cell. Each slice of the tile set has one of three shapes:

ShapeWhat it fills
FullThe whole cell. The default.
TracedWhat of the slice's art shows: its pixels whose alpha is above a tenth, outlined, holes and all. Its Smoothing, in pixels, straightens the outline wherever no corner is further than that from a straight line, so stair steps of a pixel become a slope at 1, the default. 0 keeps every pixel's corner. Where the outline meets the slice's sides stays put, so it lines up with the next tile.
DrawnShapes you draw on the slice, each a loop of corners, filled.

Set the shape of the brush's tiles with the Tile Palette's Shape list. A slice made Drawn there starts from what of its art shows. The pencil button before the list, Edit Shape, opens the brush's first slice in the Sprite Editor to draw it.

Draw a shape in the Sprite Editor

In the Sprite Editor, the list at the top left switches the canvas from Slices to Tile Shape. Every slice's shape is drawn in green, and a click picks a slice without moving it. The side of the panel shows the picked slice's Shape list, a Traced shape's Smoothing, and two buttons that make it Drawn from what of its art shows:

  • Trace draws the shape round the art, as Traced would, so you can move its corners from there.
  • Box draws a box round the art.

On a Drawn shape, drag a corner to move it, snapped to the image's pixels and kept inside the slice. Double-click a line to add a corner there, and double-click a corner to take it out. Escape during a drag puts the corner back. As with the slices, nothing is written until Apply.

A tile's shape is mirrored with the tile when it is flipped. Neighboring tiles' shapes are joined into one outline, so a column of thin walls is one tall edge with no seam.

Collision

How a tile is met by Physics 2D is also its slice's own, set with the Tile Palette's Collision list for the brush's tiles:

CollisionMet as
SolidGround or a wall, from every side. The default.
NoneNot at all: a background tile, grass, a torch.
One-WayA platform, met from above alone, so a character jumps up through it and lands on it.

Tilemap Collider 2D

The Tilemap Collider 2D component of the Physics 2D package (Add Component ▸ Tilemap Collider 2D on the Tilemap's entity) makes the Tilemap something bodies collide with. Its outline is a loop round each region of solid tiles joined by their sides, each straight run of it one edge, so a floor of a hundred tiles has no seam between tiles for a sliding character to catch on. The top of each row of one-way tiles is a line met from above. Each tile counts as its shape, and a tile of a slice the tile set no longer has is met by nothing.

FieldWhat it does
Is TriggerMeets nothing, and is told of what crosses its outline.
MaterialIts physics material; none for Physics 2D's default.

The outline is made again as the tiles change, while editing and while the game plays, so taking a tile away from code drops what rested on it. With the Tilemap picked, the Scene panel draws the outline in green, with a tick up from the middle of each one-way line. The Tilemap needs no Rigidbody 2D to be still ground; a Platform Effector 2D on its entity sets how its one-way tiles are met. Rigidbodies, colliders and effectors are covered in Physics 2D bodies.

A Shadow Caster 2D on a Tilemap casts shadows from the same outline of its solid tiles; see 2D lights.

Tilemaps from code

world.Tilemaps sets and reads the tiles of the Tilemap on an entity, by cell. Call it from code that runs between frames, such as a flow or a plugin's Started hook (see C# in a game):

// map: the Tilemap's entity, for example from an EntityRef field set in the Inspector.WorldTilemaps tilemaps = flow.World.Tilemaps;
Tile grass = tilemaps.TileNamed(map, "grass");   // a slice of its tile set, by its nameTile dirt = tilemaps.TileNamed(map, "dirt");
tilemaps.SetTile(map, 0, 0, grass);tilemaps.SetTile(map, 1, 0, grass.Flipped(flipX: true, flipY: false));tilemaps.SetTile(map, 2, 0, Tile.None);          // empties the cell
// Many at once write the tiles once: a level built from code.var floor = new PlacedTile[64];for (int x = 0; x < floor.Length; x++){    floor[x] = new PlacedTile(x, -1, dirt);}tilemaps.SetTiles(map, floor);
Tile under = tilemaps.TileAt(map, 3, -1);if (under.IsNone) { /* nothing there */ }
(int X, int Y) cell = tilemaps.CellAt(map, playerPosition);   // the cell a Vector3 of the world is overint filled = tilemaps.Fill(map, cell.X, cell.Y, grass);      // like the Fill tool
MethodWhat it does
SetTile, SetTilesPut one tile, or many writing the tiles once, in their cells. Tile.None empties a cell.
TileAt, TilesWhat one cell holds, or every cell holding a tile.
FillFills the cells joined to one, as the Fill tool does, and says how many changed.
ClearTakes every tile off.
TileNamedA slice of the tile set as a tile, by the name the Sprite Editor gave it.
CellAtThe cell a point of the world is over: what a character stands on, or what was clicked.
TileSizeHow big a cell is, in units, after the tile set's own size is worked out.
SetTileset, TilesetGive the Tilemap another tile set, or read the one it has.

A Tile is a slice's identity and its two flips, so a tile a game keeps stays the same slice when the tile set is cut again. A call about an entity with no Tilemap throws an AbyssException.

A game's Rust systems take GameTilemaps from abyss_ffi, which sets and reads tiles by cell as an ordinary system parameter:

use abyss_ffi::{GameTilemaps, Tilemap};
use bevy_ecs::prelude::*;
use bevy_math::IVec2; // bevy_math = { workspace = true } in the crate's Cargo.toml

/// Empties the cell at the origin of every Tilemap whose next cell along is empty.
fn dig(mut tilemaps: GameTilemaps, maps: Query<Entity, With<Tilemap>>) {
    for map in &maps {
        if tilemaps.tile(map, IVec2::new(1, 0)).is_none() {
            tilemaps.set_tile(map, IVec2::ZERO, None);
        }
    }
}

tile gives None for an empty cell. set_tile takes Some(abyss_ffi::Tile::of(slice)) for a slice by its identity, or None to empty a cell, and set_tiles and fill work as they do in C#.

In the Scripting API