Tilemaps and parallax¶
The tilemap plugin (src/rtype/plugins/tilemap/, rtype::plugins::tilemap) draws levels made in
Tiled and parallax backgrounds. It knows nothing of the renderer: it pushes the sprites
of the tiles the camera shows to the backend's SpriteQueue, which the GraphicsPlugin draws with the sprite entities.
The game adds it, after GraphicsPlugin, which it requires.
Loading a map¶
void spawnLevel(ecs::ResMut<TilemapAssets> maps, ecs::Commands& commands) {
const AssetId level = maps->load("assets/levels/space.tmj");
spawnTilemap(commands, *maps, level, TilemapPlacement{.position = {0.0F, 0.0F}, .scale = {2.0F, 2.0F}});
}
TilemapAssets(the resourcertype.TilemapAssets) keeps the maps byAssetId, asTextureAssetskeeps the textures.load()reads a map at once, on every side; one that cannot be read is recorded as failed, with the reason, which is printed: a missing map does not stop the game. Its images are handed toTextureAssetsby the client.spawnTilemap()spawns one entity per layer, bottom first: aTransform(the map's position plus the layer's offset), aTilemapLayer(the map, the layer's index and its draw layer,firstDrawLayerplus its index) and aParallax. Draw layers are theSpriteRenderer::layerof sprites: a map at -100 is under every sprite at 0.
What is read from Tiled¶
Save the map as JSON (.tmj). The plugin reads an orthogonal map, finite or infinite:
| Tiled | Read as |
|---|---|
Tilesets, embedded or external (.tsj) |
One image cut into tiles: tile size, columns, spacing, margin, tile offset. A tileset of separate images is rejected. |
| Tile layers | Their tiles, in Tiled's CSV layer format (base64 is rejected), with the flip flags (horizontal, vertical, diagonal). A tile bigger than the grid sits on the bottom-left corner of its cell, as in Tiled. |
| Image layers | Their image, repeated along X and/or Y (repeatx, repeaty) to fill the view. |
| Group layers | Flattened into their layers: offsets added, parallax factors, opacities and tints multiplied, names prefixed (group/layer). |
| Every layer | offsetx/offsety, parallaxx/parallaxy, opacity, tintcolor, visible. |
| The map | tilewidth/tileheight, parallaxoriginx/parallaxoriginy. |
Custom float properties scrollx, scrolly |
An extension of this plugin: pixels per second the layer scrolls on its own. |
Object layers are skipped. Image and tileset paths are relative to the file that names them.
Drawing¶
Tile layers are stored in chunks of 16x16 cells, only where there are tiles. Each frame, the Render system
rtype.Tilemap.Draw skips the chunks outside the VisibleArea (what the camera shows, recorded by the
GraphicsPlugin) and pushes one sprite per tile of the others: a level of any length costs the tiles on screen. All the
tiles of a tileset share its texture, so they are drawn in one batch per layer.
An image layer is one sprite. Repeated, it is still one sprite: its source rectangle spans as many copies as the view
needs, and the texture, asked for with TextureDesc::repeat, tiles them.
Parallax¶
Parallax moves an entity slower or faster than the camera, and scrolls it on its own. Each frame, the Render system
rtype.Tilemap.Parallax (before the camera) sets the entity's GlobalTransform to its Transform plus:
(camera - origin) * (1 - factor): a factor of 0 stays on screen with the camera, 1 moves with the world, between the two moves slower (far away), above 1 faster (a foreground).originis where the camera sees the entity at itsTransform;spawnTilemap()puts it at the map's parallax origin.scrolled, which grows byscrollunits per second.
It works on any entity, a sprite as well as a tilemap layer. It is a visual effect: it runs on the client only, after
gameplay and the PostUpdate systems, so physics and audio see the entity at its Transform.
From scripts¶
The TilemapPlugin registers two engine calls:
rtype.tilemap.load { path } returns the map's id, and rtype.tilemap.spawn { map, position, scale, firstDrawLayer }
spawns its layers (spawnTilemap()) and returns how many it spawned.
In the repository¶
assets/levels/space.tmj: a 200x10 level over the space background ofassets/backgrounds/space/(CC0, by ansimuz): three repeating layers and two planets at their own parallax speed, a group, and a layer of tiles cut from the same images (one tileset embedded,far-planets.tsjexternal), some of them flipped.assets/levels/space-background.tmj: the three repeating layers alone, each scrolling left at its own speed (scrollx): the background of the engine's duel.examples/plugins/tilemap: the camera flies overspace.tmj(xmake f --tilemap=y && xmake run tilemap).