tilemap
stableA 2D tile grid system with multi-layer support for building tile-based maps, levels, and grid worlds — with utilities for querying, filling, finding tiles, and pathfinding hints.
use plugin tilemap Plugin snippets can be edited in the Playground, but native capabilities are executed locally with the Zolo CLI.
Functions (17)
- Tilemap.new Create a new tilemap with given dimensions
- create_tilemap Free-function shorthand to create a Tilemap
- set_tile Set the tile ID at a position on a layer
- get_tile Get the tile ID at a position on a layer
- add_layer Add a new empty layer to the tilemap
- layer_count Return the number of layers
- width Return the tilemap width in tiles
- height Return the tilemap height in tiles
- fill_layer Fill an entire layer with one tile ID
- clear_layer Reset an entire layer to tile ID 0
- remove_layer Remove a layer by index
- fill_rect Fill a rectangular region with a tile ID
- find_tile Find all positions of a given tile ID
- count_tile Count occurrences of a tile ID in a layer
- is_walkable Check if a cell is empty (tile ID 0)
- resize Resize the map, preserving existing tile data
- to_table Export the whole tilemap as a plain table
From import to result
- 01Import only what you use
- 02Copy the smallest example
- 03Run it with the Zolo CLI
Create a new tilemap with given dimensions
Creates a new tilemap handle with the given tile dimensions. The map starts with one layer where all tiles are set to 0. Layer indices are 0-based.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(32, 24)
print("Map created: {map.width()} x {map.height()}")Free-function shorthand to create a Tilemap
Free-function alias for Tilemap.new. Use this form when you prefer free function style.
use plugin tilemap::{create_tilemap}
let map = create_tilemap(20, 15)Set the tile ID at a position on a layer
Sets the tile at position (x, y) on the given layer. Layer and coordinates are validated; an error is raised if they are out of bounds.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.set_tile(0, 3, 4, 5)Get the tile ID at a position on a layer
Returns the tile ID stored at position (x, y) on the specified layer.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.set_tile(0, 2, 2, 42)
let id = map.get_tile(0, 2, 2)
print("Tile ID: {id}")Add a new empty layer to the tilemap
Appends a new empty layer (all tile IDs set to 0) and returns the index of the newly created layer.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(16, 16)
let layer_idx = map.add_layer()
print("New layer at index {layer_idx}")Return the number of layers
Returns the total number of layers currently in the tilemap.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(8, 8)
map.add_layer()
print("Layers: {map.layer_count()}")Return the tilemap width in tiles
Returns the width of the tilemap in tile units.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(40, 30)
print("Width: {map.width()}")Return the tilemap height in tiles
Returns the height of the tilemap in tile units.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(40, 30)
print("Height: {map.height()}")Fill an entire layer with one tile ID
Sets every tile in the specified layer to tile_id. Useful for initializing a floor or background layer.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(20, 20)
map.fill_layer(0, 1)Reset an entire layer to tile ID 0
Resets every tile in the layer to 0 (empty). Equivalent to fill_layer(layer, 0).
use plugin tilemap::{Tilemap}
let map = Tilemap.new(20, 20)
map.fill_layer(0, 3)
map.clear_layer(0)Remove a layer by index
Removes a layer by index. The last remaining layer cannot be removed. Subsequent layers shift down by one.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.add_layer()
map.remove_layer(1)Fill a rectangular region with a tile ID
Fills a rectangular region of tiles with tile_id. Cells outside the map bounds are silently skipped.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(30, 20)
map.fill_rect(0, 5, 5, 10, 8, 2)Find all positions of a given tile ID
Returns a list of {x, y} tables for every cell in the layer that contains tile_id. The list is indexed starting at 1.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(5, 5)
map.set_tile(0, 1, 2, 9)
map.set_tile(0, 3, 4, 9)
let positions = map.find_tile(0, 9)Count occurrences of a tile ID in a layer
Counts how many cells on the layer contain the given tile_id.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.fill_rect(0, 0, 0, 5, 5, 7)
let n = map.count_tile(0, 7)
print("Found {n} tiles")Check if a cell is empty (tile ID 0)
Returns true if the tile at (x, y) is 0 (empty). Tile ID 0 is the walkability marker — any non-zero tile ID is considered blocking.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.set_tile(0, 2, 3, 1)
print(map.is_walkable(0, 2, 3))
print(map.is_walkable(0, 5, 5))Resize the map, preserving existing tile data
Resizes the tilemap to new dimensions. Existing tile data is preserved for cells that still fit; new cells are initialized to 0. All layers are resized simultaneously.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(10, 10)
map.fill_layer(0, 1)
map.resize(20, 20)Export the whole tilemap as a plain table
Exports the tilemap as a plain table with keys width, height, and layers. Each layer is an indexed list of tile IDs in row-major order. Useful for serialization.
use plugin tilemap::{Tilemap}
let map = Tilemap.new(4, 3)
map.set_tile(0, 1, 1, 5)
let data = map.to_table()
print("Width: {data["width"]}, Layers: {data["layers"]}")