NEOLearn

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.

Updated October 20, 2026

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#

TypeWhat it is
TilemapChunkThe chunk: chunk_size (in tiles), tile_display_size (in world units), tileset (the image) and alpha_mode.
TilemapChunkTileDataA Vec<Option<TileData>>, one entry per tile, row by row from the bottom-left. None is an empty tile.
TileDataOne tile: tileset_index, a color tint, visible and an orientation.
TileOrientationRotation 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:

Rust
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#

src/level.rs
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.

Rust
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:

Rust
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#

ExampleWhat it shows
tilemap_chunkA 64×64 chunk with random tiles, updated over time, and objects placed on tiles.
tilemap_chunk_orientationEvery orientation, plus tints, transparency and hidden tiles.

Run one from the engine core's workspace: cargo run --example tilemap_chunk.

Next steps#