Tilemap

A visual component that renders tilemap data composed of multiple layers. Tilemaps are grid-based maps commonly used in 2D games for rendering backgrounds, levels, and collision data.

Features:

• Multi-layer rendering with depth control
• Tile clipping for culling optimization
• Collision detection support (with arcade plugin)
• Automatic layer management from TilemapData
• Per-layer and per-tilemap scaling

Currently only supports ORTHOGONAL tile orientation. Other orientations like isometric or hexagonal are not implemented.

Usage Example: #

var tilemap = new Tilemap();
tilemap.tilemapData = assets.tilemap("level1").tilemapData;
tilemap.pos(0, 0);
scene.add(tilemap);

// Access specific layer
var collisionLayer = tilemap.layer("collision");

// Enable collision detection (arcade plugin)
tilemap.collidableLayers = ["collision", "walls"];

Instance Members #

Array of layer names that should be used for collision detection. Only layers whose names are in this array will participate in physics collisions when using the arcade physics plugin.

Example: ["collision", "walls", "platforms"]

Computed array of TilemapLayer instances that are marked as collidable. Automatically updated when collidableLayers changes.

Internal flag indicating collidable layers need recomputation.

When true, physics bodies are destroyed for tiles that are no longer in collidable layers. This frees memory but has a performance cost.

When false, physics bodies are kept even when layers become non-collidable, trading memory for performance.

Checks if there is a tile at the given world position.

Checks if collision should occur at the given world position. Only checks layers marked as collidable.

Controls pixel rounding for tile positioning.

Values:

• 0: No rounding (tiles can be positioned at sub-pixel positions)
• 1: Round to nearest pixel (default, prevents tile seams)
• 2+: Round to nearest multiple of this value

Pixel rounding helps prevent visual artifacts like gaps between tiles when rendering at non-integer positions or scales.

The tilemap data to render. Contains layer information, tilesets, and tile placement data. Setting this property triggers a complete rebuild of the tilemap's visual layers.

When null, the tilemap renders nothing and has zero size.

Global scale factor applied to all tiles in the tilemap. This scales the visual size of tiles without affecting the logical grid dimensions.

Special values:

• 1.0: Normal size (default)
• -1: Disables scale propagation to layers

This is useful for implementing zoom or creating tilemaps with different visual scales while maintaining the same data.

X coordinate (in tiles) where tile clipping begins. Tiles outside the clipping rectangle are not rendered.

Set to -1 to disable clipping on this axis (default). Used for culling optimization in large tilemaps.

Y coordinate (in tiles) where tile clipping begins. Tiles outside the clipping rectangle are not rendered.

Set to -1 to disable clipping on this axis (default). Used for culling optimization in large tilemaps.

Width (in tiles) of the clipping rectangle. Only tiles within this width from clipTilesX are rendered.

Set to -1 to disable width clipping (default). Used for culling optimization in large tilemaps.

Height (in tiles) of the clipping rectangle. Only tiles within this height from clipTilesY are rendered.

Set to -1 to disable height clipping (default). Used for culling optimization in large tilemaps.

Array of TilemapLayer visuals managed by this tilemap. Layers are automatically created, updated, and destroyed based on the tilemapData. Direct manipulation is not recommended.

Use the layer(name) method to access specific layers by name.

Computes the tilemap's visual content based on its data. This method:

• Sets the tilemap size from data dimensions
• Applies background color if specified
• Creates or updates layer visuals
• Removes unused layers

Sets the tile clipping rectangle in a single call. Tiles outside this rectangle are not rendered, improving performance for large tilemaps where only a portion is visible.

Retrieves a layer by its name as defined in the tilemap data. Returns null if no layer with the given name exists.

Private Members #

Event fired when a layer visual is created for this tilemap. Useful for customizing layer properties immediately after creation.

Creates, updates, or removes layer visuals to match the tilemap data. Ensures each data layer has a corresponding visual layer and removes any visual layers that no longer have data.

Fires the createLayer event for newly created layers.

Computes which layers should be used for collision detection. Called internally by the arcade physics system when needed.

Matches layer names in collidableLayers array with actual layers and marks them as collidable. Optionally cleans up physics bodies on layers that are no longer collidable.

Metadata #