Skip to content

Tilemaps

A tile map is ground painted cell by cell. Each cell holds one terrain (water, sand, grass, stone) or none, and what is drawn is worked out from the cells: a drawn tile sits on the corner between four cells and shows each terrain there in the shape that fits, so a lake gets its shore by itself. A terrain marked solid stops bodies in play, and one marked oneWay holds them only from above, as a ledge a body jumps up through.

@shell/tilemap-2d is a Package. A Project made from the editor’s template lists it in its package.json, and ProjectPackages installs its plugin with nothing listing it. Its names come from its own import line, beside the engine’s:

import { NO_TERRAIN, TileLayer, TileMap } from '@shell/tilemap-2d';

Outside a Project, add TileMap2DPlugin beside Engine2D, which has the Pixi and the physics it needs:

import { TileMap2DPlugin } from '@shell/tilemap-2d';
world.addPlugin(Engine2D({ canvas }), TileMap2DPlugin);

It installs three packages’ plugins, and loads /assets/tilesets.index.json as the world mounts:

PackageWhat
@shell/tilemapThe data: maps, layers, chunks, tilesets, the solver, generate. No Pixi
@shell/tilemap-pixiDraws every map, culled by chunk, in the game and the editor’s scene view
@shell/tilemap-physicsMakes solid and one-way cells into static box colliders, in play

A map is three kinds of entity:

  • TileMap: width and height in cells, tileSize in world units, seed, edgeMode and outsideTerrainId (what is read, and drawn, outside it). Its Position is the top-left corner of cell 0, 0.
  • TileLayer, a child of the map: name, tilesetName, its order (index, zIndex), visible, what generate runs on it (algorithmName, baseTerrainId, seedOffset), and variantSeed.
  • TileChunk, a child of a layer: 16 × 16 cells as text, one character a cell (0–9, a–z, . for none). It is made where a cell gets a terrain and taken away when all its cells are empty, so a map stores only where it has terrain, and a change to it is one line of the scene file.

In the editor, Entity › Create › Tile Map… asks for the tileset (the starter where you have none), the size in cells (32 × 32) and the first layer’s name (“Ground”), then makes the map ready to paint: Paint (B) is picked and the Tiles tab is in front. New Tileset… in its list makes an untitled tileset for the map instead, and opens it in its tab to set up. The tools are on the Scene view’s toolbar while a map is selected: Paint (B), Line (L), Rectangle (R), Fill (G), Erase (E) and Pick (or Alt with any of them), then the brush’s size and shape, what is chosen, and Generate. The Tiles tab beside the Inspector is the palette: keys 1 to 9 choose its terrains. A tileset dragged from the Assets panel onto the Scene view asks the same with that tileset, and makes the map where it is dropped.

A map has one layer or more, each with cells and a tileset of its own: a layer of walls over the floor, say, empty wherever there is no wall. A layer of a higher zIndex is drawn over one of a lower, and of equal zIndex the higher index; an empty cell shows what is under it. A layer whose visible is false is not drawn, in the game either, and its solid cells still collide.

A map’s layers are rows under it in the Hierarchy, the topmost first. The layer you select is the one you paint, and its Inspector has its Tileset (with Edit), Base terrain, Draw order (zIndex), Variant seed and Shown in the game (visible). Rename a layer as any row; a drag (or Alt+Arrow) among its map’s layers reorders them, which changes zIndex, and a layer never leaves its map; Delete removes it with what is painted on it. Its row’s eye hides it on your own page while you paint the others. The map’s Inspector lists its layers, says whether its cells are its tilesets’ size, and has Add Layer, as the map row’s menu does. index is given once and never changed: Generate’s seed and the map’s first layer read it.

resources.get('tilemaps') writes only the chunks it touches, and what is drawn and solid follows:

CallWhat
terrainAt(layer, x, y)A cell’s terrain id; -1 for none. Outside the map, what edgeMode says
cellAt(layer, { x, y })The cell a world point is in
isSolid(layer, x, y)Whether the cell’s terrain is solid in the layer’s tileset
isOneWay(layer, x, y)Whether the cell’s terrain is one-way in the layer’s tileset
dataAt(layer, x, y, Type)The settings item of Type the cell’s terrain links to by data
setTerrain(layer, x, y, id)Sets one cell; -1 empties it
fillRect(layer, x, y, width, height, id)Sets a rectangle, the part inside the map; answers how many changed
generate(map, { seed?, layer?, rect?, algorithm?, settings? })Runs each layer’s algorithm, or one, over the map or a rectangle
tileAt(layer, x, y)The parts drawn tile x, y shows
originOf(map)Where cell 0, 0 begins in the world
const tilemaps = resources.get('tilemaps');
const [layer] = resources.get('tilemapIndex').layersOf(map);
const cell = tilemaps.cellAt(layer, player.$position);
if (tilemaps.isSolid(layer, cell.x, cell.y + 1)) {
// standing on something solid
}

dataAt reads what a terrain means to the game: a type of your own marked .presets() (a file for each kind of ground), and the asset of it that the terrain links to by data. It is read each time, so a repaint or a changed asset is followed at once:

const ground = tilemaps.dataAt(layer, cell.x, cell.y, Ground); // undefined where there is no link
const speed = ground?.speed ?? 1;

A tileset is a layer’s terrains in priority order (each drawn over the ones before it), each solid, oneWay or neither, and how each is drawn: the frames of its 6 shapes in a picture, turned into place; 15 frames by mask, as they are, for art lit from one side; or a colour, whose shapes are drawn in code. A terrain is drawn from the picture once each of its shapes, or masks, has a frame.

  • In code: resources.get('tilesets').define('island', starterTileset(32)). starterTileset is water, sand, grass and solid stone, in colours.
  • As assets: name.tileset.json files (TilesetFile: id, image, tileSize, terrains), made in the editor with New Tileset in the Assets panel and edited in the Tileset tab, which a double click on it, or Edit Tileset in its preview, opens beside the Scene. While it is open its terrains are a Terrains tab in the left pane, and while it is in front the Inspector shows the tileset (its picture and tile size), the terrain chosen there and that terrain’s frames. Its picture is a texture dragged from Assets onto Picture, or found by name in its picker; a tileset with no picture takes one dropped in the middle of its tab. The editor keeps tilesets.index.json beside them, and TileMap2DPlugin loads what it lists. An asset whose id a tileset in code has is left out.
  • A changed tileset is a new TilesetDef: what draws or collides compares it, so a change in the editor is drawn and collides at once, also in a game that is playing.
  • A tileset has at most 36 terrains, ids 0 to 35. An id once given is not given again by the editor, so cells painted with a removed terrain never become another.

A shape or mask may have several frames. The first is the one it needs; the others are, by the terrain’s frames:

  • Variants (the default): each drawn tile shows one, picked by its place, so a field of grass does not repeat one tile. weights gives one number for each frame by its place in the list (1 where not given, 0 never). The layer’s variantSeed picks them anew.
  • An animation (frames: 'animation'): every tile shows them in turn, frameMs each (200 when not given), in step, on the game’s clock: a paused game holds its frame, and each step moves it on.

Per terrain, cost is what crossing one of its cells costs a path (1 when not given), and data is the url of a preset (.preset.json) that dataAt gives. A file that uses any of these is written as version: 2; an editor that knows only version 1 refuses it rather than dropping them. The Inspector’s switch between 6 shapes, turned and 15 tiles keeps the frames of the way it leaves, in the terrain’s kept (never drawn), and gives them back on the switch back, after a reload too; a file with kept is written as version: 3, which an editor that knows only version 2 refuses rather than dropping them. The Inspector edits all of them while the Tileset tab is in front: Add Frame and Remove Frame on a shape, variants or an animation, a weight per frame or ms per frame, the cost and the data link. A tile clicked in the tab’s picture is given to the frame chosen there. Fill from a block, in the tab’s bar, gives a terrain all its frames from one click: on the top-left tile of a 4 × 4 block for 15 tiles, laid out so that tile m draws the corners of mask m (north-west 8, north-east 4, south-east 2, south-west 1; tile 0 is not used), or on the first of a row of five for 6 shapes (corner, edge, diagonal, inner corner, full). Under the picture, the preview draws a sample map of the whole tileset as a map draws it, every terrain together, and stripes each cell with a frame not given yet: it stays in sight while frames are given.

Trees, rocks and chests stand on cells as instances of a prefab. In the Tiles tab, choose a prefab in the map’s Prefabs palette: Paint then places one at the centre of each cell the brush passes, and Erase takes away those there. A cell that has one keeps it, and a stroke is one undo step. They go in the map’s Objects, a child of the map listed with its layers in the Hierarchy (TileObjects), so they move with the map, in the editor and in the game, and a collider on one stops bodies where it is drawn. A selected instance, or the Objects, is no part of what is painted: the tile tools and the Tiles tab give way to the scene view’s own. A prefab that is no longer in the Project stays chosen, and Paint says why it places nothing.

A scene made before this has its instances in a root of its own beside the map, “Tile Map · objects”. To bring them over, drag that row onto the map in the Hierarchy: each instance stays where it stands, and from then on the group is the map’s Objects and moves with it.

The palette holds the prefabs chosen for that map, each with its picture and how many of it stand on the map (×6). Add lists the Project’s prefabs by folder, and those defined in code under “In code”; type to find one by name, and press it to add it to the palette or take it off. Each is one undo step, and Add stays open until Done. The palette is kept with the map in the scene, as editor data the game never loads, so everyone in the Project sees the same one. A map that has prefabs on it and no palette yet starts with those prefabs; a new map starts empty. A prefab no longer in the Project leaves the palette until it is back.

A prefab can also be dragged from the Assets panel. While a tile tool is on the map, the cell under the pointer lights up; dropped there, one is placed in that cell as Paint places it, and the prefab joins the palette as the brush, in one undo step. Dropped on the palette, it is only added. Dropped anywhere else on the scene view, it is added where it lands, as any asset is.

In play, TileMapPhysicsPlugin makes the solid cells of each chunk into a few static boxes (TileBox), each a root entity in its chunk’s Scene, and makes them again when the chunk’s cells, place or tileSize change. Physics seals the faces where boxes touch, so a body meets a wall as one surface. Boxes are never in a scene file. Every solid box is on the default collision layer.

The one-way cells become one-way boxes in the same way, merged apart from the solid ones: solid only from above, so a body lands on a ledge and jumps up through it (see One-way platforms). Touching one-way boxes read as one floor, and a solid wall beside a ledge keeps its side. They are on the default layer too, unless the game gives them one of their own, which lets a body drop through a ledge, its mask without that bit for a moment, and still stand on solid ground:

// A startup system: one-way terrain on layer 2, which bodies take in their mask.
resources.get('tileMapPhysics').oneWayLayer = 1 << 1;

A map’s outside is open, unless its edgeMode is Empty and its outsideTerrainId is a solid terrain: then a ring of boxes one cell thick outside its edge keeps bodies in, and where the Project has @shell/spatial, flow-field paths too. Clamp and Wrap maps stay open; close one with solid cells along its edge.

Where a Project also has the Package @shell/spatial, its flow fields see every map, with nothing to write: a solid cell blocks them (a one-way cell does not), and a terrain’s cost costs that much to cross, as an obstacle or a terrain cost would. No entity is made for it, and a repaint in play is followed. A FlowFieldAgent goes to its FlowFieldTarget round the walls.

  • Set the grid’s cellSize to the map’s tileSize, in the Project’s settings (Configuration). The default is 64: a flow cell larger than a tile is blocked wherever a wall reaches into it, which closes a corridor one tile wide.
  • Keep the map inside the grid, which covers -2048 to 2048 on both axes by default, with the grid’s corner a whole number of tiles from the map’s, so that each flow cell is a cell of the map.
  • Paths are built in play, on profile 0.

generate runs each layer’s algorithm, or the algorithm given, with the map’s seed plus the layer’s: the same seed gives the same map. Given a layer, it runs on that layer alone; given a rect, it writes only those cells, and reads the cells around them. Each algorithm describes its settings (key, label, min, max, step, default), which generate takes by key. A setting of kind: 'terrain' is a terrain id of the layer’s tileset, or -1 for none, in place of a range. Four are registered:

NameMakesSettings
cellularAutomataCaves or islands of fill over emptyfillChance, iterations, fill, empty
noiseEvery terrain of the tileset by height, lowest firstfrequency, octaves, level<id> per terrain
roomsAndCorridorsRooms of floor joined by corridors, in walldug, roomWidth, roomHeight, corridorLength, floor, wall
randomWalkA path; nothing else changescover, walkers, turn, path

By default fill, floor and path are the layer’s baseTerrainId, empty is terrain 0, and wall is the tileset’s first solid terrain other than the floor, or else its last other terrain.

A cell is rolled by its place and the seed, so a region generated again matches the map around it. A game registers its own:

world.get('tilemapAlgorithms').register('stripes', {
generate: ({ width, height, baseTerrainId }) =>
Int32Array.from({ length: width * height }, (_, at) =>
Math.floor(at / width) % 4 === 0 ? baseTerrainId : 0,
),
});

The answer is a terrain id for each cell, row by row from the top, and is checked before any chunk changes.

The editor’s Agent works on maps with its tools, one undo step a call:

ToolWhat
tilemap_createNew Tile Map: a map of a tileset (the starter), its size and first layer, selected
tilemap_paintPaints rectangles or lists of cells with terrains, by name or id, on a map or a layer
tilemap_readThe terrain as rows of characters, a legend, the size, where cell 0, 0 is, the layers
tilemap_generateGenerate, from a seed, over the map, a layer or a rectangle, with settings
tilemap_placePlaces a prefab on cells, as the prefab brush does
write_tilesetMakes or changes a tileset asset, keeping its terrains’ ids; frames, cost and data

It adds a layer with world_spawn, a child of the map. Its guidance is the ecs-tilemap skill.