tilemaps

Tilemaps

O Phaser Tilemaps renderiza níveis baseados em blocos a partir de arquivos JSON do Tiled, CSV ou matrizes 2D brutas. Um Tilemap armazena dados de mapa analisados e oferece métodos para adicionar conjuntos de blocos, criar camadas, definir colisão e consultar blocos. Camadas (TilemapLayer ou TilemapGPULayer) são os Objetos de Jogo que realmente renderizam os blocos. O Phaser suporta mapas ortogonais, isométricos, hexagonais e escalonados.

Principais caminhos de código-fonte: 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

Introdução rápida

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

O fluxo é sempre: carregar JSON + imagem, criar mapa de blocos, adicionar imagem do conjunto de blocos, criar camada(s), definir colisão.

Conceitos básicos

Mapa de blocos vs. Camada

Um Tilemap é um contêiner de dados, não um objeto de exibição. Ele armazena dados de mapa analisados (camadas, conjuntos de blocos, objetos) e fornece métodos que operam sobre eles. Um TilemapLayer ou TilemapGPULayer é o Objeto de Jogo propriamente dito adicionado à lista de exibição que renderiza os blocos.

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

this.add.tilemap(key) é uma fábrica registrada em GameObjectFactory. Ele delega para ParseToTilemap que lê do cache e retorna uma Tilemap instância.

Conjuntos de blocos

Um Tileset (src/tilemaps/Tileset.js) vincula um nome de conjunto de blocos (do Tiled) a uma textura carregada. Ele armazena firstgid, as dimensões dos blocos, a margem e o espaçamento.

// 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) - Se o nome do conjunto de blocos já existir nos dados do mapa analisados, ele atualiza o objeto Tileset existente com a textura. Caso contrário (mapas que não sejam do Tiled), ele cria um novo Tileset.

Importante: O analisador Tiled do Phaser não suporta conjuntos de blocos do tipo “Coleção de Imagens”. Todos os blocos devem estar em uma única imagem por conjunto de blocos.

A classe Tile

Cada célula em uma camada é um Tile objeto (src/tilemaps/Tile.js). Principais propriedades:

• index - índice do bloco no conjunto de blocos (-1 para vazio)
• x, y - coordenadas do bloco (em blocos, não em pixels)
• pixelX, pixelY - posição em pixels em relação à origem da camada
• width, height - tamanho do bloco em pixels
• properties - propriedades personalizadas do Tiled (objeto)
• collideLeft, collideRight, collideUp, collideDown - sinalizadores de colisão por aresta
• faceLeft, faceRight, faceTop, faceBottom - sinalizadores de faces interessantes para otimização de colisão
• collisionCallback - função de retorno de chamada de colisão por bloco
• tint - valor da cor de matiz (padrão 0xffffff)
• tintMode - modo de mistura da tonalidade (padrão TintModes.MULTIPLY)
• rotation - ângulo de rotação
• physics - objeto para dados específicos do motor de física (por exemplo, corpos)
• alpha, visible, flipX, flipY - herdado de mixins

TilemapGPULayer (v4.0.0)

TilemapGPULayer é uma alternativa de alto desempenho, exclusiva para WebGL, ao TilemapLayer. Ele renderiza toda a camada como um único quadrilátero usando um shader, tornando-a quase inteiramente dependente da GPU.

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

Recursos:

• Apenas um conjunto de blocos por camada (sem suporte a múltiplos conjuntos de blocos)
• Tamanho máximo do mapa de blocos: 4096x4096 blocos
• Número máximo de IDs de blocos únicos: 2^23 (8.388.608)
• Suporta inversão e animação de blocos
• Apenas mapas ortográficos (sem iso/hex/escalonados)
• Bordas suaves dos blocos com filtragem LINEAR (sem emendas)
• Pixels nítidos com filtragem NEAREST

Restrições:

• As edições na camada não são exibidas automaticamente. Chame generateLayerDataTexture() após modificar os blocos.
• Apenas renderizador WebGL (sem fallback para Canvas)
• Não é possível usar vários conjuntos de blocos em uma única camada

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

TilemapLayerBase

Ambos TilemapLayer e TilemapGPULayer estendem TilemapLayerBase (src/tilemaps/TilemapLayerBase.js), que estende GameObject. A classe base fornece todos os métodos de consulta, manipulação e colisão de blocos. Ela inclui os seguintes mixins de componentes: Alpha, BlendMode, ComputedSize, Depth, ElapseTimer, Flip, GetBounds, Lighting, Mask, Origin, RenderNodes, Transform, Visible, ScrollFactor e Arcade Physics Collision.

Padrões comuns

Criação a partir de JSON do 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);
}

O layerID passado para createLayer deve corresponder exatamente ao nome da camada no Tiled. Os elementos filhos da camada de grupo são nivelados com uma 'ParentGroup/Layer' convenção de nomenclatura.

Várias camadas

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

Uma camada pode usar vários conjuntos de blocos (apenas na camada de CPU):

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

Criação de uma camada em branco

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)

Configuração de colisão

Existem várias maneiras de habilitar a colisão de blocos no 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 os métodos de colisão nos TilemapLayerBase métodos de espelhamento Tilemap mas não exigem um layer parâmetro. No Tilemap, você pode passar uma referência de camada ou usar a “camada atual”:

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');

Integração com 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
});

A camada deve ter a colisão definida em seus blocos (por meio dos setCollision* métodos) para que a física possa detectá-los. A própria camada possui collisionCategory e collisionMask propriedades para filtragem de colisão.

Propriedades dos blocos

Os blocos podem ter propriedades personalizadas definidas no editor de conjuntos de blocos do 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'] });

Callbacks de blocos

// 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
};

As chamadas de retorno de bloco exigem um colisor físico ativo ou sobreposição entre o corpo e a camada.

Consulta de blocos

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 */ });

Modificação de blocos em tempo de execução

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

Conversão 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

Camadas de objetos (em blocos)

Camadas de objetos em blocos definem pontos, retângulos e o posicionamento de sprites. Use createFromObjects as 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) opções de configuração: id, gid, name, type, classType (padrão Sprite), scene, container, key, frame, ignoreTileset.

Blocos animados

As animações de blocos são definidas no editor de conjuntos de blocos do Tiled e analisadas automaticamente. Tanto TilemapLayer e TilemapGPULayer suportam blocos animados. O TilemapLayerBase usa ElapseTimer para controlar o tempo de animação por meio de preUpdate.

Mapas isométricos, hexagonais e 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

A propriedade orientation é definida a partir dos dados do Tiled. As funções de conversão de coordenadas são selecionadas automaticamente com base na orientação.

Referência rápida da API

Tilemap (contêiner de dados — não renderizado)

A maioria dos métodos de consulta, colisão e manipulação de blocos existe tanto Tilemap (com o parâmetro extra layer ) e TilemapLayerBase (sem). É preferível chamar diretamente na camada.

TilemapLayerBase (camada renderizada — CPU e GPU)

Colisão: setCollision(indexes), setCollisionBetween(start, stop), setCollisionByProperty(props), setCollisionByExclusion(indexes), setCollisionFromCollisionGroup(), setTileIndexCallback(indexes, cb, ctx), setTileLocationCallback(x, y, w, h, cb, ctx)

Consultas de blocos: 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)

Manipulação de blocos: 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)

Propriedades dos blocos

index (número, -1 = vazio), x/y (coordenadas do bloco), pixelX/pixelY (posição em pixels em relação à camada), width/height, properties (objeto do Tiled), collideLeft/Right/Up/Down (booleano), collisionCallback (função), tint (número), rotation (número), alpha, flipX/flipY, physics (objeto para dados do motor)

Pontos a serem observados

1. O nome do conjunto de blocos deve corresponder exatamente ao do Tiled. O primeiro argumento de addTilesetImage é o nome do conjunto de blocos conforme definido no Tiled, não a chave de textura do Phaser. Se não corresponderem, você receberá null retornará e exibirá um aviso no console.

2. O nome da camada deve corresponder exatamente ao do Tiled. createLayer recebe o nome da camada do Tiled (ou o índice da camada). Os elementos filhos da camada de grupo recebem o prefixo 'GroupName/LayerName'.

3. Cada camada só pode ser criada uma vez. Chamar createLayer com o mesmo ID de camada duas vezes retorna null um aviso. Os dados da camada só podem ser associados a um único Game Object de camada.

4. setCollision deve ser chamado antes que os coliders de física funcionem. Sem marcar os blocos como colidíveis, this.physics.add.collider() passará por todos os blocos.

5. O `TilemapGPULayer` é apenas ortográfico. Ele não suporta mapas isométricos, hexagonais ou escalonados. Além disso, suporta apenas um conjunto de blocos por camada.

6. O TilemapGPULayer requer a regeneração manual da textura. Após chamar putTileAt ou outros métodos de edição, chame generateLayerDataTexture() ou as alterações não aparecerão.

7. Conjuntos de blocos do tipo “Coleção de Imagens” não são suportados. O analisador do Tiled exige que todos os blocos de um conjunto estejam em uma única imagem. É necessário que os conjuntos de blocos estejam incorporados no JSON exportado.

8. O índice de bloco -1 significa vazio. Muitos métodos retornam null para blocos vazios por padrão. Passe nonNull: true para obter um objeto Tile com index === -1 em vez disso.

9. insertNull na fábrica de mapas de blocos. Ao criar um mapa de blocos, insertNull: true armazena null para blocos vazios em vez de objetos `Tile` com índice -1. Economiza memória para mapas grandes e esparsos, mas impede o posicionamento dinâmico de blocos em células vazias.

10. Os callbacks de tile só são acionados com a física ativa. setTileIndexCallback e setTileLocationCallback exigem um colisor físico ou sobreposição entre o corpo e a camada para serem acionados.

11. Posição da camada e deslocamento do Tiled. Se x e y não forem especificados em createLayer, assumem por padrão o deslocamento da camada definido no Tiled, e não (0, 0).

Mapa do arquivo de origem