tilemaps

Tilemaps

Phaser-Tilemapsen rendern kachelbasierte Levels aus Tiled-JSON-, CSV- oder rohen 2D-Arrays. Ein Tilemap enthält geparste Kartendaten und bietet Methoden zum Hinzufügen von Kachelsätzen, zum Erstellen von Ebenen, zum Festlegen von Kollisionen und zum Abfragen von Kacheln. Ebenen (TilemapLayer oder TilemapGPULayer) sind die Spielobjekte, die die Kacheln tatsächlich rendern. Phaser unterstützt orthogonale, isometrische, hexagonale und versetzte Karten.

Wichtige Quellpfade: 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/ Verwandte Fähigkeiten: ../loading-assets/SKILL.md, ../sprites-and-images/SKILL.md

Schnellstart

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

Der Ablauf ist immer derselbe: JSON + Bild laden, Kachelkarte erstellen, Kachelsatz-Bild hinzufügen, Ebene(n) erstellen, Kollision festlegen.

Kernkonzepte

Kachelkarte vs. Ebene

Eine Tilemap ist ein Datencontainer, kein Anzeigeobjekt. Er speichert geparste Kartendaten (Ebenen, Kachelsätze, Objekte) und stellt Methoden bereit, die auf diese Daten zugreifen. Eine TilemapLayer oder TilemapGPULayer ist das eigentliche Spielobjekt, das der Anzeigeliste hinzugefügt wird und Kacheln rendert.

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

this.add.tilemap(key) ist eine bei GameObjectFactoryregistriert ist. Es delegiert an ParseToTilemap , die aus dem Cache liest und eine Tilemap Instanz zurückgibt.

Kachelsätze

Ein Tileset (src/tilemaps/Tileset.js) verknüpft einen Tileset-Namen (aus Tiled) mit einer geladenen Textur. Es speichert firstgid, die Kachelabmessungen, den Rand und den Abstand.

// 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) – Wenn der Tileset-Name bereits in den geparsten Kartendaten vorhanden ist, wird das bestehende Tileset-Objekt mit der Textur aktualisiert. Ist dies nicht der Fall (Nicht-Tiled-Karten), wird ein neues Tileset erstellt.

Wichtig: Der Phaser-Tiled-Parser unterstützt keine Tilesets vom Typ „Sammlung von Bildern“. Alle Kacheln müssen pro Tileset in einem einzigen Tileset-Bild enthalten sein.

Die Tile-Klasse

Jede Zelle in einer Ebene ist ein Tile Objekt (src/tilemaps/Tile.js). Wichtige Eigenschaften:

• index - Kachelindex im Tileset (-1 für leer)
• x, y - Kachelkoordinaten (in Kacheln, nicht in Pixeln)
• pixelX, pixelY - Pixelposition relativ zum Ursprung der Ebene
• width, height - Kachelgröße in Pixeln
• properties - benutzerdefinierte Eigenschaften aus Tiled (Objekt)
• collideLeft, collideRight, collideUp, collideDown - Kollisionsflags pro Kante
• faceLeft, faceRight, faceTop, faceBottom - Flags für interessante Flächen zur Kollisionsoptimierung
• collisionCallback - Callback-Funktion für Kollisionen pro Kachel
• tint - Farbtonwert (Standard 0xffffff)
• tintMode - Farbton-Mischmodus (Standard TintModes.MULTIPLY)
• rotation - Drehwinkel
• physics - Objekt für physik-engine-spezifische Daten (z. B. Körper)
• alpha, visible, flipX, flipY - von Mixins geerbt

TilemapGPULayer (v4.0.0)

TilemapGPULayer ist eine leistungsstarke, ausschließlich für WebGL bestimmte Alternative zu TilemapLayer. Es rendert die gesamte Ebene mithilfe eines Shaders als einzelnes Quad, wodurch es fast vollständig GPU-gebunden ist.

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

Funktionen:

• Nur ein Tileset pro Ebene (keine mehreren Tilesets)
• Maximale Größe der Kachelkarte: 4096 × 4096 Kacheln
• Maximale Anzahl eindeutiger Kachel-IDs: 2²³ (8.388.608)
• Unterstützt Kachelspiegelung und Kachelanimation
• Nur orthogonale Karten (keine Iso-/Hex- oder versetzte Karten)
• Glatte Kachelränder mit LINEAR-Filterung (keine Übergänge)
• Scharfe Pixel mit NEAREST-Filterung

Einschränkungen:

• Änderungen an Ebenen werden nicht automatisch angezeigt. Rufen Sie generateLayerDataTexture() nach dem Ändern von Kacheln auf.
• Nur WebGL-Renderer (kein Canvas-Fallback)
• Es können nicht mehrere Kachelsätze auf einer einzigen Ebene verwendet werden

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

TilemapLayerBase

Beides TilemapLayer und TilemapGPULayer erweitert TilemapLayerBase (src/tilemaps/TilemapLayerBase.js), die GameObject. Die Basisklasse stellt alle Methoden für die Abfrage, Bearbeitung und Kollisionsprüfung von Kacheln bereit. Sie enthält folgende Komponenten-Mixins: Alpha, BlendMode, ComputedSize, Depth, ElapseTimer, Flip, GetBounds, Lighting, Mask, Origin, RenderNodes, Transform, Visible, ScrollFactor und Arcade Physics Collision.

Häufige Muster

Erstellung aus Tiled-JSON

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

Der layerID an createLayer muss exakt mit dem Ebenennamen in Tiled übereinstimmen. Untergeordnete Elemente von Gruppenebenen werden unter einer 'ParentGroup/Layer' Namenskonvention zusammengefasst.

Mehrere Ebenen

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

Eine Ebene kann mehrere Kachelsätze verwenden (nur CPU-Ebene):

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

Erstellen einer leeren Ebene

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)

Einrichtung von Kollisionen

Es gibt mehrere Möglichkeiten, die Kachelkollision für Arcade Physics zu aktivieren:

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

Alle Kollisionsmethoden in den TilemapLayerBase Spiegelungsmethoden Tilemap benötigen jedoch keinen layer Parameter. Auf der Tilemapkönnen Sie eine Layer-Referenz übergeben oder den „aktuellen Layer“ verwenden:

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

Physik-Integration (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
});

Die Ebene muss für ihre Kacheln Kollisionen aktiviert haben (über setCollision* Methoden) aktiviert haben, damit die Physik sie erkennen kann. Die Ebene selbst verfügt über collisionCategory sowie collisionMask Eigenschaften zur Kollisionsfilterung.

Kachel-Eigenschaften

Kacheln können im Tileset-Editor von Tiled mit benutzerdefinierten Eigenschaften versehen werden:

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

Kachel-Callbacks

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

Kachel-Callbacks erfordern einen aktiven Physik-Kollider bzw. eine Überlappung zwischen dem Körper und der Ebene.

Abfrage von Kacheln

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

Kacheln zur Laufzeit ändern

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

Koordinatenumrechnung

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

Objektebenen (gekachelt)

Kachelbasierte Objektebenen definieren die Platzierung von Punkten, Rechtecken und Sprites. Verwenden Sie createFromObjects in den 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) Konfigurationsoptionen: id, gid, name, type, classType (Standard Sprite), scene, container, key, frame, ignoreTileset.

Animierte Kacheln

Kachelanimationen werden im Tileset-Editor von Tiled definiert und automatisch analysiert. Sowohl TilemapLayer und TilemapGPULayer unterstützen animierte Kacheln. Die TilemapLayerBase verwendet ElapseTimer , um die Animationszeit über preUpdate.

Isometrische, hexagonale und versetzte Karten

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

Die Eigenschaft orientation wird anhand der Tiled-Daten festgelegt. Koordinatenumrechnungsfunktionen werden automatisch entsprechend der Ausrichtung ausgewählt.

API-Kurzanleitung

Tilemap (Datencontainer – wird nicht gerendert)

Die meisten Methoden zur Abfrage, Kollisionsprüfung und Bearbeitung von Kacheln sind sowohl Tilemap (mit zusätzlichem layer Parameter) als auch TilemapLayerBase (ohne). Es wird empfohlen, die Methoden direkt auf der Ebene aufzurufen.

TilemapLayerBase (gerenderte Ebene – CPU und GPU)

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

Kachelabfragen: 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)

Kachelbearbeitung: 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)

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

TilemapGPULayer (zusätzlich)

Kacheleigenschaften

index (Anzahl, -1 = leer), x/y (Kachelkoordinaten), pixelX/pixelY (Pixelposition relativ zur Ebene), width/height, properties (Objekt aus Tiled), collideLeft/Right/Up/Down (Boolescher Wert), collisionCallback (Funktion), tint (Zahl), rotation (Zahl), alpha, flipX/flipY, physics (Objekt für Engine-Daten)

Hinweise

1. Der Name des Tilesets muss genau mit dem in Tiled übereinstimmen. Das erste Argument von addTilesetImage ist der in Tiled definierte Tileset-Name, nicht der Phaser-Textur-Schlüssel. Wenn diese nicht übereinstimmen, erfolgt null zurück und eine Konsolenwarnung.

2. Der Layername muss exakt mit dem in Tiled übereinstimmen. createLayer übernimmt den Layernamen aus Tiled (oder den Layer-Index). Untergeordnete Layer einer Gruppe erhalten das Präfix 'GroupName/LayerName'.

3. Jede Ebene kann nur einmal erstellt werden. Der Aufruf von createLayer mit derselben Layer-ID zweimal führt zu null eine Warnung zurück. Die Layer-Daten können nur einem einzigen Layer-Game-Object zugeordnet werden.

4. setCollision muss aufgerufen werden, bevor Physik-Kollisionskörper funktionieren. Ohne Kacheln als kollidierbar zu markieren, this.physics.add.collider() werden alle Kacheln durchdrungen.

5. „TilemapGPULayer“ ist ausschließlich orthografisch. Es unterstützt keine isometrischen, hexagonalen oder versetzten Karten. Außerdem unterstützt es nur ein einziges Kachelsatz pro Ebene.

6. TilemapGPULayer erfordert eine manuelle Neugenerierung der Texturen. Nach dem Aufruf putTileAt oder anderer Bearbeitungsmethoden aufrufen Sie generateLayerDataTexture() , sonst werden die Änderungen nicht angezeigt.

7. Tilesets vom Typ „Bildersammlung“ werden nicht unterstützt. Der Tiled-Parser erfordert, dass sich alle Kacheln eines Tilesets in einem einzigen Bild befinden. In das exportierte JSON müssen Tilesets eingebettet sein.

8. Der Kachelindex -1 bedeutet „leer“. Viele Methoden geben null standardmäßig für leere Kacheln zurück. Übergeben Sie nonNull: true , um stattdessen ein Tile-Objekt mit index === -1 stattdessen.

9. insertNull in der Tilemap-Factory. Beim Erstellen einer Tilemap insertNull: true speichert null für leere Kacheln anstelle von „Tile“-Objekten mit dem Index -1. Das spart Speicherplatz bei großen, spärlich besetzten Karten, verhindert jedoch die dynamische Platzierung von Kacheln in leeren Zellen.

10. Tile-Callbacks werden nur bei aktiver Physik ausgelöst. setTileIndexCallback und setTileLocationCallback benötigen einen Physik-Kollidierer oder eine Überlappung zwischen dem Körper und der Ebene, um ausgelöst zu werden.

11. Ebenenposition und Kachelversatz. Wenn x und y in createLayer, werden sie standardmäßig auf den in Tiled definierten Layer-Offset gesetzt, nicht auf (0, 0).

Quelldatei-Karte