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::{Tilemap.new, create_tilemap, set_tile, …} 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
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"]}")