tilemaps

Tilemaps

Phaser Tilemaps renderiza niveles basados en mosaicos a partir de archivos JSON de Tiled, CSV o matrices 2D sin procesar. Un Tilemap contiene los datos del mapa analizados y ofrece métodos para añadir conjuntos de mosaicos, crear capas, configurar colisiones y consultar mosaicos. Las capas (TilemapLayer o TilemapGPULayer) son los objetos de juego que se encargan de renderizar los mosaicos. Phaser admite mapas ortogonales, isométricos, hexagonales y escalonados.

Rutas clave del código fuente: 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/ Habilidades relacionadas: ../loading-assets/SKILL.md, ../sprites-and-images/SKILL.md

Inicio rápido

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]);
    }
}

El proceso es siempre el mismo: cargar el JSON y la imagen, crear el mapa de mosaicos, añadir la imagen del conjunto de mosaicos, crear capas y configurar la colisión.

Conceptos básicos

Mapa de mosaicos frente a capa

Un Tilemap es un contenedor de datos, no un objeto de visualización. Almacena datos de mapa analizados (capas, conjuntos de mosaicos, objetos) y proporciona métodos que operan sobre ellos. Una TilemapLayer o TilemapGPULayer es el objeto de juego real añadido a la lista de visualización que renderiza los mosaicos.

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

this.add.tilemap(key) es una fábrica registrada en GameObjectFactory. Este delega en ParseToTilemap , que lee de la caché y devuelve una Tilemap instancia.

Conjuntos de mosaicos

Un Tileset (src/tilemaps/Tileset.js) vincula un nombre de conjunto de mosaicos (de Tiled) a una textura cargada. Almacena firstgid, las dimensiones de los mosaicos, el margen y el espaciado.

// 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) - Si el nombre del conjunto de mosaicos ya existe en los datos del mapa analizados, actualiza el objeto Tileset existente con la textura. Si no es así (mapas que no son de Tiled), crea un nuevo Tileset.

Importante: El analizador de Tiled de Phaser no admite conjuntos de mosaicos del tipo «Colección de imágenes». Todos los mosaicos deben estar en una única imagen por conjunto de mosaicos.

La clase Tile

Cada celda de una capa es un Tile objeto (src/tilemaps/Tile.js). Propiedades clave:

• index - índice del mosaico en el conjunto de mosaicos (-1 si está vacío)
• x, y - coordenadas del mosaico (en mosaicos, no en píxeles)
• pixelX, pixelY - posición en píxeles respecto al origen de la capa
• width, height - tamaño del mosaico en píxeles
• properties - propiedades personalizadas de Tiled (objeto)
• collideLeft, collideRight, collideUp, collideDown - indicadores de colisión por arista
• faceLeft, faceRight, faceTop, faceBottom - indicadores de caras de interés para la optimización de colisiones
• collisionCallback - función de devolución de llamada de colisión por mosaico
• tint - valor del color de matiz (por defecto 0xffffff)
• tintMode - modo de fusión del tinte (por defecto TintModes.MULTIPLY)
• rotation - Ángulo de rotación
• physics - Objeto para datos específicos del motor físico (p. ej., cuerpos)
• alpha, visible, flipX, flipY - heredado de los mixins

TilemapGPULayer (v4.0.0)

TilemapGPULayer es una alternativa de alto rendimiento, exclusiva para WebGL, a TilemapLayer. Representa toda la capa como un único cuadrilátero mediante un shader, lo que hace que su rendimiento dependa casi por completo de la GPU.

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

Características:

• Solo un conjunto de mosaicos por capa (no admite múltiples conjuntos de mosaicos)
• Tamaño máximo del mapa de mosaicos: 4096 x 4096 mosaicos
• Número máximo de ID de mosaicos únicos: 2^23 (8 388 608)
• Admite la inversión de mosaicos y la animación de mosaicos
• Solo mapas ortográficos (no iso/hexagonales/escalonados)
• Bordes de mosaicos suaves con filtrado LINEAL (sin costuras)
• Píxeles nítidos con filtrado NEAREST

Restricciones:

• Los cambios en las capas no se muestran automáticamente. Llama a generateLayerDataTexture() después de modificar los mosaicos.
• Solo renderizador WebGL (sin alternativa de Canvas)
• No se pueden utilizar varios conjuntos de mosaicos en una misma capa

// If you edit tiles on a GPU layer, regenerate the data texture:
gpuLayer.putTileAt(5, 10, 10);
gpuLayer.generateLayerDataTexture();

TilemapLayerBase

Ambos TilemapLayer y TilemapGPULayer hereda TilemapLayerBase (src/tilemaps/TilemapLayerBase.js), que a su vez hereda de GameObject. La clase base proporciona todos los métodos de consulta, manipulación y colisión de mosaicos. Incluye los siguientes mixins de componentes: Alpha, BlendMode, ComputedSize, Depth, ElapseTimer, Flip, GetBounds, Lighting, Mask, Origin, RenderNodes, Transform, Visible, ScrollFactor y Arcade Physics Collision.

Patrones comunes

Creación a partir de JSON de Tiled

preload() {
    this.load.tilemapTiledJSON('map', 'assets/map.json');
    this.load.image('tiles', 'assets/tileset.png');
}create() {
    const map = this.add.tilemap('map');
    const tileset = map.addTilesetImage('TilesetNameInTiled', 'tiles');
    const layer = map.createLayer('LayerNameInTiled', tileset);
}

El layerID pasado a createLayer debe coincidir exactamente con el nombre de la capa en Tiled. Los elementos secundarios de las capas de grupo se aplanan siguiendo una 'ParentGroup/Layer' convención de nomenclatura.

Varias capas

const map = this.add.tilemap('map');
const tileset = map.addTilesetImage('terrain', 'terrain-img');const background = map.createLayer('Background', tileset);
const ground = map.createLayer('Ground', tileset);
const foreground = map.createLayer('Foreground', tileset);// Layers are rendered in creation order. Use depth for finer control:
foreground.setDepth(10);

Una capa puede utilizar varios conjuntos de mosaicos (solo en la capa de CPU):

const tiles1 = map.addTilesetImage('terrain', 'terrain-img');
const tiles2 = map.addTilesetImage('objects', 'objects-img');
const layer = map.createLayer('Ground', [tiles1, tiles2]);

Creación de una capa en blanco

const map = this.add.tilemap('map');
const tileset = map.addTilesetImage('terrain', 'terrain-img');// createBlankLayer(name, tileset, x, y, width, height, tileWidth, tileHeight)
const layer = map.createBlankLayer('dynamic', tileset, 0, 0, 50, 50, 32, 32);// Fill it with tiles
layer.fill(1);  // Fill entire layer with tile index 1
layer.putTileAt(5, 10, 10);  // Place tile index 5 at tile coord (10, 10)

Configuración de colisiones

Hay varias formas de habilitar la colisión de mosaicos en Arcade Physics:

// By specific tile indexes
layer.setCollision([1, 2, 3]);// By range (inclusive)
layer.setCollisionBetween(1, 50);// By tile property (set in Tiled's tileset editor)
layer.setCollisionByProperty({ collides: true });
// Supports arrays: { type: ['stone', 'lava'] }// By exclusion - collide on ALL tiles except these
layer.setCollisionByExclusion([-1, 0]);  // -1 is empty, 0 is often background// From Tiled collision editor shapes
layer.setCollisionFromCollisionGroup();

Todos los métodos de colisión de los TilemapLayerBase métodos de espejo Tilemap pero no requieren un layer parámetro. En el Tilemap, puedes pasar una referencia de capa o utilizar la «capa actual»:

map.setLayer('Ground');
map.setCollision([1, 2, 3]);  // Applies to current layer
// Or specify a layer explicitly:
map.setCollision([1, 2, 3], true, true, 'Ground');

Integración física (Arcade)

// Enable collisions between a sprite and a tilemap layer
this.physics.add.collider(player, groundLayer);// With a callback
this.physics.add.collider(player, groundLayer, (sprite, tile) => {
    if (tile.index === 5) {
        // Hit a special tile
    }
});// Overlap detection instead of collision
this.physics.add.overlap(player, groundLayer, (sprite, tile) => {
    // Player is overlapping this tile
});

La capa debe tener activada la colisión en sus casillas (mediante setCollision* métodos) para que la física las detecte. La propia capa dispone de collisionCategory y collisionMask propiedades para el filtrado de colisiones.

Propiedades de los mosaicos

Los mosaicos pueden tener propiedades personalizadas configuradas en el editor de conjuntos de mosaicos de Tiled:

// Access tile properties
const tile = layer.getTileAt(10, 5);
console.log(tile.properties.damage);    // Custom property from Tiled
console.log(tile.properties.type);      // Custom property from Tiled// Set collision based on custom properties
layer.setCollisionByProperty({ collides: true });
layer.setCollisionByProperty({ type: ['wall', 'rock'] });

Llamadas de retorno de los mosaicos

// Callback by tile index - fires when physics body overlaps these tiles
map.setTileIndexCallback([5, 6, 7], (sprite, tile) => {
    // Called for tiles with index 5, 6, or 7
    console.log('Hit tile', tile.index, 'at', tile.x, tile.y);
}, this);// Callback by tile location - fires for tiles in a rectangular area
map.setTileLocationCallback(10, 10, 5, 5, (sprite, tile) => {
    // Called for any tile in the 5x5 region starting at (10, 10)
}, this);// Per-tile callback
const tile = layer.getTileAt(10, 5);
tile.collisionCallback = (sprite, tile) => {
    // Custom logic for this specific tile
};

Las funciones de llamada de los mosaicos requieren un colisionador físico activo o una superposición entre el cuerpo y la capa.

Consulta de mosaicos

const tile = layer.getTileAt(10, 5);               // By tile coords (or null)
const tile = layer.getTileAt(10, 5, true);          // nonNull: Tile with index -1 instead of null
const tile = layer.getTileAtWorldXY(worldX, worldY); // By world coords
const exists = layer.hasTileAt(10, 5);              // Boolean check// Region queries
const tiles = layer.getTilesWithin(0, 0, 10, 10);            // Tile coord region
const tiles = layer.getTilesWithinWorldXY(x, y, w, h);       // World coord region
const tiles = layer.getTilesWithinShape(circle);              // Shape overlap// Functional queries
const water = layer.filterTiles(t => t.properties.type === 'water');
const spawn = layer.findTile(t => t.properties.isSpawn);
layer.forEachTile(t => { /* iterate all tiles */ });

Modificación de mosaicos en tiempo de ejecución

layer.putTileAt(5, 10, 10);                      // Place tile index 5 at (10, 10)
layer.putTileAtWorldXY(5, worldX, worldY);        // Place by world coords
layer.putTilesAt([[1, 2], [3, 4]], 10, 10);       // Place a 2x2 grid
layer.removeTileAt(10, 10);                       // Remove tile
layer.fill(1, 0, 0, 10, 10);                     // Fill 10x10 region with index 1
layer.replaceByIndex(5, 10);                      // Replace all index-5 with index-10
layer.copy(0, 0, 5, 5, 20, 20);                  // Copy 5x5 from (0,0) to (20,20)
layer.randomize(0, 0, 10, 10, [1, 2, 3, 4]);     // Random tiles in region
layer.weightedRandomize([{ index: 1, weight: 4 }, { index: 2, weight: 1 }], 0, 0, 10, 10);
layer.shuffle(0, 0, 10, 10);                     // Shuffle tiles in region

Conversión de coordenadas

const tileXY = layer.worldToTileXY(worldX, worldY);   // World -> tile coords
const worldXY = layer.tileToWorldXY(tileX, tileY);    // Tile -> world coords// Reuse a vector to avoid allocation
const vec = new Phaser.Math.Vector2();
layer.worldToTileXY(worldX, worldY, true, vec);  // snapToFloor = true

Capas de objetos (en mosaico)

Las capas de objetos en mosaico definen la ubicación de puntos, rectángulos y sprites. Utiliza createFromObjects en las Tilemap:

// Create sprites from all objects on the 'Enemies' object layer
const enemies = map.createFromObjects('Enemies', {
    gid: 26,          // Match by tile GID
    classType: Enemy   // Custom class extending Sprite
});// Match by name
const coins = map.createFromObjects('Items', {
    name: 'coin',
    key: 'coin-texture',
    frame: 0
});// Match by type
const spawns = map.createFromObjects('Spawns', {
    type: 'player-spawn'
});// Access raw object layer data
const objectLayer = map.getObjectLayer('Enemies');
objectLayer.objects.forEach(obj => {
    console.log(obj.name, obj.x, obj.y, obj.properties);
});

createFromObjects(layerName, config, useTileset) opciones de configuración: id, gid, name, type, classType (por defecto Sprite), scene, container, key, frame, ignoreTileset.

Mosaicos animados

Las animaciones de los mosaicos se definen en el editor de conjuntos de mosaicos de Tiled y se analizan automáticamente. Tanto TilemapLayer y TilemapGPULayer admiten mosaicos animados. El TilemapLayerBase utiliza ElapseTimer para controlar el tiempo de animación mediante preUpdate.

Mapas isométricos, hexagonales y escalonados

// Isometric map
const map = this.add.tilemap('iso-map');
const tileset = map.addTilesetImage('iso-tiles', 'iso-img');
const layer = map.createLayer('Ground', tileset);// Get tile at world coords in isometric space
const tile = layer.getIsoTileAtWorldXY(worldX, worldY);// TilemapGPULayer does NOT support iso/hex/staggered - use TilemapLayer

La propiedad orientation se configura a partir de los datos de Tiled. Las funciones de conversión de coordenadas se seleccionan automáticamente en función de la orientación.

Referencia rápida de la API

Mapa de mosaicos (contenedor de datos; no se renderiza)

La mayoría de los métodos de consulta, colisión y manipulación de mosaicos existen tanto en Tilemap (con un layer ) y TilemapLayerBase (sin él). Es preferible llamar a la capa directamente.

TilemapLayerBase (capa renderizada —CPU y GPU—)

Colisión: setCollision(indexes), setCollisionBetween(start, stop), setCollisionByProperty(props), setCollisionByExclusion(indexes), setCollisionFromCollisionGroup(), setTileIndexCallback(indexes, cb, ctx), setTileLocationCallback(x, y, w, h, cb, ctx)

Consultas de mosaicos: getTileAt(x, y, nonNull), getTileAtWorldXY(wx, wy, nonNull, cam), getTilesWithin(x, y, w, h, opts), getTilesWithinWorldXY(wx, wy, w, h, opts, cam), getTilesWithinShape(shape, opts, cam), hasTileAt(x, y), hasTileAtWorldXY(wx, wy, cam), filterTiles(cb), findTile(cb), forEachTile(cb)

Manipulación de mosaicos: putTileAt(tile, x, y), putTileAtWorldXY(tile, wx, wy), putTilesAt(arr, x, y), removeTileAt(x, y), fill(index, x, y, w, h), copy(sx, sy, w, h, dx, dy), randomize(x, y, w, h, indexes), weightedRandomize(weights, x, y, w, h), shuffle(x, y, w, h), swapByIndex(a, b), replaceByIndex(find, replace), createFromTiles(indexes, replacements, config)

Coordenadas: worldToTileXY(wx, wy, snap, vec, cam), tileToWorldXY(tx, ty, vec, cam)

TilemapGPULayer (adicional)

Propiedades de los mosaicos

index (número, -1 = vacío), x/y (coordenadas del mosaico), pixelX/pixelY (posición en píxeles relativa a la capa), width/height, properties (objeto de Tiled), collideLeft/Right/Up/Down (booleano), collisionCallback (función), tint (número), rotation (número), alpha, flipX/flipY, physics (objeto para datos del motor)

Aspectos a tener en cuenta

1. El nombre del conjunto de mosaicos debe coincidir exactamente con el de Tiled. El primer argumento de addTilesetImage es el nombre del conjunto de mosaicos tal y como está definido en Tiled, no la clave de textura de Phaser. Si no coinciden, se produce null y una advertencia en la consola.

2. El nombre de la capa debe coincidir exactamente con el de Tiled. createLayer toma el nombre de la capa de Tiled (o el índice de la capa). A las capas hijas del grupo se les antepone 'GroupName/LayerName'.

3. Cada capa solo se puede crear una vez. Llamar createLayer dos veces con el mismo ID de capa devuelve null una advertencia. Los datos de la capa solo pueden asociarse a un único objeto de juego de capa.

4. setCollision Debe llamarse antes de que funcionen los colisionadores físicos. Si no se marcan los mosaicos como colisionables, this.physics.add.collider() atravesará todas las casillas.

5. TilemapGPULayer es únicamente ortográfica. No admite mapas isométricos, hexagonales ni escalonados. Además, solo admite un único conjunto de mosaicos por capa.

6. TilemapGPULayer requiere la regeneración manual de texturas. Tras llamar a putTileAt u otros métodos de edición, llama a generateLayerDataTexture() o los cambios no se mostrarán.

7. No se admiten conjuntos de mosaicos de tipo «Colección de imágenes». El analizador de Tiled requiere que todos los mosaicos de un conjunto de mosaicos estén en una única imagen. Es necesario que los conjuntos de mosaicos estén incrustados en el JSON exportado.

8. El índice de mosaico -1 significa que está vacío. Muchos métodos devuelven null para los mosaicos vacíos de forma predeterminada. Pasa nonNull: true para obtener un objeto Tile con index === -1 en su lugar.

9. insertNull en la fábrica de mapas de mosaicos. Al crear un mapa de mosaicos, insertNull: true almacena null para los mosaicos vacíos en lugar de objetos `Tile` con índice -1. Ahorra memoria en mapas grandes y dispersos, pero impide la colocación dinámica de mosaicos en celdas vacías.

10. Las funciones de devolución de llamada de los mosaicos solo se activan con la física activa. setTileIndexCallback y setTileLocationCallback requieren un colisionador físico o una superposición entre el cuerpo y la capa para activarse.

11. Posición de la capa y desplazamiento del mosaico. Si x y y no se especifican en createLayer, su valor por defecto es el desplazamiento de la capa definido en Tiled, no (0, 0).

Mapa del archivo fuente