Tilemap

Tilemap :: # (opaque)

Tiled TMX data, tileset drawing, and grid queries.

load_tmx! waits and is legal only in init! or a task. Bind every parsed tileset to a loaded texture with Builder, then retain the built Tilemap in the model. Drawing requires Draw.Frame and is legal only in render!.

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

build refuses unbound tilesets. layer_role and object_role attach application-defined meanings for role-based drawing and queries.

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

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 test the app's real update! from an expect. Drawing it draws nothing, which is what having no layers means.

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.

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.

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

Parse a Tiled TMX map from an asset store.

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 from the same store, so a map spread across several files parks once per file and parses in between. A reference that would leave the store is PathInvalid.

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.