tilemaps

Tilemaps

Tilemaps, de Phaser, génère des niveaux basés sur des tuiles à partir de fichiers Tiled au format JSON, CSV ou de tableaux 2D bruts. Une Tilemap contient les données de carte analysées et fournit des méthodes pour ajouter des jeux de tuiles, créer des couches, définir les collisions et interroger les tuiles. Les couches (TilemapLayer ou TilemapGPULayer) sont les objets de jeu qui affichent effectivement les tuiles. Phaser prend en charge les cartes orthogonales, isométriques, hexagonales et en quinconce.

Chemins d’accès aux sources clés : 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/ Compétences associées : ../loading-assets/SKILL.md, ../sprites-and-images/SKILL.md

Démarrage rapide

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

La procédure est toujours la suivante : charger le fichier JSON et l’image, créer une carte de tuiles, ajouter l’image du jeu de tuiles, créer un ou plusieurs calques, définir les collisions.

Concepts fondamentaux

Carte de tuiles vs calque

Une Tilemap est un conteneur de données, et non un objet d’affichage. Elle stocke les données de carte analysées (couches, jeux de tuiles, objets) et fournit des méthodes permettant de les manipuler. Une TilemapLayer ou TilemapGPULayer est l’objet de jeu proprement dit ajouté à la liste d’affichage qui effectue le rendu des tuiles.

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

this.add.tilemap(key) est une fabrique enregistrée sur GameObjectFactory. Il délègue à ParseToTilemap qui lit dans le cache et renvoie une Tilemap instance.

Jeux de tuiles

Un Tileset (src/tilemaps/Tileset.js) associe un nom de jeu de tuiles (provenant de Tiled) à une texture chargée. Il stocke firstgid, les dimensions des tuiles, la marge et l’espacement.

// 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 le nom du jeu de tuiles existe déjà dans les données de carte analysées, il met à jour l’objet Tileset existant avec la texture. Sinon (cartes non Tiled), il crée un nouveau Tileset.

Important : l’analyseur Tiled de Phaser ne prend pas en charge les ensembles de tuiles de type « Collection d’images ». Toutes les tuiles doivent figurer dans une seule image par ensemble de tuiles.

La classe Tile

Chaque cellule d’un calque est un Tile objet (src/tilemaps/Tile.js). Propriétés clés :

• index - l'index de la tuile dans le jeu de tuiles (-1 si vide)
• x, y - coordonnées de la tuile (en tuiles, et non en pixels)
• pixelX, pixelY - position en pixels par rapport à l'origine du calque
• width, height - taille de la tuile en pixels
• properties - propriétés personnalisées issues de Tiled (objet)
• collideLeft, collideRight, collideUp, collideDown - indicateurs de collision par arête
• faceLeft, faceRight, faceTop, faceBottom - indicateurs de faces intéressantes pour l'optimisation des collisions
• collisionCallback - fonction de rappel de collision par tuile
• tint - valeur de la teinte (par défaut 0xffffff)
• tintMode - mode de fusion de la teinte (par défaut TintModes.MULTIPLY)
• rotation - angle de rotation
• physics - objet pour les données spécifiques au moteur physique (par exemple, les corps)
• alpha, visible, flipX, flipY - hérité des mixins

TilemapGPULayer (v4.0.0)

TilemapGPULayer est une alternative haute performance, exclusivement WebGL, à TilemapLayer. Il rend l'intégralité de la couche sous la forme d'un seul quad à l'aide d'un shader, ce qui le rend presque entièrement lié au GPU.

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

Capacités :

• Un seul jeu de tuiles par couche (pas de jeux de tuiles multiples)
• Taille maximale de la carte de tuiles : 4096 x 4096 tuiles
• Nombre maximal d’identifiants de tuiles uniques : 2^23 (8 388 608)
• Prise en charge de la rotation et de l’animation des tuiles
• Cartes orthographiques uniquement (pas d'iso/hex/décalées)
• Bords de tuiles lissés avec un filtrage LINÉAIRE (pas de joints visibles)
• Pixels nets avec filtrage NEAREST

Restrictions :

• Les modifications apportées aux couches ne s’affichent pas automatiquement. Appelez generateLayerDataTexture() après avoir modifié les tuiles.
• Rendu WebGL uniquement (pas de solution de secours Canvas)
• Impossible d’utiliser plusieurs jeux de tuiles sur un même calque

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

TilemapLayerBase

Les deux TilemapLayer et TilemapGPULayer héritent TilemapLayerBase (src/tilemaps/TilemapLayerBase.js), qui hérite de GameObject. La classe de base fournit toutes les méthodes de requête, de manipulation et de collision des tuiles. Elle inclut les mixins de composants suivants : Alpha, BlendMode, ComputedSize, Depth, ElapseTimer, Flip, GetBounds, Lighting, Mask, Origin, RenderNodes, Transform, Visible, ScrollFactor et Arcade Physics Collision.

Modèles courants

Création à partir d'un fichier JSON 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);
}

Le layerID passé à createLayer doit correspondre exactement au nom de la couche dans Tiled. Les éléments enfants d’une couche de groupe sont regroupés selon une 'ParentGroup/Layer' convention de nommage.

Couches multiples

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

Un calque peut utiliser plusieurs jeux de tuiles (calque CPU uniquement) :

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

Création d’un calque vierge

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)

Configuration des collisions

Il existe plusieurs façons d’activer les collisions entre tuiles pour 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();

Toutes les méthodes de collision des TilemapLayerBase méthodes « mirror » Tilemap mais ne nécessitent pas de layer paramètre. Sur la Tilemap, vous pouvez passer une référence de couche ou utiliser la « couche actuelle » :

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

Intégration physique (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 couche doit avoir la collision activée sur ses tuiles (via les setCollision* méthodes) pour que la physique puisse les détecter. La couche elle-même dispose de collisionCategory et collisionMask propriétés permettant de filtrer les collisions.

Propriétés des tuiles

Les tuiles peuvent avoir des propriétés personnalisées définies dans l'éditeur de jeux de tuiles 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'] });

Callbacks de tuiles

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

Les callbacks de tuiles nécessitent un collider physique actif ou un chevauchement entre le corps et le calque.

Interrogation des tuiles

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

Modification des tuiles à l'exécution

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

Conversion des coordonnées

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

Couches d’objets (en mosaïque)

Les couches d’objets en mosaïque définissent l’emplacement des points, des rectangles et des sprites. Utilisez createFromObjects les 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) options de configuration suivantes : id, gid, name, type, classType (par défaut Sprite), scene, container, key, frame, ignoreTileset.

Tuiles animées

Les animations de tuiles sont définies dans l’éditeur de jeux de tuiles de Tiled et analysées automatiquement. Les deux TilemapLayer et TilemapGPULayer prennent en charge les tuiles animées. Le TilemapLayerBase utilise ElapseTimer pour suivre la durée de l’animation via preUpdate.

Cartes isométriques, hexagonales et en quinconce

// 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 propriété orientation est définie à partir des données Tiled. Les fonctions de conversion des coordonnées sont automatiquement sélectionnées en fonction de l’orientation.

Référence rapide de l’API

Carte de tuiles (conteneur de données – non affichée)

La plupart des méthodes de requête, de collision et de manipulation des tuiles existent à la fois Tilemap (avec un layer ) et TilemapLayerBase (sans). Il est préférable d’appeler directement la couche.

TilemapLayerBase (couche affichée – CPU et GPU)

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

Requêtes de tuiles : 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)

Manipulation des tuiles : 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)

Coordonnées : worldToTileXY(wx, wy, snap, vec, cam), tileToWorldXY(tx, ty, vec, cam)

TilemapGPULayer (supplémentaire)

Propriétés des tuiles

index (nombre, -1 = vide), x/y (coordonnées de la tuile), pixelX/pixelY (position en pixels par rapport au calque), width/height, properties (objet provenant de Tiled), collideLeft/Right/Up/Down (booléen), collisionCallback (fonction), tint (nombre), rotation (nombre), alpha, flipX/flipY, physics (objet pour les données du moteur)

Points à retenir

1. Le nom du jeu de tuiles doit correspondre exactement à celui défini dans Tiled. Le premier argument de addTilesetImage est le nom du jeu de tuiles tel qu’il est défini dans Tiled, et non la clé de texture Phaser. S’ils ne correspondent pas, vous obtenez null et un avertissement s'affiche dans la console.

2. Le nom de la couche doit correspondre exactement à celui de Tiled. createLayer reprend le nom de la couche de Tiled (ou son index). Les éléments enfants d’une couche de groupe sont préfixés par 'GroupName/LayerName'.

3. Chaque couche ne peut être créée qu’une seule fois. Appeler createLayer deux fois avec le même ID de couche renvoie null un avertissement. Les données de couche ne peuvent être associées qu’à un seul objet de jeu de couche.

4. setCollision doit être appelé avant que les collideurs physiques ne fonctionnent. Si les tuiles ne sont pas marquées comme « collidables », this.physics.add.collider() traversera toutes les tuiles.

5. TilemapGPULayer est uniquement orthographique. Il ne prend pas en charge les cartes isométriques, hexagonales ou en quinconce. Il ne prend également en charge qu’un seul jeu de tuiles par couche.

6. TilemapGPULayer nécessite une régénération manuelle des textures. Après avoir appelé putTileAt ou d’autres méthodes d’édition, appelez generateLayerDataTexture() sinon les modifications n'apparaîtront pas.

7. Les jeux de tuiles de type « Collection d’images » ne sont pas pris en charge. L’analyseur Tiled exige que toutes les tuiles d’un jeu de tuiles se trouvent dans une seule image. Les jeux de tuiles intégrés dans le fichier JSON exporté sont obligatoires.

8. L'index de tuile -1 signifie « vide ». De nombreuses méthodes renvoient null pour les tuiles vides par défaut. Passez nonNull: true pour obtenir un objet Tile avec index === -1 à la place.

9. insertNull dans la fabrique de cartes de tuiles. Lors de la création d’une carte de tuiles, insertNull: true enregistre null pour les tuiles vides au lieu d’objets Tile avec l’index -1. Cela permet d’économiser de la mémoire pour les grandes cartes clairsemées, mais empêche le placement dynamique de tuiles dans les cellules vides.

10. Les callbacks de tuiles ne se déclenchent que lorsque la physique est active. setTileIndexCallback et setTileLocationCallback nécessitent un collideur physique ou un chevauchement entre le corps et la couche pour se déclencher.

11. Position de la couche et décalage de la tuile. Si x et y ne sont pas spécifiés dans createLayer, leur valeur par défaut est le décalage de couche défini dans Tiled, et non (0, 0).

Fichier source de la carte