TilemapData

Unified tilemap data structure that represents a tile-based map. This format is inspired by the Tiled TMX format but provides a format-agnostic representation that can be populated from various sources.

Key features:

• Multi-layer support with different tile sizes per layer
• Multiple tilesets with automatic GID resolution
• Support for various map orientations (orthogonal, isometric, etc.)
• Observable properties for reactive updates
• Serializable for save/load functionality

Ceramic's built-in tilemap visual only supports orthogonal maps, but this data model supports:

• Orthogonal maps (standard grid-based)
• Isometric maps (diamond-shaped tiles)
• Hexagonal maps (honeycomb pattern)
• Staggered maps (offset rows/columns)

This is a Model class from the Tracker framework, providing:

• Automatic serialization support
• Observable properties with @observe
• Computed properties with @compute
• Change notifications

Reference: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/

Instance Members #

Reference to the LDtk level this tilemap data was generated from. Only set when the tilemap originates from an LDtk file. Provides access to the original LDtk-specific data.

Optional name identifier for this tilemap. Useful for debugging and when managing multiple tilemaps.

Map orientation type that determines how tiles are arranged and rendered.

• ORTHOGONAL: Standard grid layout (most common)
• ISOMETRIC: Diamond-shaped tiles for 2.5D appearance
• STAGGERED: Offset rows or columns
• HEXAGONAL: Hexagon-shaped tiles

Note: Currently only ORTHOGONAL is fully supported by the renderer.

Total width of the map in pixels. This is typically calculated as: columns × tileWidth

Total height of the map in pixels. This is typically calculated as: rows × tileHeight

Determines the order in which tiles are rendered within each layer. Affects which tiles appear on top when they overlap.

• RIGHT_DOWN: Left to right, top to bottom (default)
• RIGHT_UP: Left to right, bottom to top
• LEFT_DOWN: Right to left, top to bottom
• LEFT_UP: Right to left, bottom to top

For hexagonal maps only: The length of the hex tile edge in pixels. This determines the size of the hexagon sides. Set to -1 for non-hexagonal maps.

For staggered and hexagonal maps: Which axis has alternating offsets.

• AXIS_X: Alternating columns are offset (vertical hex)
• AXIS_Y: Alternating rows are offset (horizontal hex)

For staggered and hexagonal maps: Which indices are shifted.

• ODD: Odd rows/columns are offset (1, 3, 5...)
• EVEN: Even rows/columns are offset (0, 2, 4...)

Background color displayed behind all map layers. Includes alpha channel for transparency. Default is fully transparent (alpha = 0).

Computes the maximum tile width across all layers. Useful for allocating buffers or determining map bounds.

Some maps may have layers with different tile sizes (e.g., detail layers with smaller tiles).

Computes the maximum tile height across all layers. Useful for allocating buffers or determining map bounds.

Some maps may have layers with different tile sizes (e.g., detail layers with smaller tiles).

Array of tilesets used by this map. Tilesets define the graphics and properties for tiles.

Ordered by firstGid (ascending) for efficient GID lookups. Each tileset handles a range of global tile IDs (GIDs).

Array of layers that make up the map. Layers are rendered in array order (first = bottom).

Each layer can be:

• Tile layer: Grid of tile GIDs
• Object layer: Positioned objects (future)
• Image layer: Single background image (future)

Reference to the TilemapAsset that loaded this data. When the asset is destroyed, this data is also destroyed. Set automatically by TilemapAsset during loading.

Finds the tileset that contains the given global tile ID (GID). GIDs are globally unique across all tilesets in the map.

Retrieves a layer by its name. Layer names should be unique within a tilemap.

Sets the texture filtering mode for all tileset textures.

Common values:

• NEAREST: Pixel-perfect rendering (recommended for pixel art)
• LINEAR: Smooth/blurred rendering

Convenience method to set both width and height at once.

Retrieves a tileset by its name. Tileset names should be unique within a tilemap.

Private Members #

Event when ldtkLevel field changes.

Event when name field changes.

Event when orientation field changes.

Event when width field changes.

Event when height field changes.

Event when renderOrder field changes.

Event when hexSideLength field changes.

Event when staggerAxis field changes.

Event when staggerIndex field changes.

Event when backgroundColor field changes.

Event when maxTileWidth field changes.

Event when maxTileHeight field changes.

Event when tilesets field changes.

Event when layers field changes.

Returns a string representation of the tilemap data for debugging. Includes all major properties but excludes detailed tile data.

Metadata #