Tile map

Introduction

Display of tiles map, built-in game object of phaser.

  • Author: Richard Davey

Usage

Hierarchy

graph TD

map --> layerA
map --> layerB

layerA --> tilesA["tiles<br>(layer.data[x][y])"]
layerB --> tilesB["tiles"]
  • map : A container for Tilemap data.
  • layer : A Game Object that renders LayerData from a map when used in combination with one or more tileset.
  • tiles : A 2d array of Tile object
    • Tile : A lightweight data representation, store position information without factoring in scroll, layer scale or layer position.
  • tileset : Image and tileData of some kind of tiles.

Load tile map

scene.load.tilemapTiledJSON(key, url);  // JSON
scene.load.tilemapCSV(key, url);          // CSV

Add tile map object

  1. Create map
    • Create map from tiled
      var map = scene.add.tilemap(key);
      // var map = this.make.tilemap({ key: 'map', tileWidth: 16, tileHeight: 16 });
      
    • Create map from 2d array
      var map = this.make.tilemap({
          // data: tileIdxArray,  // [ [], [], ... ]
          tileWidth: 32,
          tileHeight: 32,
          width: 10,
          height: 10
      });
      
    • Create map from csv
      var map = this.make.tilemap({
          key: 'map',     // csv file
          tileWidth: 32,
          tileHeight: 32
      });
      
  2. Add tileset image
    var tileset = map.addTilesetImage(tilesetName, key); // key: texture key
    // var tileset = map.addTilesetImage(tilesetName);  // key = tilesetName
    // var tileset = map.addTilesetImage(tilesetName, key, tileWidth, tileHeight, tileMargin, tileSpacing, gid);
    
  3. Create layer
    • Create existed layer
      var layer = map.createLayer(layerID, tileset);
      // var layer = map.createLayer(layerID, tileset, x, y);
      
      • tileset : The tileset, or an array of tilesets.
        • A string, or an array of string.
        • A tileset object, or an array of tileset objects.
      • x, y : Offset in pixels. Default is 0/0.
    • Create a new and empty layer
      var layer = map.createBlankLayer(layerID, tileset);
      // var layer = map.createBlankLayer(layerID, tileset, x, y, width, height, tileWidth, tileHeight); // x, y : offset in pixels
      
      • layerID : The name of this layer. Must be unique within the map.
      • tileset : The tileset, or an array of tilesets.
        • A string, or an array of string.
        • A tileset object, or an array of tileset objects.
      • x, y : Offset in pixels. Default is 0/0.
      • width, height : The width/height of the layer in tiles. Default is map.width/map.height.
      • tileWidth, tileHeight : The width/height of the tiles the layer uses for calculations. Default is map's tileWidth/tileHeight.
  4. Create game objects (optional)
    • Create game objects by Object-ID/Object-GID/Object-Name
      var sprites = map.createFromObjects(layerName, {
          // gid: 26,
          // name: 'bonus',
          // id: 9,
      
          // classType: Sprite,
          // scene,
          // container: null,
          // key: null,
          // frame: null
      });
      
      or
      var sprites = map.createFromObjects(layerName, configArray);
      
      • One of filter
        • gid : Object GID.
        • id : Object ID.
        • name : Object Name.
      • classType : Class of game object, default is Sprite.
      • scene : A Scene reference, passed to the Game Objects constructors. Default is map's scene.
      • container : Optional Container to which the Game Objects are added.
      • key, frame : Optional key of a Texture to be used.
    • Create game objects by tile
      var sprites = map.createFromTiles(indexes, replacements, spriteConfig);
      // var sprites = map.createFromTiles(indexes, replacements, spriteConfig, scene, camera, layer);
      
      • indexes : The tile index, or array of indexes
      • replacements :
        • null : Leave the tiles unchanged
        • Array of indexes : One-to-one mapping indexes to replacements.
      • spriteConfig : The config object to pass into the Sprite creator (i.e. scene.make.sprite).
      • scene : The Scene to create the Sprites within.
      • camera : The Camera to use when determining the world XY.
      • layer : The Tilemap Layer to act upon.

Map

Map size

var mapWidth = map.width;
var mapHeight = map.height;

Tile size

  • Set
    map.setBaseTileSize(tileWidth, tileHeight);
    
  • Get
    var tileWidth = map.tileWidth;
    var tileHeight = map.tileHeight;
    

Tile/world position

  • World position -> Tile position
    var tileXY = map.worldToTileXY(worldX, worldY);
    // var out = map.worldToTileXY(worldX, worldY, snapToFloor, out, camera, layer);
    
  • Tile position -> World position
    var worldXY = map.tileToWorldXY(tileX, tileY);
    // var out = map.tileToWorldXY(tileX, tileY, out, camera, layer);
    

Tile at world XY

var hasTile = map.hasTileAtWorldXY(worldX, worldY);

or

var hasTile = map.hasTileAtWorldXY(worldX, worldY, camera, layer);

Draw on graphics

map.renderDebug(graphics);

or

map.renderDebug(graphics, {
    tileColor: new Phaser.Display.Color(105, 210, 231, 150),         // null
    collidingTileColor: new Phaser.Display.Color(243, 134, 48, 200), // null
    faceColor: new Phaser.Display.Color(40, 39, 37, 150)             // null
});

or

map.renderDebug(graphics, styleConfig, layer);

Layer

A Game Object that renders LayerData from a map when used in combination with one or more tileset.

Get layer

  • Get layer instance
    var layer = map.getLayer(name);
    
  • Set current layer of map
    map.setLayer(layer);  // layer name, layer index
    
    or
    map.layer = layer;
    

Render pipeline

layer.setPipeline(pipelineName);
layer.setPostPipeline(pipelineName);

See Render pipeline section of Game object.

Render order

layer.setRenderOrder(renderOrder);
  • renderOrder
    • 0, or 'right-down'
    • 1, or 'left-down'
    • 2, or 'right-up'
    • 3, or 'left-up'

Fill tiles

  • Fill current layer
    map.fill(index);  // Fill all grids
    
    or
    map.fill(index, tileX, tileY, width, height);
    
  • Fill layer
    layer.fill(index);  // Fill all grids
    
    or
    layer.fill(index, tileX, tileY, width, height);
    

Randomize

  • Randomize current layer
    map.randomize(); // Randomize all grids
    
    or
    map.randomize(tileX, tileY, width, height, indexes);
    
    • indexes An array of tile indexes.
      • -1 : Empty tile.
  • Weight randomize current layer
    map.weightedRandomize(
        {
            { index: 0, weight: 4 },
            { index: [0, 1], weight: 4 }
        },
        tileX, tileY, width, height);
    
  • Randomize layer
    layer.randomize();  // Randomize all grids
    
    or
    layer.randomize(tileX, tileY, width, height, indexes);
    
    • indexes An array of tile indexes.
  • Weight randomize layer
    layer.weightedRandomize(
        {
            { index: 0, weight: 4 },
            { index: [0, 1], weight: 4 }
        },
        tileX, tileY, width, height);
    

Copy tiles

  • Copy current layer
    map.copy(srcTileX, srcTileY, width, height, destTileX, destTileY);
    
  • Copy layer
    map.copy(srcTileX, srcTileY, width, height, destTileX, destTileY, recalculateFaces, layer);
    
    or
    layer.copy(srcTileX, srcTileY, width, height, destTileX, destTileY, recalculateFaces);
    

Put tile at

  • Put on current layer
    map.putTileAt(tile, tileX, tileY);
    
    • tile :
      • Tile index
      • Tile object :
        var tile = map.getTileAt(tileX, tileY);
        
        or
        var tile = map.getTileAtWorldXY(worldX, worldY);
        
  • Put on layer
    map.putTileAt(tile, tileX, tileY, recalculateFaces, layer);
    
    or
    layer.putTileAt(tile, tileX, tileY, recalculateFaces);
    
    • tile : Tile index, or tile object.

Put tiles at

  • Put on current layer
    map.putTilesAt(tilesArray, tileX, tileY);  // tilesArray: 1d/2d array of Tile object or tile index
    
    • tilesArray : 1d/2d array of tile objects or tile indexes
  • Put on layer
    map.putTilesAt(tilesArray, tileX, tileY, recalculateFaces, layer);
    
    or
    layer.putTilesAt(tilesArray, tileX, tileY, recalculateFaces);
    
    • tilesArray : 1d/2d array of tile objects or tile indexes

Replace tiles

  • Replace on current layer
    map.replaceByIndex(findIndex, newIndex); // Search on all grids
    
    or
    map.replaceByIndex(findIndex, newIndex, tileX, tileY, width, height);
    
  • Replace on layer
    map.replaceByIndex(findIndex, newIndex, tileX, tileY, width, height, layer);
    
    or
    layer.replaceByIndex(findIndex, newIndex, tileX, tileY, width, height);
    

Swap tiles

  • Swap on current layer
    map.swapByIndex(indexA, indexB);
    
    or
    map.swapByIndex(indexA, indexB, tileX, tileY, width, height);
    
  • Swap on layer
    map.swapByIndex(indexA, indexB, tileX, tileY, width, height, layer);
    
    or
    layer.swapByIndex(indexA, indexB, tileX, tileY, width, height);
    

Shuffle tiles

  • Shuffle on current layer
    map.shuffle();
    
    or
    map.shuffle(tileX, tileY, width, height);
    
  • Shuffle on layer
    map.shuffle(tileX, tileY, width, height, layer);
    
    or
    layer.shuffle(tileX, tileY, width, height);
    

Tile

Get tile

var tile = map.getTileAt(tileX, tileY);
// var tile = map.getTileAtWorldXY(worldX, worldY);

or

var tile = map.getTileAt(tileX, tileY, true, layer);  // Return a Tile object with an index of -1 for empty tile
// var tile = map.getTileAtWorldXY(worldX, worldY, true, camera, layer);
  • layer : The tile layer to use. Default is current layer (map.setLayer(layer))
  • tile : A tile, or null if layer is invalid.

Get tiles within a rectangle area

var tiles = map.getTilesWithin(tileX, tileY, width, height);

or

var tiles = map.getTilesWithin(tileX, tileY, width, height, {
    // isNotEmpty: false,
    // isColliding: false,
    // hasInterestingFace: false
}, layer);
  • tileX , tileY : The left/top most tile index (in tile coordinates) to use as the origin of the area. Default is 0/0.
  • width , height : How many tiles wide/tall from the tileX/tileY index the area will be. Default is map.width/map.height.
  • filteringOptions : Optional filters to apply when getting the tiles.
    • isNotEmpty : If true, only return tiles that don't have -1 for an index.
    • isColliding : If true, only return tiles that collide on at least one side.
    • hasInterestingFace : If true, only return tiles that have at least one interesting face.
  • layer : The tile layer to use. Default is current layer (map.setLayer(layer))
  • tiles : An array of Tiles, or null if layer is invalid.

Get tiles within world XY

var tiles = map.getTilesWithinWorldXY(worldX, worldY, width, height);

or

var tiles = map.getTilesWithinWorldXY(worldX, worldY, width, height,  {
    // isNotEmpty: false,
    // isColliding: false,
    // hasInterestingFace: false
}, camera, layer);
  • worldX , worldY : The world x/y coordinate for the top-left of the area.
  • width , height : The width/height of the area. Default is map.width/map.height.
  • filteringOptions : Optional filters to apply when getting the tiles.
    • isNotEmpty : If true, only return tiles that don't have -1 for an index.
    • isColliding : If true, only return tiles that collide on at least one side.
    • hasInterestingFace : If true, only return tiles that have at least one interesting face.
  • camera : The Camera to use when factoring in which tiles to return. Default is main camera.
  • layer : The tile layer to use. Default is current layer (map.setLayer(layer))
  • tiles : An array of Tiles, or null if layer is invalid.

Get tiles within shape

vat tiles = map.getTilesWithinShape(shape);

or

vat tiles = map.getTilesWithinShape(shape, {
    // isNotEmpty: false,
    // isColliding: false,
    // hasInterestingFace: false
}, camera, layer);

Shape:

  • new Phaser.Geom.Rectangle(x0, y0, width, height)
  • new Phaser.Geom.Line(x0, y0, x1, y1)
  • new Phaser.Geom.Circle(x, y, radius)
  • new Phaser.Geom.Triangle(x0, y0, x1, y1, x2, y2)

For each tile in layer

map.forEachTile(function(tile, index, tileArray) { /* ... */ }, context);

or

map.forEachTile(function(tile, index, tileArray) { /* ... */ }, context,
    tileX, tileY, width, height, {
        // isNotEmpty: false,
        // isColliding: false,
        // hasInterestingFace: false
    }, layer);
  • tileX , tileY : The left/top most tile index (in tile coordinates) to use as the origin of the area to search.
  • width , height : How many tiles wide/tall from the tileX/tileY index the area will be. Default is map.width/map.height.
  • filteringOptions : Optional filters to apply when getting the tiles.
    • isNotEmpty : If true, only return tiles that don't have -1 for an index.
    • isColliding : If true, only return tiles that collide on at least one side.
    • hasInterestingFace : If true, only return tiles that have at least one interesting face.
  • layer : The tile layer to use. Default is current layer (map.setLayer(layer))

Tile index

  • Get index
    var index = tile.index;
    
  • Copy index
    tile.index = index;
    
  • Copy
    tile.copy(tileSrc);
    
    Copies the tile data & properties from the given tile to this tile. This copies everything except for position and interesting faces.

Tile position

var x = tile.x;
var y = tile.y;

Alpha

  • Set
    tile.setAlpha(value);
    
    or
    tile.alpha = value;
    
  • Get
    var alpha = tile.alpha;
    

Visible

  • Set
    tile.setVisible(visible);
    
    or
    tile.visible = visible;
    
  • Get
    var visible = visible;
    

Flip

  • Set
    tile.setFlipX(flipX);
    tile.setFlipY(flipY);
    
    or
    tile.flipX = flipX;
    tile.flipY = flipY;
    
  • Toggle
    tile.toggleFlipX();
    tile.toggleFlipY();
    
    or
    tile.flipX = !tile.flipX;
    tile.flipY = !tile.flipY;
    
  • Reset
    tile.resetFlip();
    
    or
    tile.flipX = false;
    tile.flipY = false;
    
  • Get
    var flipX = tile.flipX;
    var flipY = tile.flipY;
    

Bounds

  • Bounds rectangle
    var bounds = tile.getBounds();
    // var out = tile.getBounds(camera, out);
    
  • Left
    var left = tile.getLeft();
    // var left = tile.getLeft(camera);
    
  • Right
    var right = tile.getRight();
    // var right = tile.getRight(camera);
    
  • CenterX
    var centerX = tile.getCenterX();
    // var centerX = tile.getCenterX(camera);
    
  • Top
    var top = tile.getTop();
    // var top = tile.getTop(camera);
    
  • Bottom
    var bottom = tile.getBottom();
    // var bottom = tile.getBottom(camera);
    
  • CenterY
    var centerY = tile.getCenterY();
    // var centerY = tile.getCenterY(camera);
    

Properties

var properties = tile.properties;  // object or null
var value = properties[key];
tile.properties[key] = value;

Collision

Enable collision

  • Enable collision by tile index
    map.setCollision(index);
    // map.setCollision(index, true, recalculateFaces, updateLayer);
    
    • index : Tile index, or an array of tile indexes.
  • Enable collision by tile index in a range
    map.setCollisionBetween(start, stop);
    // map.setCollisionBetween(start, stop, true, recalculateFaces, layer);
    
    • start , stop : The first/last index of the tile.
  • Enable collision excluded tile indexes
    map.setCollisionByExclusion(indexes);
    // map.setCollisionByExclusion(indexes, true, recalculateFaces, layer);
    
    • index : An array of tile indexes.
  • Enable collision by properties matching
    • Enable collision if value of tile property 'key' is equal to 'value'
      map.setCollisionByProperty({key:value});
      // map.setCollisionByProperty({key:value}, true, recalculateFaces, layer);
      
    • Enable collision if value of tile property 'key' is equal to 'value0', or 'value1'
      map.setCollisionByProperty({key:[value0, value1]});
      // map.setCollisionByProperty({key:[value0, value1]}, true, recalculateFaces, layer);
      
  • Enable collision by collision group
    map.setCollisionFromCollisionGroup();
    // map.setCollisionFromCollisionGroup(true, recalculateFaces, layer);
    

Disable collision

  • Disable collision by tile index
    map.setCollision(index, false);
    // map.setCollision(index, false, recalculateFaces, layer);
    
    • index : Tile index, or an array of tile indexes.
  • Disable collision by tile index in a range
    map.setCollisionBetween(start, stop, false);
    // map.setCollisionBetween(start, stop, false, recalculateFaces, layer);
    
    • start , stop : The first/last index of the tile.
  • Disable collision by properties matching
    • Disable collision if value of tile property 'key' is equal to 'value'
      map.setCollisionByProperty({key:value}, false);
      // map.setCollisionByProperty({key:value}, false, recalculateFaces, layer);
      
    • Disable collision if value of tile property 'key' is equal to 'value0', or 'value1'
      map.setCollisionByProperty({key:[value0, value1]}, false);
      // map.setCollisionByProperty({key:[value0, value1]}, false, recalculateFaces, layer);
      
  • Disable collision by collision group
    map.setCollisionFromCollisionGroup(false);
    // map.setCollisionFromCollisionGroup(false, recalculateFaces, layer);
    

Get collision group

var collisionGroup = tile.getCollisionGroup();

or

var collisionGroup = tileset.getTileCollisionGroup(tile.index); // array of collision shapes, or null

Types of collision shape (collisionGroup.objects[i])

  • object.rectangle :
    {
        rectangle: true,
        x, y,
        width, height
    }
    
    • x, y : Offset position related top-left of tile.
      var worldX = tile.getLeft() + object.x;
      var worldY = tile.getTop() + object.y;
      
    • width, height : Width/height of rectangle area in pixels.
  • object.ellipse :
    {
        ellipse: true,
        x, y,
        width, height
    }
    
    • x, y : Offset position related top-left of tile.
      var centerX = tile.getLeft() + object.x + (object.width / 2);
      var centerY = tile.getTop() + object.y + (object.height / 2);
      
    • width, height : Width/height of ellipse area in pixels.
  • object.polygon :
    {
        x, y,
        polygon: [{x,y}, {x,y}, ...]
    }
    
    • Each point :
      {
          x: tile.getLeft() + object.x + polygon[i].x,
          y: tile.getTop() + object.y + polygon[i].y
      }
      
  • object.polyline :
    {
        x, y,
        polyline: [{x,y}, {x,y}, ...]
    }
    
    • Each point :
      {
          x: tile.getLeft() + object.x + polyline[i].x,
          y: tile.getTop() + object.y + polyline[i].y
      }
      

Arcade collision

scene.physics.add.collider(arcadeGO, layer);

or, in update stage:

scene.physics.world.collide(arcadeGO, layer);

See Collision section of Arcade-world.

Matter collision

  • Any colliding tiles will be given a Matter body.
    scene.matter.world.convertTilemapLayer(layer);
    

Tileset

Get tileset

var tileset = map.getTileset(name);

Change texture of tileset

var texture = scene.sys.textures.get(key);
tileset.setImage(texture);