tilemapplugin

A tiled level from a file: the questions a rule asks of it, and drawing it on render2d.

#Putting it in a scene

List it before render2d. The scene's sim lists the tilemap kind from #plugins/tilemap/tilemap.sim.ts, and the scene has one { "is": "tilemap" } actor, which carries the cells rules have changed. The map file is a tilemap entry of the loader catalogue, with preload so a rule has it on the first step.

"plugins": ["loader", "scenemanager", "player", "tilemap", "render2d"],
"world": {
  "loader": { "assets": { "level1": { "type": "tilemap", "url": "/games/mygame/assets/level1.tmj", "preload": true, "nearest": true } } },
  "tilemap": { "file": "level1" }
},
"actors": [{ "is": "tilemap" }],
"prefabs": {
  "tilemap": { "edits": {} }
}

render2d's ground must lay cells out as Tiled does, or the page throws: [[w, 0], [0, h]] for an orthogonal map of w × h pixel tiles, and [[w/2, h/2], [-w/2, h/2]] for an isometric one.

#Properties

Read from world.tilemap.

.file : string

The loader catalogue name of the map, a tilemap entry. A rule reads the map through the loader with this name and hands it to the questions below. With nearest on the entry, every tile is drawn on whole pixels.

#The row

#Drawing

Each tile layer and image layer is drawn on the render2d layer its Tiled name names, in the map's order, with its opacity and tint. Object layers and hidden layers are not drawn, and render2d is asked for no layer of their names, so a huge layer that only says where things may walk costs the page nothing.

A changed edit redraws only its cell. When the map or one of its tilesets is written while the game runs, the whole map is drawn again.

#Methods

From #plugins/tilemap/tilemap.sim.ts. Each takes the map the loader read and the row's edits. A point is [x, y] in cells, x along a row and y down the rows; cell [c, r] is the square from [c, r] to [c + 1, r + 1], moved by its layer's offset. A box is { x, y, w, h }, its top left and size in cells.

Asking about tiles

tileAt( map, edits, layer, c, r ) : number

The gid of a cell of a tile layer, 0 for none.

overlaps( map, edits, box ) : { layer, cell, tile, type }[]

Every tile of every tile layer, visible or not, with or without collision, whose cell the box overlaps. type is the tile's Tiled type, '' when it has none.

solidAt( map, edits, box ) : boolean

Whether any collision shape, one-way ones aside, reaches into the box by more than 10⁻⁹ cells, so a thing put there would stand inside the ground or a wall. A box resting against a shape is clear of it.

shapes( map, edits, box ) : { pts, oneway, cell, tile }[]

Every collision shape of every tile whose cell the box overlaps, its points in the world going clockwise, for handing the level's ground to a physics world.

objects( map, layer? ) : TiledObject[]

The objects of the map's object layers, or of the ones named layer, which must exist.

tileOfType( map, type ) : number

The first gid, by tileset and then by id, whose Tiled type is type, for a rule that writes such a tile into edits. Throws when there is none.

Platform movement

sweep( map, edits, box, axis, to, solids = [] ) : { box, hits }

Moves a box along x (axis 0) or y (1) to to, its new x or y, against the collision shapes of every tile layer, visible or not, and the solids, boxes from rows such as a moving platform. It returns the box where it stopped and one hit for each thing it touched.

A tile's shapes are its Tiled collision rectangles and convex polygons, flipped with the cell. A shape whose type is top is one-way. In an isometric map a tile with any shape blocks its whole cell, one-way if all its shapes are.

• A box stands on its feet, the middle of its bottom edge. A slope of 45° or gentler carries it only under its feet, so its lower corner sinks into the slope, and it walks off a ledge when its feet do.
• Moving down, it lands on what its feet meet, a one-way shape only when the shape's top was at or under its feet.
• Moving up, its top meets the underside of anything but a one-way shape.
• Moving along x, it steps up onto anything no higher than half its width above its feet, such as a 45° slope, and slides along walls without catching on the seams between tiles. Walking down a slope, it stays on it.
• A box that starts inside a shape moves out of it freely; nothing pushes it out.

Movement cell by cell

For a top-down game, a mover is a circle of radius cells at pos [x, y].

blocked( map, edits, c, r ) : boolean

Whether cell [c, r] stops a mover: outside a map of fixed size, with no tile on any tile layer, or with a tile with collision on any. A tile layer offset by part of a cell throws.

slide( map, edits, pos, axis, to, radius, solids = [] ) : number

Where a mover going along x (0) or y (1) toward to stops against blocked cells and the solids, boxes of rows in the way such as a crate, a door or another mover. Moving along x and then along y, each stopped, slides a mover along a wall it hits slantwise and round a solid's corner.

clear( map, edits, pos, radius, solids = [] ) : boolean

Whether a mover at pos stands clear of every blocked cell and every solid, so a thing put down there is not in a wall, off the floor or in another thing. A mover a stop left touching a cell is clear of it.

#Used by

• nav
  Takes tilemap's blocked as the map it finds ways through.
• mapgen
  Writes maps tilemap loads, blocking where tilemap reads them blocking.

#In the guide