name: tilemaps

description: "Use this skill when working with tilemaps in Phaser 4. Covers loading Tiled JSON maps, creating tilemap layers, tile collision, dynamic tiles, tile properties, and tilemap camera culling. Triggers on: Tilemap, Tiled, tilemap layer, tile collision, tile properties."

Tilemaps

Phaser Tilemaps render tile-based levels from Tiled JSON, CSV, or raw 2D arrays. A Tilemap holds parsed map data and provides methods to add tilesets, create layers, set collision, and query tiles. Layers (TilemapLayer or TilemapGPULayer) are the Game Objects that actually render tiles. Phaser supports orthogonal, isometric, hexagonal, and staggered maps.

Key source paths: src/tilemaps/Tilemap.js, src/tilemaps/TilemapLayer.js, src/tilemaps/TilemapGPULayer.js, src/tilemaps/TilemapLayerBase.js, src/tilemaps/Tile.js, src/tilemaps/Tileset.js, src/tilemaps/TilemapFactory.js, src/tilemaps/components/, src/tilemaps/parsers/tiled/

Related skills: ../loading-assets/SKILL.md, ../sprites-and-images/SKILL.md

Quick Start

class GameScene extends Phaser.Scene {
    preload() {
        // Load the Tiled JSON and the tileset image
        this.load.tilemapTiledJSON('map', 'assets/level1.json');
        this.load.image('tiles', 'assets/tilesheet.png');
    }

    create() {
        // Create the tilemap from cached JSON
        const map = this.add.tilemap('map');

        // Link the tileset image to the tileset name used in Tiled
        const tileset = map.addTilesetImage('tilesheet', 'tiles');

        // Create a layer - layerID must match the layer name in Tiled
        const ground = map.createLayer('Ground', tileset);

        // Enable collision on specific tile indexes
        ground.setCollision([1, 2, 3]);
    }
}

The flow is always: load JSON + image, create tilemap, add tileset image, create layer(s), set collision.

Core Concepts

Tilemap vs Layer

A Tilemap is a data container, not a display object. It stores parsed map data (layers, tilesets, objects) and provides methods that operate on them. A TilemapLayer or TilemapGPULayer is the actual Game Object added to the display list that renders tiles.

const map = this.add.tilemap('map');    // Data container (not rendered)
const layer = map.createLayer('Ground', tileset);  // Game Object (rendered)

this.add.tilemap(key) is a factory registered on GameObjectFactory. It delegates to ParseToTilemap which reads from the cache and returns a Tilemap instance.

Tilesets

A Tileset (src/tilemaps/Tileset.js) links a tileset name (from Tiled) to a loaded texture. It stores firstgid, tile dimensions, margin, and spacing.

// tilesetName: the name in Tiled's tileset panel
// key: the Phaser texture key (defaults to tilesetName if omitted)
const tileset = map.addTilesetImage('tilesetName', 'textureKey');

// Override tile dimensions, margin, and spacing if needed
const tileset = map.addTilesetImage('name', 'key', 16, 16, 1, 2);

addTilesetImage(tilesetName, key, tileWidth, tileHeight, tileMargin, tileSpacing, gid, tileOffset) - If the tileset name already exists in the parsed map data, it updates the existing Tileset object with the texture. If not (non-Tiled maps), it creates a new Tileset.

Important: The Phaser Tiled parser does not support "Collection of Images" tilesets. All tiles must be in a single tileset image per tileset.

The Tile Class

Each cell in a layer is a Tile object (src/tilemaps/Tile.js). Key properties:

• index - tile index in the tileset (-1 for empty)
• x, y - tile coordinates (in tiles, not pixels)
• pixelX, pixelY - pixel position relative to layer origin
• width, height - tile size in pixels
• properties - custom properties from Tiled (object)
• collideLeft, collideRight, collideUp, collideDown - per-edge collision flags
• faceLeft, faceRight, faceTop, faceBottom - interesting face flags for collision optimization
• collisionCallback - per-tile collision callback function
• tint - tint color value (default 0xffffff)
• tintMode - tint blend mode (default TintModes.MULTIPLY)
• rotation - rotation angle
• physics - object for physics-engine-specific data (e.g. bodies)
• alpha, visible, flipX, flipY - inherited from mixins

TilemapGPULayer (v4.0.0)

TilemapGPULayer is a high-performance WebGL-only alternative to TilemapLayer. It renders the entire layer as a single quad using a shader, making it almost entirely GPU-bound.

// Pass gpu: true as the 5th argument to createLayer
const layer = map.createLayer('Ground', tileset, 0, 0, true);

Capabilities:

• Single tileset per layer only (no multi-tileset)
• Max tilemap size: 4096x4096 tiles
• Max unique tile IDs: 2^23 (8,388,608)
• Supports tile flip and tile animation
• Orthographic maps only (no iso/hex/staggered)
• Smooth tile borders with LINEAR filtering (no seams)
• Sharp pixels with NEAREST filtering