TilemapAsset

Asset type for loading tilemap data from various formats (TMX, LDtk). Handles loading of tilemap files, external tilesets, and associated textures.

Supported formats:

• TMX (Tiled Map Editor): XML-based format with optional external TSX tilesets
• LDtk (Level Designer Toolkit): JSON-based format with modern features

The asset automatically:

• Parses tilemap data into a unified TilemapData structure
• Loads required tileset textures
• Handles external tileset references
• Supports hot-reloading when files change
• Manages texture density changes for different screen resolutions

Usage Example: #

// Load a TMX tilemap
assets.add(Tilemaps.LEVEL1);
assets.load();

// Access the tilemap data
var tilemapData = assets.tilemap(Tilemaps.LEVEL1).tilemapData;

// Create a visual from the data
var tilemap = new Tilemap();
tilemap.tilemapData = tilemapData;

Instance Members #

If the tilemap originates from an LDtk file, this contains the complete LDtk data structure. Provides access to:

• All levels in the project
• Entity instances
• Custom fields
• Generated tilemaps

This is null for non-LDtk tilemaps.

If the tilemap originates from a Tiled/TMX file, this contains the raw TMX data structure. Useful for accessing custom properties, object layers, or other TMX-specific features not converted to TilemapData.

This is null for non-TMX tilemaps.

The unified tilemap data that can be used with Ceramic's Tilemap visual. This is the primary output of the asset, containing layers, tilesets, and tile placement data in a format-agnostic structure.

For TMX files, this contains the first/main tilemap. For LDtk files, access individual level tilemaps through ldtkData.

Cleans up the tilemap asset and all associated data. Destroys:

• The TilemapData instance
• The LDtk data (if applicable)
• References to TMX data
• All loaded textures and sub-assets

Private Members #

Cache for external TSX tileset data loaded from separate files. Maps from tileset source path to raw XML content.

List of external LDtk level file paths for hot-reload monitoring.

Event when tmxMap field changes.

Event when ldtkData field changes.

Event when tilemapData field changes.

Loads a TMX (Tiled Map Editor) format tilemap. Handles:

1. Loading the main TMX file
2. Loading external TSX tilesets if referenced
3. Parsing the XML data into TmxMap structure
4. Converting to unified TilemapData
5. Loading all required textures

Loads external TSX tileset files referenced by the TMX map. TSX files allow sharing tilesets between multiple maps.

This method:

• Parses the TMX to find external tileset references
• Checks the cache for already-loaded TSX data
• Loads any missing TSX files
• Caches the results for future use

Adds a text asset for loading an external TSX tileset file.

Resolves raw TSX data from the cache by filename. Called by the parser when it encounters an external tileset reference.

Loads a texture from a source path, used by tileset loading.

This method:

• Checks if the texture is already loaded
• Creates an ImageAsset if needed
• Configures the asset (e.g., for filtering)
• Shares loaded textures with the owner Assets instance
• Sets NEAREST filter by default (pixel-perfect for tilemaps)

Loads an LDtk (Level Designer Toolkit) format tilemap project.

Handles:

1. Loading the main .ldtk JSON file
2. Loading external level files if the project uses them
3. Parsing the LDtk data structure
4. Loading tileset textures for all levels
5. Generating TilemapData for each level

The skip option in AssetOptions can exclude specific levels from loading.

Loads an external LDtk level file (.ldtkl). Used when LDtk projects are configured to save levels in separate files.

Handles texture density changes for responsive asset loading. Called when the screen density changes (e.g., moving between displays).

Checks and updates textures for the current screen density. Currently a no-op as tileset textures handle density changes themselves, but kept for potential future use.

Handles file change notifications for hot-reloading. Automatically reloads the tilemap when:

• The main tilemap file changes
• Any external level files change (LDtk)
• Any referenced tileset files change

Metadata #