Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TileMap

The TileMap class provides a lightweight way to do large complex scenes with collision without the overhead of actors.

Tile maps are made up of Cells which can draw TileSprites. Tile maps support multiple layers and work well for building tile-based games such as RPGs, adventure games, strategy games, and others. Cells can be solid so that Actors can't pass through them.

We recommend using the Tiled map editor to build your maps and export them to JSON. You can then load them using a Generic Resource and process them to create your levels. A TileMap can then be used as part of a level or map class that adds enemies and builds game objects from the Tiled map.

Creating a tile map

A TileMap is meant to be used in conjunction with a map editor. Creating a tile map is fairly straightforward.

You need a tile sheet (see SpriteSheet) that holds all the available tiles to draw. TileMap supports multiple sprite sheets, letting you organize tile sheets to your liking.

Next, you need to populate each Cell with one or more TileSprites using Cell.pushSprite.

Once the TileMap is added to a Scene, it will be drawn and updated.

You can then add Actors to the Scene and interact with the TileMap.

In this example, we take in a map configuration that we designed (for example, based on the exported structure of a JSON file).

// define TypeScript interfaces to make our life easier
public interface IMapDefinition {
  cells: IMapCellDefinition[];
  tileSheets: IMapTileSheet[];
  width: number;
  height: number;
  tileWidth: number;
  tileHeight: number;
}

public interface IMapCellDefinition {
  x: number;
  y: number;
  tileId: number;
  sheetId: number;
}

public interface IMapTileSheet {
  id: number;
  path: string;
  columns: number;
  rows: number;
}

// create a Map class that creates a game map
// based on JSON configuration
public class Map extends ex.Scene {
  private _mapDefinition: IMapDefinition;
  private _tileMap: ex.TileMap;
  constructor(mapDef: IMapDefinition) {
    // store reference to definition
    this._mapDefinition = mapDef;
    // create a tile map
    this._tileMap = new ex.TileMap(0, 0, mapDef.tileWidth, mapDef.tileHeight,
      mapDef.width / mapDef.tileWidth, mapDef.height / mapDef.tileHeight);
  }
  public onInitialize() {
    // build our map based on JSON config
    // build sprite sheets
    this._mapDefinition.tileSheets.forEach(sheet => {

      // register sprite sheet with the tile map
      // normally, you will want to ensure you load the Texture before
      // creating the SpriteSheet
      // this can be done outside the Map class, in a Loader
      this._tileMap.registerSpriteSheet(sheet.id.toString(),
        new ex.SpriteSheet(new ex.Texture(sheet.path), sheet.columns, sheet.rows,
          this._mapDefinition.tileWidth, this._mapDefinition.tileHeight));
    });
    // fill cells with sprites
    this._mapDefinition.cells.forEach(cell => {
      // create a TileSprite
      // assume tileId is the index of the frame in the sprite sheet
      var ts = new ex.TileSprite(cell.sheetId.toString(), cell.spriteId);
      // add to cell
      this._tileMap.getCell(cell.x, cell.y).pushSprite(ts);
    }
  }
}

// create a game
var game = new ex.Engine();

// add our level (JSON from external source)
var map1 = new Map({ ... });
game.add("map1", map1);
game.start();

In a real game, you will want to ensure all the textures for the sprite sheets have been loaded. You could do this in the Resource.processData function of the generic resource when loading your JSON, before creating your Map object.

Off-screen culling

The TileMap takes care of only drawing the portion of the map that is on-screen. This significantly improves performance and essentially means Excalibur can support huge maps. Since Actors off-screen are not drawn, this also means maps can support many actors.

Collision checks

You can use TileMap.collides to check if a given Actor is colliding with a solid Cell. This method returns an intersection Vector that represents the smallest overlap with colliding cells.

Hierarchy

  • TileMapImpl
    • TileMap

Implements

Index

Constructors

constructor

  • new TileMap(config: ITileMapArgs): TileMap
  • new TileMap(x: number, y: number, cellWidth: number, cellHeight: number, rows: number, cols: number): TileMap
  • Parameters

    Returns TileMap

  • Parameters

    • x: number
    • y: number
    • cellWidth: number
    • cellHeight: number
    • rows: number
    • cols: number

    Returns TileMap

Properties

cellHeight

cellHeight: number

cellWidth

cellWidth: number

cols

cols: number

data

data: Cell[] = []

eventDispatcher

eventDispatcher: EventDispatcher

Direct access to the game object event dispatcher.

logger

logger: Logger = Logger.getInstance()

rows

rows: number

x

x: number

y

y: number

Methods

collides

  • Returns the intersection vector that can be used to resolve collisions with actors. If there is no collision null is returned.

    Parameters

    Returns Vector

debugDraw

  • debugDraw(ctx: CanvasRenderingContext2D): void
  • Draws all the tile map's debug info. Called by the Scene.

    Parameters

    • ctx: CanvasRenderingContext2D

      The current rendering context

    Returns void

draw

  • draw(ctx: CanvasRenderingContext2D, delta: number): void
  • Draws the tile map to the screen. Called by the Scene.

    Parameters

    • ctx: CanvasRenderingContext2D

      The current rendering context

    • delta: number

      The number of milliseconds since the last draw

    Returns void

emit

  • emit(eventName: string, eventObject?: GameEvent<any>): void
  • Emits a new event

    Parameters

    • eventName: string

      Name of the event to emit

    • Optional eventObject: GameEvent<any>

      Data associated with this event

    Returns void

getCell

  • getCell(x: number, y: number): Cell
  • Returns the Cell by its x and y coordinates

    Parameters

    • x: number
    • y: number

    Returns Cell

getCellByIndex

  • getCellByIndex(index: number): Cell
  • Returns the Cell by index (row major order)

    Parameters

    • index: number

    Returns Cell

getCellByPoint

  • getCellByPoint(x: number, y: number): Cell
  • Returns the Cell by testing a point in global coordinates, returns null if no cell was found.

    Parameters

    • x: number
    • y: number

    Returns Cell

off

  • off(eventName: string, handler?: function): void
  • Alias for removeEventListener. If only the eventName is specified it will remove all handlers registered for that specific event. If the eventName and the handler instance are specified only that handler will be removed.

    Parameters

    • eventName: string

      Name of the event to listen for

    • Optional handler: function

      Event handler for the thrown event

    Returns void

on

  • on(eventName: Events.preupdate, handler: function): void
  • on(eventName: Events.postupdate, handler: function): void
  • on(eventName: Events.predraw, handler: function): void
  • on(eventName: Events.postdraw, handler: function): void
  • on(eventName: string, handler: function): void
  • Parameters

    • eventName: Events.preupdate
    • handler: function
        • (event?: Events.PreUpdateEvent): void
        • Parameters

          • Optional event: Events.PreUpdateEvent

          Returns void

    Returns void

  • Parameters

    • eventName: Events.postupdate
    • handler: function
        • (event?: Events.PostUpdateEvent): void
        • Parameters

          • Optional event: Events.PostUpdateEvent

          Returns void

    Returns void

  • Parameters

    • eventName: Events.predraw
    • handler: function
        • (event?: Events.PreDrawEvent): void
        • Parameters

          • Optional event: Events.PreDrawEvent

          Returns void

    Returns void

  • Parameters

    • eventName: Events.postdraw
    • handler: function
        • (event?: Events.PostDrawEvent): void
        • Parameters

          • Optional event: Events.PostDrawEvent

          Returns void

    Returns void

  • Parameters

    • eventName: string
    • handler: function
        • (event?: Events.GameEvent<any>): void
        • Parameters

          • Optional event: Events.GameEvent<any>

          Returns void

    Returns void

once

  • once(eventName: string, handler: function): void
  • Once listens to an event one time, then unsubscribes from that event

    Parameters

    • eventName: string

      The name of the event to subscribe to once

    • handler: function

      The handler of the event that will be auto unsubscribed

    Returns void

registerSpriteSheet

  • registerSpriteSheet(key: string, spriteSheet: SpriteSheet): void
  • Parameters

    Returns void

update

  • update(engine: Engine, delta: number): void
  • Parameters

    • engine: Engine
    • delta: number

    Returns void

Static extend

  • extend(methods: any): any
  • You may wish to extend native Excalibur functionality in vanilla Javascript. Any method on a class inheriting Class may be extended to support additional functionality. In the example below we create a new type called MyActor.

    var MyActor = Actor.extend({
    
       constructor: function() {
          this.newprop = 'something';
          Actor.apply(this, arguments);
       },
    
       update: function(engine, delta) {
          // Implement custom update
          // Call super constructor update
          Actor.prototype.update.call(this, engine, delta);
    
          console.log("Something cool!");
       }
    });
    
    var myActor = new MyActor(100, 100, 100, 100, Color.Azure);

    In TypeScript, you only need to use the extends syntax, you do not need to use this method of extension.

    Parameters

    • methods: any

      A JSON object contain any methods/properties you want to extend

    Returns any