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:
| Package | What |
|---|---|
@shell/tilemap | The data: maps, layers, chunks, tilesets, the solver, generate. No Pixi |
@shell/tilemap-pixi | Draws every map, culled by chunk, in the game and the editor’s scene view |
@shell/tilemap-physics | Makes solid and one-way cells into static box colliders, in play |
A map is three kinds of entity:
TileMap:widthandheightin cells,tileSizein world units,seed,edgeModeandoutsideTerrainId(what is read, and drawn, outside it). ItsPositionis 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), andvariantSeed.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.
Layers
Section titled “Layers”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.
Painting in code
Section titled “Painting in code”resources.get('tilemaps') writes only the chunks it touches, and what is drawn and solid follows:
| Call | What |
|---|---|
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 linkconst speed = ground?.speed ?? 1;Tilesets
Section titled “Tilesets”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)).starterTilesetis water, sand, grass and solid stone, in colours. - As assets:
name.tileset.jsonfiles (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 keepstilesets.index.jsonbeside them, andTileMap2DPluginloads 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.
Several frames, cost and data
Section titled “Several frames, cost and data”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.
weightsgives one number for each frame by its place in the list (1 where not given, 0 never). The layer’svariantSeedpicks them anew. - An animation (
frames: 'animation'): every tile shows them in turn,frameMseach (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.
Things on cells
Section titled “Things on cells”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.
Collision
Section titled “Collision”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.
Paths round walls
Section titled “Paths round walls”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
cellSizeto the map’stileSize, 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
Section titled “Generate”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:
| Name | Makes | Settings |
|---|---|---|
cellularAutomata | Caves or islands of fill over empty | fillChance, iterations, fill, empty |
noise | Every terrain of the tileset by height, lowest first | frequency, octaves, level<id> per terrain |
roomsAndCorridors | Rooms of floor joined by corridors, in wall | dug, roomWidth, roomHeight, corridorLength, floor, wall |
randomWalk | A path; nothing else changes | cover, 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 Agent
Section titled “The Agent”The editor’s Agent works on maps with its tools, one undo step a call:
| Tool | What |
|---|---|
tilemap_create | New Tile Map: a map of a tileset (the starter), its size and first layer, selected |
tilemap_paint | Paints rectangles or lists of cells with terrains, by name or id, on a map or a layer |
tilemap_read | The terrain as rows of characters, a legend, the size, where cell 0, 0 is, the layers |
tilemap_generate | Generate, from a seed, over the map, a layer or a rectangle, with settings |
tilemap_place | Places a prefab on cells, as the prefab brush does |
write_tileset | Makes 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.