Tilemaps
Draw grids of tiles in one draw call with TilemapChunk and TilemapChunkTileData, load a tileset, change tiles at runtime, and rotate or mirror tiles.
On this page
A tilemap draws a grid of tiles from one tileset image. The engine's TilemapChunk draws a rectangular block of tiles as a single mesh in a single draw call, however many tiles it has, so a level made of a few chunks stays cheap. Large worlds are several chunks side by side.
Tilemaps are part of the 2D renderer (neo::sprite_render), which NEO's builds include. They run in the browser.
The pieces#
| Type | What it is |
|---|---|
TilemapChunk | The chunk: chunk_size (in tiles), tile_display_size (in world units), tileset (the image) and alpha_mode. |
TilemapChunkTileData | A Vec<Option<TileData>>, one entry per tile, row by row from the bottom-left. None is an empty tile. |
TileData | One tile: tileset_index, a color tint, visible and an orientation. |
TileOrientation | Rotation and mirroring of a tile. |
The tileset#
The tileset is an array texture: one image whose tiles are stacked as layers, each tile the same size. When you load it, tell the image loader how the image is divided with ImageArrayLayout:
use neo::image::{ImageArrayLayout, ImageLoaderSettings};
let tileset = asset_server
.load_builder()
.with_settings(|settings: &mut ImageLoaderSettings| {
// the image holds 4 tiles stacked vertically
settings.array_layout = Some(ImageArrayLayout::RowCount { rows: 4 });
})
.load("textures/array_texture.png");tileset_index picks the layer. The tile's size on screen is tile_display_size, independent of its size in the image.
Spawn a chunk#
use neo::{
prelude::*,
sprite_render::{TileData, TilemapChunk, TilemapChunkTileData},
};
fn spawn_level(mut commands: Commands, asset_server: Res<AssetServer>) {
let chunk_size = UVec2::new(32, 18);
let tiles: Vec<Option<TileData>> = (0..chunk_size.element_product())
.map(|i| Some(TileData::from_tileset_index((i % 4) as u16)))
.collect();
commands.spawn(Camera2d);
commands.spawn((
TilemapChunk {
chunk_size,
tile_display_size: UVec2::splat(16),
tileset: asset_server.load("textures/tileset.png"), // loaded as an array, see above
..default()
},
TilemapChunkTileData(tiles),
));
}The chunk is centred on its Transform. Move the entity to place it, and give neighbouring chunks transforms that are chunk_size * tile_display_size apart.
Change tiles at runtime#
TilemapChunkTileData derefs to its Vec, so edit entries in place. The chunk redraws the next frame.
fn break_tile(mut chunks: Query<(&TilemapChunk, &mut TilemapChunkTileData)>) {
for (chunk, mut data) in &mut chunks {
let (x, y) = (3, 4);
let index = (y * chunk.chunk_size.x + x) as usize;
data[index] = None; // now empty
}
}data.tile_data_from_tile_pos(chunk.chunk_size, UVec2::new(3, 4)) reads one tile. TilemapChunk itself is immutable: to change its size or tileset, insert a new TilemapChunk on the entity.
Tile rows count up from the bottom. If your level data is written top row first (as most editors export it), convert it with TilemapChunkTileData::from_y_down_tiles(chunk_size, data).
Put things on tiles#
chunk.calculate_tile_transform(UVec2::new(x, y)) returns the transform of a tile's centre, relative to the chunk. Use it to place a character, a pickup or a cursor on a tile, raising its Z so it draws on top:
let mut transform = chunk.calculate_tile_transform(UVec2::new(5, 6));
transform.translation.z = 1.0;
commands.spawn((Sprite::from_image(asset_server.load("chest.png")), transform));Rotate and mirror tiles#
Set TileData::orientation to reuse one tile in eight orientations: Default, Rotate90, Rotate180, Rotate270, MirrorH, MirrorHRotate90, MirrorHRotate180 and MirrorHRotate270. Rotation is counter-clockwise. TileOrientation::from_bools(mirror_h, mirror_v, mirror_d) builds one from mirror flags, which matches the flip bits map editors such as Tiled store.
Examples#
| Example | What it shows |
|---|---|
tilemap_chunk | A 64×64 chunk with random tiles, updated over time, and objects placed on tiles. |
tilemap_chunk_orientation | Every orientation, plus tints, transparency and hidden tiles. |
Run one from the engine core's workspace: cargo run --example tilemap_chunk.