Skip to content

Tilemap

A grid of tiles drawn from a tileset, with optional collision.

A tilemap draws a grid of tiles from a .tileset asset, and builds 2D physics collision from each tile's collision shape. It can lay tiles out orthogonally, isometrically, staggered or as hexagons. Tilemaps can be imported from Tiled, and Pathfinding can search across them.

Scene file

Saved as a <Tilemap> element inside the entity's <Entity> element. Attributes that are left out keep their default. See Scene Files for how values like vectors, colours and file paths are written.

<Tilemap Filepath="Tilesets/Dungeon.tileset" TilesWide="4" TilesHigh="3"
         TileWidth="16" TileHeight="16" Orientation="Orthogonal" IsTrigger="false" Layer="1" Mask="65535">
    <Tint R="1" G="1" B="1" A="1"/>
1,2,2,3,
4,0,0,6,
7,8,8,9
</Tilemap>
Name Where Type Default
Filepath attribute: project-relative path path to a .tileset none
TilesWide / TilesHigh attributes int, grid size in tiles
TileWidth / TileHeight attributes int, tile size in pixels
Orientation attribute Orthogonal, Isometric, Staggered or Hexagonal Orthogonal
IsTrigger attribute bool, collision reports overlaps without blocking false
Layer attribute int, bit of the collision layer the collider is on 1 (Default)
Mask attribute int, bits of the collision layers it collides with 65535 (everything)
Tint child R G B A float, 0-1 1, 1, 1, 1
text content element text comma-separated tile indices, top row first all 0

Tile index 0 is an empty cell, and index n is tile n - 1 in the tileset. The text must contain exactly TilesWide × TilesHigh numbers. Line breaks are only there for readability.

Lua scripting

Properties

  • IsTrigger (boolean): Whether this tilemap's collision only reports overlaps instead of physically blocking
  • Layer (string): Name of the collision layer this collider is on (read-only)
  • Mask (table of string): Names of the collision layers this collider collides with (read-only)
  • Orientation (integer (enum)): How tiles are laid out: orthogonal, isometric, staggered or hexagonal
  • TileHeight (integer): Height of a single tile, in pixels
  • TileWidth (integer): Width of a single tile, in pixels
  • TilesHigh (integer): Number of tile rows - use Resize() to change this and the tile grid together
  • TilesWide (integer): Number of tile columns - use Resize() to change this and the tile grid together
  • Tileset (Tileset): The tileset this map draws its tiles from
  • Tint (Colour): Colour multiplied over every tile

Functions

  • CollidesWithLayer(): Whether this collider's mask includes the named collision layer
  • GetTile(): Get the tile index at the given column/row, or 0 if out of bounds
  • Rebuild(): Regenerate the tilemap's mesh from the current tile grid (runs in the background; call UpdateRebuild to pick up the result)
  • Resize(): Resize the tile grid to the given width/height in tiles, preserving existing tile data
  • SetTile(): Set the tile index at the given column/row, if within bounds