Tilemap

Tilemap :: # (opaque)

Tiled TMX data, tileset drawing, and grid queries.

Parse a map with load_tmx! in init!, bind its tilesets to loaded textures, and keep the built Tilemap in the model. Parsing reads files, so load_tmx! waits: it is legal in init!, where it blocks startup, and in tasks, where it parks the task, and refused in update! and render!. To swap levels while the app is running, call it inside Task.spawn! and build the Tilemap from the map its message carries. Every draw_*! here takes a Draw.Frame and is legal in render! only.

raw = Tilemap.load_tmx!("assets/level.tmx")?
tilemap = Tilemap.from_raw(raw)
    .with_origin({ x: 0, y: 0 })
    .with_tileset_texture(1, tiles)
    .build()?

tilemap.draw_all!(frame)

The builder is where a parsed map becomes a drawable one. Tiled records a tileset by its image path; with_tileset_texture says which loaded texture each first GID means, and build refuses a map with a tileset left unbound rather than drawing it blank. layer_role and object_role attach the app's own meaning -- which layers are solid, which objects are spawns -- so the rest of the app asks about roles instead of about layer names.

Grid queries and coordinate conversions are pure, so an app can use them from update! for collision and picking.

Signatures here name TilemapRawMap, TilemapRawObject, TilemapBuilder and their siblings. Those are module-private nominals, one per public alias; the names to write are the short ones on this page -- Tilemap.RawMap, Tilemap.RawObject, Tilemap.Builder. A nominal has to be declared outside the module object to be aliased inside it, which is why the two spellings exist.

empty_raw_map : TilemapRawMap

Empty parsed map value, useful as a deliberate fallback.

empty : Tilemap

Empty configured tilemap, useful when an optional map fails to load. Unlike building empty_raw_map, this value cannot fail validation.

It is also the resource-free value for pure tests, and needs no separate stub: a tilemap holds its textures in render_tilesets, and this one has none. Put it in a model to reach the app's real update! from an expect. Drawing it draws nothing, which is what having no layers means.

load_tmx! : Str => Try(TilemapRawMap, [NotFound, ReadFailed, ParseFailed, Unsupported, ..])

Parse a Tiled TMX map.

The returned data is an allocation-efficient set of flat lists with index ranges for nested properties, objects, and tile data.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!. A map is more than one file: an external tileset is read the same way, so a map spread across several files parks once per file and parses in between.

from_raw : TilemapRawMap -> TilemapBuilder

Begin configuring a drawable and queryable tilemap from parsed TMX data.

raw_map : Tilemap -> TilemapRawMap

Access the parsed flat-map data backing a configured tilemap.

layer_role_for : Tilemap, TilemapRawLayer -> TilemapLayerRole

Resolve a layer's configured semantic role; unmatched layers are drawn.

object_role_for : Tilemap, TilemapRawObject -> TilemapObjectRole

Resolve an object's configured semantic role; unmatched objects are unknown.

objects : Tilemap -> List(TilemapRawObject)

Return every parsed object in source order.

objects_named : Tilemap, Str -> List(TilemapRawObject)

Return objects whose Tiled name matches exactly.

objects_typed : Tilemap, Str -> List(TilemapRawObject)

Return objects whose Tiled type matches exactly.

objects_with_role : Tilemap, TilemapObjectRole -> List(TilemapRawObject)

Return objects matching a configured semantic role.

first_object : Tilemap, TilemapObjectRole -> Try(TilemapRawObject, [NotFound, ..])

Return the first object matching a configured semantic role.

object_center : TilemapRawObject -> Vec2

Return an object's center in map-local coordinates.

object_rect : TilemapRawObject -> Rect

Return an object's bounding rectangle in map-local coordinates.

object_circle : TilemapRawObject -> Circle

Approximate an object as a circle centered in its bounds.

object_world_center : Tilemap, TilemapRawObject -> Vec2

Return an object's center translated by the tilemap origin.

object_world_rect : Tilemap, TilemapRawObject -> Rect

Return an object's bounds translated by the tilemap origin.

object_world_circle : Tilemap, TilemapRawObject -> Circle

Return an object's circle translated by the tilemap origin.

property_named : TilemapRawMap, U64, U64, Str -> Try(TilemapRawProperty, [NotFound, ..])

Look up a property within an explicit flat-list range.

object_property : TilemapRawMap, TilemapRawObject, Str -> Try(TilemapRawProperty, [NotFound, ..])

Look up a property attached to an object.

layer_property : TilemapRawMap, TilemapRawLayer, Str -> Try(TilemapRawProperty, [NotFound, ..])

Look up a property attached to a layer.

property_str : TilemapRawMap, TilemapRawObject, Str, Str -> Str

Read an object's string property, or return the supplied default.

property_f32 : TilemapRawMap, TilemapRawObject, Str, F32 -> F32

Read an object's numeric property, or return the supplied default.

property_i64 : TilemapRawMap, TilemapRawObject, Str, I64 -> I64

Read an object's integer property, or return the supplied default.

property_bool : TilemapRawMap, TilemapRawObject, Str, Bool -> Bool

Read an object's boolean property, or return the supplied default.

cell_at_world : Tilemap, Vec2 -> Try(TilemapCell, [OutOfBounds, ..])

Convert a world-space position to a map cell, accounting for map origin.

cell_range_for_world_rect : Tilemap, Rect -> Try(TilemapCellRange, [OutOfBounds, ..])

Return the inclusive cell range overlapping a world-space rectangle's half-open area. The arithmetic is O(1), allocation-free, and clamps the range to map bounds.

world_rect_for_cell : Tilemap, TilemapCell -> Rect

Return the world-space rectangle covered by a map cell.

gid_at : Tilemap, Str, TilemapCell -> Try(U64, [NotFound, OutOfBounds, ..])

Read the cleaned tile GID at a named layer and cell.

solid_cell : Tilemap, TilemapCell -> Bool

Whether any layer configured as solid contains a tile in this cell.

solid_at_world : Tilemap, Vec2 -> Bool

Whether a world-space point falls in a solid cell.

circle_touches_solid : Tilemap, Circle -> Bool

Whether a world-space circle overlaps any configured solid tile.

draw_layer! : Tilemap, Frame, Str => {  }

Draw one named visible layer without camera culling.

Legal in render! only. So is every other draw_*! in this module.

draw_layer_in! : Tilemap, Frame, Str, Rect => {  }

Draw only cells intersecting world_view. This is the preferred hot path for maps larger than the viewport. One hosted effect draws the complete selected range; no per-tile effect or temporary List is created.

Legal in render! only.

draw_layers! : Tilemap, Frame, TilemapDrawRole => {  }

Draw every visible layer configured with the Drawn role.

Legal in render! only.

draw_layers_in! : Tilemap, Frame, TilemapDrawRole, Rect => {  }

Draw visible configured layers culled to a world-space viewport.

Legal in render! only.

draw_all! : Tilemap, Frame => {  }

Draw every visible tile layer, regardless of configured role.

Legal in render! only.

draw_all_in! : Tilemap, Frame, Rect => {  }

Draw every visible tile layer culled to a world-space viewport.

Legal in render! only.

viewport_for_camera : Camera2D, Vec2 -> Rect

Compute the world-space axis-aligned bounds visible through a 2D camera, including non-centered offsets and rotation. This is pure and allocates no temporary list.

draw_all_for_camera! : Tilemap, Frame, Camera2D, Vec2 => {  }

Convenience form of draw_all_in! for camera-driven scenes.

Legal in render! only.

flip_for_gid : U64 -> TilemapFlip

Decode Tiled horizontal, vertical, and diagonal flip flags.

clean_gid : U64 -> U64

Remove Tiled flip flags from a packed global tile ID.

RawMap : TilemapRawMap

Parsed TMX data stored in flat lists to avoid a heap allocation per nested item.

RawLayer : TilemapRawLayer

Parsed tile-layer metadata and a range into the map GID list.

RawObject : TilemapRawObject

Parsed Tiled object metadata and ranges into point and property lists.

RawProperty : TilemapRawProperty

Parsed Tiled property with tagged scalar storage.

RawTileset : TilemapRawTileset

Parsed tileset metadata and its property range.

RawPoint : TilemapRawPoint

Parsed object point in map-local coordinates.

Cell : TilemapCell

Zero-based tile column and row.

CellRange : TilemapCellRange

Inclusive rectangular range of map cells.

Flip : TilemapFlip

Decoded Tiled tile-transform flags.

ResolvedTileset : TilemapResolvedTileset

A tileset with its texture binding resolved, as build left it.

LayerRole : TilemapLayerRole

Application-level behavior assigned to a named layer: Drawn, Solid, or Hidden.

DrawRole : TilemapDrawRole

The two layer roles ordinary role-based drawing accepts. Hidden layers are drawn only by name.

ObjectRole : TilemapObjectRole

Application-level behavior assigned to an object name or type.

Builder : TilemapBuilder

Immutable tilemap configuration builder, from from_raw.

TilemapBuilder in the signature is the module-private nominal this aliases; Tilemap.Builder is the name to write.