@pixi/tilemap -- llms.txt

pixi-tilemap-llms.md

@pixi/tilemap - PixiJS Tilemap Kit

This package provides a low-level rectangular tilemap implementation, optimized for high performance rendering and a out-of-the-box canvas fallback.

Version Compatiblity

PixiJS	PixiJS Tilemap Kit
v4.x	v1.x
v5.x	v2.x
v6.x	v3.x
v7.x	v4.x
v8.x	v5.x

Installation

npm install --save @pixi/tilemap

You can also use the browser bundle:

<script src="https://cdn.jsdelivr.net/npm/@pixi/tilemap@latest/dist/pixi-tilemap.js"></script>

Usage

In short, the tilemap you create will render each tile texture at the provided position and dimensions. Generally, a spritesheet is used to load the tileset assets:

import { Assets } from 'pixi.js';
import { CompositeTilemap } from '@pixi/tilemap';

Assets.add('atlas', 'atlas.json');
Assets.load(['atlas']).then(() => {
    const tilemap = new CompositeTilemap();

    // Render your first tile at (0, 0)!
    tilemap.tile('grass.png', 0, 0);
});

CompositeTilemap is actually a lazy composite of layered Tilemap instances. A Tilemap has a fixed number of tile textures (the tileset) it can render in one go. Usually, CompositeTilemap abstracts away this limitation in a robust enough manner.

Settings

import { settings } from '@pixi/tilemap';

Setting	Description
TEXTURES_PER_TILEMAP	Temporarily switched off
TEXTILE_UNITS	Temporarily switched off
use32bitIndex	There's also a limitation on 16k tiles per one tilemap. If you want to lift it, please use PixiJS v5.1.0 and following setting settings.use32bitIndex = true;

Tilemap

A rectangular tilemap implementation that renders a predefined set of tile textures.

The tileset of a tilemap defines the list of base-textures that can be painted in the tilemap. A texture is identified using its base-texture's index into the this list, i.e. changing the base-texture at a given index in the tileset modifies the paint of all tiles pointing to that index.

The size of the tileset is limited by the texture units supported by the client device. The minimum supported value is 8, as defined by the WebGL 1 specification. gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS) can be used to extract this limit. CompositeTilemap can be used to get around this limit by layering multiple tilemap instances.

new Tilemap (tileset)

Name	Type	Description
tileset	TextureSource | TextureSource	The tileset to use for the tilemap. This can be reset later with setTileset. The base-textures in this array must not be duplicated.

Example

import { Tilemap } from '@pixi/tilemap';
import { Loader } from '@pixi/loaders';

// Add the spritesheet into your loader!
Loader.shared.add('atlas', 'assets/atlas.json');

// Make the tilemap once the tileset assets are available.
Loader.shared.load(function onTilesetLoaded() {
    // The base-texture is shared between all the tile textures.
    const tilemap = new Tilemap([Texture.from('grass.png').baseTexture])
        .tile('grass.png', 0, 0)
        .tile('grass.png', 100, 100)
        .tile('brick_wall.png', 0, 100);
});

Extends: Container

Members

shadowColor

Currently doesnt work.

tileAnim [number, number]

The tile animation frame.

Default Value: undefined

See: tileAnim

hasAnimatedTile boolean (protected)

Flags whether any animated tile was added.

Default Value: false

tilemapBounds (protected, readonly)

The local bounds of the tilemap itself. This does not include DisplayObject children.

tileset (protected)

The list of base-textures being used in the tilemap.

This should not be shuffled after tiles have been added into this tilemap. Usually, only tile textures should be added after tiles have been added into the map.

Methods

addFrame (texture, x, y, animX, animY) boolean -- Deprecated`` : Since @pixi/tilemap 3.

Deprecated signature for tile.

Name	Type	Description
texture	Texture | string	number
x	number
y	number
animX	number
animY	number

Returns: boolean

addRect (textureIndex, u, v, x, y, tileWidth, tileHeight, animX, animY, rotate, animCountX, animCountY, animDivisor, alpha) this Deprecated`` : Since @pixi/tilemap 3.

Name	Type	Default	Description
textureIndex	number
u	number
v	number
x	number
y	number
tileWidth	number
tileHeight	number
animX	number	0
animY	number	0
rotate	number	0
animCountX	number	1024
animCountY	number	1024
animDivisor	number	1
alpha	number	1

Returns: this

clear ()

Clears all the tiles added into this tilemap.

Returns: this

destroy (options)

Name	Type	Attributes	Description
options	DestroyOptions

Returns: void

getTileset ()

Returns:

Type	Description
TileTextureArray	The tileset of this tilemap.

setTileset (textureOrArray)

Define the tileset used by the tilemap.

Name	Type	Description
textureOrArray	TileTextureArray | TextureSource	Array	The list of textures to use in the tilemap. If a base-texture (not array) is passed, it will be wrapped into an array. This should not contain any duplicates.

Returns: this

tile (tileTexture, x, y, options)

Adds a tile that paints the given texture at (x, y).

Returns: this

Name	Type	Attributes	Default	Description
tileTexture	number | string	Texture	TextureSource	The tiling texture to render.
x	number			The local x-coordinate of the tile's position.
y	number			The local y-coordinate of the tile's position.
options	{ u?: number, v?: number, tileWidth?: number, tileHeight?: number, animX?: number, animY?: number, rotate?: number, animCountX?: number, animCountY?: number, animDivisor?: number, alpha?: number}			Additional tile options.
options.u			texture.frame.x	The x-coordinate of the texture in its base-texture's space.
options.v			texture.frame.y	The y-coordinate of the texture in its base-texture's space.
options.tileWidth			texture.orig.width	The local width of the tile.
options.tileHeight			texture.orig.height	The local height of the tile.
options.animX			0	For animated tiles, this is the "offset" along the x-axis for adjacent animation frame textures in the base-texture.
options.animY			0	For animated tiles, this is the "offset" along the y-axis for adjacent animation frames textures in the base-texture.
options.rotate			0
options.animCountX			1024	For animated tiles, this is the number of animation frame textures per row.
options.animCountY			1024	For animated tiles, this is the number of animation frame textures per column.
options.animDivisor			1	For animated tiles, this is the animation duration of each frame
options.alpha			1	Tile alpha

tileAnimDivisor (divisor) void

Changes the animDivisor value of the last tile.

Name	Type	Description
divisor	number

tileAnimX (offset, count) void

Changes the animX, animCountX of the last tile.

Name	Type	Description
offset	number
count	number

tileAnimY (offset, count) void

Changes the animY, animCountY of the last tile.

tileRotate (rotate) void

Changes the rotation of the last tile.

Name	Type	Description
rotate	number

CompositeTilemap

A tilemap composite that lazily builds tilesets layered into multiple tilemaps.

The composite tileset is the concatenation of the individual tilesets used in the tilemaps. You can preinitialized it by passing a list of tile textures to the constructor. Otherwise, the composite tilemap is lazily built as you add more tiles with newer tile textures. A new tilemap is created once the last tilemap has reached its limit (as set by texturesPerTilemap).

Extends: Container

new CompositeTilemap (tileset)

Name	Type	Attributes	Description
tileset	Array		A list of tile base-textures that will be used to eagerly initialized the layered tilemaps. This is only an performance optimization, and using tile will work equivalently.

Example

 import { Application } from '@pixi/app';
 import { CompositeTilemap } from '@pixi/tilemap';
 import { Loader } from '@pixi/loaders';

 // Setup view & stage.
 const app = new Application();

 document.body.appendChild(app.renderer.view);
 app.stage.interactive = true;

 // Global reference to the tilemap.
 let globalTilemap: CompositeTilemap;

 // Load the tileset spritesheet!
 Loader.shared.load('atlas.json');

 // Initialize the tilemap scene when the assets load.
 Loader.shared.load(function onTilesetLoaded()
 {
      const tilemap = new CompositeTilemap();

      // Setup the game level with grass and dungeons!
      for (let x = 0; x < 10; x++)
      {
          for (let y = 0; y < 10; y++)
          {
              tilemap.tile(
                  x % 2 === 0 && (x === y || x + y === 10) ? 'dungeon.png' : 'grass.png',
                  x * 100,
                  y * 100,
              );
          }
      }

      globalTilemap = app.stage.addChild(tilemap);
 });

 // Show a bomb at a random location whenever the user clicks!
 app.stage.on('click', function onClick()
 {
      if (!globalTilemap) return;

      const x = Math.floor(Math.random() * 10);
      const y = Math.floor(Math.random() * 10);

      globalTilemap.tile('bomb.png', x * 100, y * 100);
 });

Members

setBitmaps -- Deprecated : Since @pixi/tilemap 3.

Alias for tileset.

texPerChild number -- Deprecated : Since @pixi/tilemap 3. readonly

See: texturesPerTilemap

texturesPerTilemap number readonly

The hard limit on the number of tile textures used in each tilemap.

tileAnim [number, number]

The animation frame vector.

Animated tiles have four parameters - animX, animY, animCountX, animCountY. The textures of adjacent animation frames are at offset animX or animY of each other, with animCountX per row and animCountY per column.

The animation frame vector specifies which animation frame texture to use. If the x/y coordinate is larger than the animCountX or animCountY for a specific tile, the modulus is taken.

Default Value: undefined

lastModifiedTilemap Tilemap protected

The last modified tilemap.

Default Value: undefined

Methods

addFrame (texture, x, y, animX, animY, animWidth, animHeight, animDivisor, alpha) this Deprecated`` : Since @pixi/tilemap 3.

Name	Type	Attributes	Description
texture	Texture | string	number
x	number
y	number
animX	number
animY	number
animWidth	number
animHeight	number
animDivisor	number
alpha	number

See: tile

Returns: this

addRect (textureIndex, u, v, x, y, tileWidth, tileHeight, animX, animY, rotate, animWidth, animHeight) this Deprecated`` : @pixi/tilemap 3

Name	Type	Attributes	Description
textureIndex	number
u	number
v	number
x	number
y	number
tileWidth	number
tileHeight	number
animX	number
animY	number
rotate	number
animWidth	number
animHeight	number

See: tile

Returns: this

clear ()

Clears the tilemap composite.

Returns: this

tile (tileTexture, x, y, options)

Adds a tile that paints the given tile texture at (x, y).

Returns: this

Name	Type	Attributes	Default	Description
tileTexture	Texture | string	number			The tile texture. You can pass an index into the composite tilemap as well.
x	number			The local x-coordinate of the tile's location.
y	number			The local y-coordinate of the tile's location.
options	{ u?: number, v?: number, tileWidth?: number, tileHeight?: number, animX?: number, animY?: number, rotate?: number, animCountX?: number, animCountY?: number, animDivisor?: number, alpha?: number}			Additional options to pass to tile.
options.u			texture.frame.x	The x-coordinate of the texture in its base-texture's space.
options.v			texture.frame.y	The y-coordinate of the texture in its base-texture's space.
options.tileWidth			texture.orig.width	The local width of the tile.
options.tileHeight			texture.orig.height	The local height of the tile.
options.animX			0	For animated tiles, this is the "offset" along the x-axis for adjacent animation frame textures in the base-texture.
options.animY			0	For animated tiles, this is the "offset" along the y-axis for adjacent animation frames textures in the base-texture.
options.rotate			0
options.animCountX			1024	For animated tiles, this is the number of animation frame textures per row.
options.animCountY			1024	For animated tiles, this is the number of animation frame textures per column.
options.animDivisor			1	For animated tiles, this is the animation duration each frame
options.alpha			1	Tile alpha

tileAnimDivisor (divisor)

Changes tileAnimDivisor value of the last added tile.

Name	Type	Description
divisor	number

Returns: this

tileAnimX (offset, count)

Changes animX, animCountX of the last added tile.

Name	Type	Description
offset	number
count	number

Returns: this

tileAnimY (offset, count)

Changes animY, animCountY of the last added tile.

Returns: this

tileRotate (rotate)

Changes the rotation of the last added tile.

Name	Type	Description
rotate	number

Returns: this

tileset (tileTextures)

This will preinitialize the tilesets of the layered tilemaps.

If used after a tilemap has been created (or a tile added), this will overwrite the tile textures of the existing tilemaps. Passing the tileset to the constructor instead is the best practice.

Name	Type	Description
tileTextures	Array	The list of tile textures that make up the tileset.

Returns: this

GlTilemapAdaptor

Extends TilemapAdaptor

new GlTilemapAdaptor();

GpuTilemapAdaptor

Extends TilemapAdaptor

new GpuTilemapAdaptor();

TilemapPipe

Rendering helper pipeline for tilemaps. This plugin is registered automatically.

Implements

• RenderPipe
• InstructionPipe

Members

renderer Renderer readonly

The managing renderer

tileAnim

The tile animation frame

Methods

getShader () TilemapGeometry

Returns:

Type	Description
TilemapGeometry	The TilemapGeometry shader that this rendering pipeline is using.