Class: Spritesheet

Spritesheet

Utility class for maintaining reference to a collection of Textures on a single Spritesheet.

To access a sprite sheet from your code you may pass its JSON data file to Pixi's loader:

import { Assets } from 'pixi.js';

const sheet = await Assets.load('images/spritesheet.json');

Alternately, you may circumvent the loader by instantiating the Spritesheet directly:

import { Spritesheet } from 'pixi.js';

const sheet = new Spritesheet(texture, spritesheetData);
await sheet.parse();
console.log('Spritesheet ready to use!');

With the sheet.textures you can create Sprite objects, and sheet.animations can be used to create an AnimatedSprite.

Here's an example of a sprite sheet JSON data file:

{
    "frames": {
        "enemy1.png":
        {
            "frame": {"x":103,"y":1,"w":32,"h":32},
            "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
            "sourceSize": {"w":32,"h":32},
            "anchor": {"x":16,"y":16}
        },
        "enemy2.png":
        {
            "frame": {"x":103,"y":35,"w":32,"h":32},
            "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
            "sourceSize": {"w":32,"h":32},
            "anchor": {"x":16,"y":16}
        },
        "button.png":
        {
            "frame": {"x":1,"y":1,"w":100,"h":100},
            "spriteSourceSize": {"x":0,"y":0,"w":100,"h":100},
            "sourceSize": {"w":100,"h":100},
            "anchor": {"x":0,"y":0},
            "borders": {"left":35,"top":35,"right":35,"bottom":35}
        }
    },

    "animations": {
        "enemy": ["enemy1.png","enemy2.png"]
    },

    "meta": {
        "image": "sheet.png",
        "format": "RGBA8888",
        "size": {"w":136,"h":102},
        "scale": "1"
    }
}

Sprite sheets can be packed using tools like TexturePacker, Shoebox or Spritesheet.js. Default anchor points (see Texture#defaultAnchor), default 9-slice borders (see Texture#defaultBorders) and grouping of animation sprites are currently only supported by TexturePacker.

Alternative ways for loading spritesheet image if you need more control:

import { Assets } from 'pixi.js';

const sheetTexture = await Assets.load('images/spritesheet.png');
Assets.add({
    alias: 'atlas',
    src: 'images/spritesheet.json',
    data: {texture: sheetTexture} // using of preloaded texture
});
const sheet = await Assets.load('atlas')

or:

import { Assets } from 'pixi.js';

Assets.add({
    alias: 'atlas',
    src: 'images/spritesheet.json',
    data: {imageFilename: 'my-spritesheet.2x.avif'} // using of custom filename located in "images/my-spritesheet.2x.avif"
});
const sheet = await Assets.load('atlas')

new Spritesheet (texture, data)

ts:256

Name	Type	Description
`texture`	BindableTexture	Reference to the source BaseTexture object.
`data`	object	Spritesheet image data.

Members

BATCH_SIZE number staticreadonly

The maximum number of Textures to build per process.

Default Value:

1000

animations Record<keyof, Texture[]>

A map containing the textures for each animation. Can be used to create an AnimatedSprite:

Example

 import { AnimatedSprite } from 'pixi.js';

 new AnimatedSprite(sheet.animations['anim_name']);

data object

Reference to the original JSON data.

linkedSheets Spritesheet<S>[]

For multi-packed spritesheets, this contains a reference to all the other spritesheets it depends on.

resolution number

The resolution of the spritesheet.

textures Record<keyof, Texture>

A map containing all textures of the sprite sheet. Can be used to create a Sprite:

Example

 import { Sprite } from 'pixi.js';

 new Sprite(sheet.textures['image.png']);

textureSource TextureSource

Reference to ths source texture.

Methods

destroy (destroyBase) void

ts:433

Destroy Spritesheet and don't use after this.

Name	Type	Attributes	Default	Description
`destroyBase`	boolean	<optional>	false	Whether to destroy the base texture as well

parse () Promise<Texture<string, Record>>

ts:286

Parser spritesheet from loaded data. This is done asynchronously to prevent creating too many Texture within a single process.

Returns:

Type	Description
Promise<Texture<string, Record>>