TilemapLayer
A TilemapLayer is a Game Object responsible for rendering a single layer of tile data from a Tilemap. It works in combination with one or more Tileset objects, which provide the actual tile imagery. You would typically create a TilemapLayer via Tilemap.createLayer, rather than instantiating it directly.
Each layer corresponds to a LayerData entry within the Tilemap, and supports all four map orientations: Orthogonal, Isometric, Hexagonal, and Staggered. The layer handles its own camera culling, only sending visible tiles to the renderer each frame, which keeps performance efficient even for large maps.
TilemapLayers support physics via both Arcade Physics and Matter.js, and can have tints, alpha, and other standard Game Object properties applied to them.
A TilemapLayer can be placed inside a Container, but its physics will work as though it was placed directly in the world. This is rarely what you want.
Constructor
new TilemapLayer(scene, tilemap, layerIndex, tileset, [x], [y])
Parameters
| name | type | optional | default | description |
|---|---|---|---|---|
| scene | Phaser.Scene | No | The Scene to which this Game Object belongs. | |
| tilemap | Phaser.Tilemaps.Tilemap | No | The Tilemap this layer is a part of. | |
| layerIndex | number | No | The index of the LayerData associated with this layer. | |
| tileset | string | Array.<string> | Phaser.Tilemaps.Tileset | Array.<Phaser.Tilemaps.Tileset> | No |
| x | number | Yes | 0 | The world x position where the top left of this layer will be placed. |
| y | number | Yes | 0 | The world y position where the top left of this layer will be placed. |
Scope: static
Extends
Source: src/tilemaps/TilemapLayer.js#L14
Since: 3.50.0
Inherited Members
From Phaser.GameObjects.Components.Alpha:
From Phaser.GameObjects.Components.BlendMode:
From Phaser.GameObjects.Components.ComputedSize:
From Phaser.GameObjects.Components.Depth:
From Phaser.GameObjects.Components.ElapseTimer:
From Phaser.GameObjects.Components.Filters:
- filterCamera
- filters
- filtersAutoFocus
- filtersFocusContext
- filtersForceComposite
- maxFilterSize
- renderFilters
From Phaser.GameObjects.Components.Flip:
From Phaser.GameObjects.Components.Lighting:
From Phaser.GameObjects.Components.Mask:
From Phaser.GameObjects.Components.RenderNodes:
From Phaser.GameObjects.Components.ScrollFactor:
From Phaser.GameObjects.Components.Transform:
From Phaser.GameObjects.Components.Visible:
From Phaser.GameObjects.GameObject:
- active
- body
- cameraFilter
- data
- displayList
- ignoreDestroy
- input
- isDestroyed
- name
- parentContainer
- renderFlags
- scene
- state
- tabIndex
- type
- vertexRoundMode
From Phaser.Tilemaps.TilemapLayerBase:
- collisionCategory
- collisionMask
- displayOriginX
- displayOriginY
- gidMap
- isTilemap
- layer
- layerIndex
- originX
- originY
- tilemap
Public Members
cullCallback
cullCallback: function
Description:
The callback that is invoked when the tiles are culled.
It will call a different function based on the map orientation:
Orthogonal (the default) is TilemapComponents.CullTiles Isometric is TilemapComponents.IsometricCullTiles Hexagonal is TilemapComponents.HexagonalCullTiles Staggered is TilemapComponents.StaggeredCullTiles
However, you can override this to call any function you like.
It will be sent 4 arguments:
-
The Phaser.Tilemaps.LayerData object for this Layer
-
The Camera that is culling the layer. You can check its
dirtyproperty to see if it has changed since the last cull. -
A reference to the
culledTilesarray, which should be used to store the tiles you want rendered. -
The Render Order constant.
See the TilemapComponents.CullTiles source code for details on implementing your own culling system.
Source: src/tilemaps/TilemapLayer.js#L136
Since: 3.50.0
culledTiles
culledTiles: Array.<Phaser.Tilemaps.Tile>
Description:
Used internally during rendering. This holds the tiles that are visible within the Camera.
Source: src/tilemaps/TilemapLayer.js#L89
Since: 3.50.0
cullPaddingX
cullPaddingX: number
Description:
The amount of extra tiles to add into the cull rectangle when calculating its horizontal size.
See the method setCullPadding for more details.
Source: src/tilemaps/TilemapLayer.js#L112
Since: 3.50.0
cullPaddingY
cullPaddingY: number
Description:
The amount of extra tiles to add into the cull rectangle when calculating its vertical size.
See the method setCullPadding for more details.
Source: src/tilemaps/TilemapLayer.js#L124
Since: 3.50.0
skipCull
skipCull: boolean
Description:
You can control if the camera should cull tiles on this layer before rendering them or not.
By default the camera will try to cull the tiles in this layer, to avoid over-drawing to the renderer.
However, there are some instances when you may wish to disable this, and toggling this flag allows you to do so. Also see setSkipCull for a chainable method that does the same thing.
Source: src/tilemaps/TilemapLayer.js#L98
Since: 3.50.0
tilesDrawn
tilesDrawn: number
Description:
The total number of tiles drawn by the renderer in the last frame.
Source: src/tilemaps/TilemapLayer.js#L69
Since: 3.50.0
tileset
tileset: Array.<Phaser.Tilemaps.Tileset>
Description:
An array of Tileset objects associated with this layer.
Source: src/tilemaps/TilemapLayer.js#L60
Since: 3.50.0
tilesTotal
tilesTotal: number
Description:
The total number of tiles in this layer. Updated every frame.
Source: src/tilemaps/TilemapLayer.js#L79
Since: 3.50.0
Inherited Methods
From Phaser.Events.EventEmitter:
- addListener
- emit
- eventNames
- listenerCount
- listeners
- off
- on
- once
- removeAllListeners
- removeListener
- shutdown
From Phaser.GameObjects.Components.Alpha:
From Phaser.GameObjects.Components.BlendMode:
From Phaser.GameObjects.Components.ComputedSize:
From Phaser.GameObjects.Components.Depth:
From Phaser.GameObjects.Components.ElapseTimer:
From Phaser.GameObjects.Components.Filters:
- enableFilters
- focusFilters
- focusFiltersOnCamera
- focusFiltersOverride
- renderWebGLFilters
- setFiltersAutoFocus
- setFiltersFocusContext
- setFiltersForceComposite
- setFilterSize
- setRenderFilters
- willRenderFilters
From Phaser.GameObjects.Components.Flip:
From Phaser.GameObjects.Components.GetBounds:
- getBottomCenter
- getBottomLeft
- getBottomRight
- getBounds
- getCenter
- getLeftCenter
- getRightCenter
- getTopCenter
- getTopLeft
- getTopRight
From Phaser.GameObjects.Components.Lighting:
From Phaser.GameObjects.Components.Mask:
From Phaser.GameObjects.Components.Origin:
From Phaser.GameObjects.Components.RenderNodes:
From Phaser.GameObjects.Components.RenderSteps:
From Phaser.GameObjects.Components.ScrollFactor:
From Phaser.GameObjects.Components.Transform:
- copyPosition
- getLocalPoint
- getLocalTransformMatrix
- getParentRotation
- getWorldPoint
- getWorldTransformMatrix
- setAngle
- setPosition
- setRandomPosition
- setRotation
- setScale
- setW
- setX
- setY
- setZ
From Phaser.GameObjects.Components.Visible:
From Phaser.GameObjects.GameObject:
- addToDisplayList
- addToUpdateList
- disableInteractive
- getData
- getDisplayList
- getIndexList
- incData
- removeFromDisplayList
- removeFromUpdateList
- removeInteractive
- setActive
- setData
- setDataEnabled
- setInteractive
- setName
- setState
- setVertexRoundMode
- toggleData
- toJSON
- update
- willRender
- willRoundVertices
From Phaser.Physics.Arcade.Components.Collision:
- addCollidesWith
- removeCollidesWith
- resetCollisionCategory
- setCollidesWith
- setCollisionCategory
- willCollideWith
From Phaser.Tilemaps.TilemapLayerBase:
- addedToScene
- calculateFacesAt
- calculateFacesWithin
- copy
- createFromTiles
- fill
- filterTiles
- findByIndex
- findTile
- forEachTile
- getIsoTileAtWorldXY
- getTileAt
- getTileAtWorldXY
- getTileCorners
- getTilesWithin
- getTilesWithinShape
- getTilesWithinWorldXY
- hasTileAt
- hasTileAtWorldXY
- preUpdate
- putTileAt
- putTileAtWorldXY
- putTilesAt
- randomize
- removedFromScene
- removeTileAt
- removeTileAtWorldXY
- renderDebug
- replaceByIndex
- setCollision
- setCollisionBetween
- setCollisionByExclusion
- setCollisionByProperty
- setCollisionFromCollisionGroup
- setTileIndexCallback
- setTileLocationCallback
- shuffle
- swapByIndex
- tileToWorldX
- tileToWorldXY
- tileToWorldY
- weightedRandomize
- worldToTileX
- worldToTileXY
- worldToTileY
Public Methods
cull
<instance> cull([camera])
Description:
Returns the tiles in the given layer that are within the camera's viewport. This is used internally during rendering.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| camera | Phaser.Cameras.Scene2D.Camera | Yes | The Camera to run the cull check against. |
Returns: Array.<Phaser.Tilemaps.Tile> - An array of Tile objects to render.
Source: src/tilemaps/TilemapLayer.js#L296
Since: 3.50.0
destroy
<instance> destroy([removeFromTilemap])
Description:
Destroys this TilemapLayer, clearing the culled tiles array and removing the cull callback. Also removes the layer from its parent Tilemap if removeFromTilemap is set to true.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| removeFromTilemap | boolean | Yes | true | Remove this layer from the parent Tilemap before destroying it. |
Overrides: Phaser.Tilemaps.TilemapLayerBase#destroy
Source: src/tilemaps/TilemapLayer.js#L439
Since: 3.50.0
setCullPadding
<instance> setCullPadding([paddingX], [paddingY])
Description:
When a Camera culls the tiles in this layer it does so using its view into the world, building up a rectangle inside which the tiles must exist or they will be culled. Sometimes you may need to expand the size of this 'cull rectangle', especially if you plan on rotating the Camera viewing the layer. Do so by providing the padding values. The values given are in tiles, not pixels. So if the tile width was 32px and you set paddingX to be 4, it would add 32px x 4 to the cull rectangle (adjusted for scale)
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| paddingX | number | Yes | 1 | The amount of extra horizontal tiles to add to the cull check padding. |
| paddingY | number | Yes | 1 | The amount of extra vertical tiles to add to the cull check padding. |
Returns: Phaser.Tilemaps.TilemapLayer - This Tilemap Layer object.
Source: src/tilemaps/TilemapLayer.js#L335
Since: 3.50.0
setRenderOrder
<instance> setRenderOrder(renderOrder)
Description:
Sets the rendering (draw) order of the tiles in this layer.
The default is 'right-down', meaning it will order the tiles starting from the top-left, drawing to the right and then moving down to the next row.
The draw orders are:
0 = right-down 1 = left-down 2 = right-up 3 = left-up
Setting the render order does not change the tiles or how they are stored in the layer, it purely impacts the order in which they are rendered.
You can provide either an integer (0 to 3), or the string version of the order.
Parameters:
| name | type | optional | description |
|---|---|---|---|
| renderOrder | number | string | No | The render (draw) order value. Either an integer between 0 and 3, or a string: 'right-down', 'left-down', 'right-up' or 'left-up'. |
Returns: Phaser.Tilemaps.TilemapLayer - This Tilemap Layer object.
Source: src/tilemaps/TilemapLayer.js#L254
Since: 3.50.0
setSkipCull
<instance> setSkipCull([value])
Description:
You can control if the Cameras should cull tiles before rendering them or not.
By default the camera will try to cull the tiles in this layer, to avoid over-drawing to the renderer.
However, there are some instances when you may wish to disable this.
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| value | boolean | Yes | true | Set to true to stop culling tiles. Set to false to enable culling again. |
Returns: Phaser.Tilemaps.TilemapLayer - This Tilemap Layer object.
Source: src/tilemaps/TilemapLayer.js#L312
Since: 3.50.0
setTint
<instance> setTint([tint], [tileX], [tileY], [width], [height], [filteringOptions])
Description:
Sets an additive tint on each Tile within the given area.
The tint works by taking the pixel color values from the tileset texture, and then multiplying it by the color value of the tint.
If no area values are given then all tiles will be tinted to the given color.
To remove a tint call this method with either no parameters, or by passing white 0xffffff as the tint color.
If a tile already has a tint set then calling this method will override that.
Tags:
- webglOnly
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| tint | number | Yes | "0xffffff" | The tint color being applied to each tile within the region. Given as a hex value, i.e. 0xff0000 for red. Set to white (0xffffff) to reset the tint. |
| tileX | number | Yes | The left most tile index (in tile coordinates) to use as the origin of the area to search. | |
| tileY | number | Yes | The top most tile index (in tile coordinates) to use as the origin of the area to search. | |
| width | number | Yes | How many tiles wide from the tileX index the area will be. | |
| height | number | Yes | How many tiles tall from the tileY index the area will be. | |
| filteringOptions | Phaser.Types.Tilemaps.FilteringOptions | Yes | Optional filters to apply when getting the tiles. |
Returns: Phaser.Tilemaps.TilemapLayer - This Tilemap Layer object.
Source: src/tilemaps/TilemapLayer.js#L361
Since: 3.60.0
setTintMode
<instance> setTintMode([tintMode], [tileX], [tileY], [width], [height], [filteringOptions])
Description:
Sets the tint mode to use when applying the tint to the texture.
Available modes are:
-
Phaser.TintModes.MULTIPLY (default)
-
Phaser.TintModes.FILL
-
Phaser.TintModes.ADD
-
Phaser.TintModes.SCREEN
-
Phaser.TintModes.OVERLAY
-
Phaser.TintModes.HARD_LIGHT
Call this method with no parameters to reset the tint mode to the default.
If a tile already has a tint mode set then calling this method will override that.
Tags:
- webglOnly
Parameters:
| name | type | optional | default | description |
|---|---|---|---|---|
| tintMode | Phaser.TintModes | Yes | "Phaser.TintModes.MULTIPLY" | The tint mode to use. |
| tileX | number | Yes | The left most tile index (in tile coordinates) to use as the origin of the area to search. | |
| tileY | number | Yes | The top most tile index (in tile coordinates) to use as the origin of the area to search. | |
| width | number | Yes | How many tiles wide from the tileX index the area will be. | |
| height | number | Yes | How many tiles tall from the tileY index the area will be. | |
| filteringOptions | Phaser.Types.Tilemaps.FilteringOptions | Yes | Optional filters to apply when getting the tiles. |
Returns: Phaser.Tilemaps.TilemapLayer - This Tilemap Layer object.
Source: src/tilemaps/TilemapLayer.js#L398
Since: 4.0.0