Introduction To Sprites

Sprites

Babylon.js has three ways of managing sprites, the SpriteManager, the SpritePackedManager and the SpriteMap. The first manages a single image file or, for animation, a spritesheet (also called a sprite atlas) of multiple sprite images all of the same size. The second is for a packed spritesheet of different sized sprite images. The third uses a packed spritesheet to form a 2D (or 2.5D) grid of possibly thousands of sprites.

The separate images in a spritesheet off either type are in what are called cells.

The brief overviews on this page are further detailed within this section.

Sprite Manager

For a single sprite image or uniform spritesheet you create a sprite manager.

const mySpriteManagerTrees = new BABYLON.SpriteManager(name, url, capacity, size, scene); //scene is optional and defaults to the current scene

• name - (string) manager name;
• url - (string) path to the image/spritesheet url;
• capacity (number) maximum number of sprite instances in this manager;
• size ({width: number, height: number} | number), width and height or size of a sprite or a cell within a spritesheet;
• scene (scene) optional

Sprite Packed Manager

Available from BJS version 4.1

When your sprites images are of varying sizes you need a packed spritesheet file and a JSON file containing the positional data of the individual sprites within the packed spritesheet. The packed spritesheet file and the JSON file should have the same name and be in the same folder, eg pack1.png and pack1.json. You can then create a sprite packed manager by either

referencing just the packed spritesheet file

const mySpritePackedManager = new BABYLON.SpritePackedManager(name, spritesheet url, capacity, scene); //scene is optional and defaults to the current scene

or a packed spritesheet file and an appropriate JSON object

const spm = new BABYLON.SpritePackedManager(name, spritesheet url, capacity, scene, atlasJSON);

• name - (string) manager name;
• url - (string) path to the spritesheet url;
• capacity (number) maximum number of sprite instances in this manager;
• scene (scene) optional unless the following parameter is used
• JSONpack (JSON object) optional

Currently the sprite packed manager only uses the cell positional and cell size data from the packed spritesheet.

Sprite Map

Available from BJS version 4.1

When creating a 2D or 2.5D game you often need to render thousands of animated sprites on screen fast. This is beyond the capabilities of either of the sprite managers. The Babylon.js SpriteMap was made for use in this situation. The only current limitation of this sprite mapping system is that the positions of the sprites are static to a specific grid dictated by the Sprite Maps initializing parameters.

Note: SpriteMap uses a different JSON format to SpritePackedManager and so their files are not interchangeable. Also you need to create a texture from the packed spritesheet and pass this rather than a direct path to its url.

To create a SpriteMap is simple:

const mySpriteMap = new BABYLON.SpriteMap(name, atlasJSON, spriteSheetTexture, options, scene);

• name - (string) manager name;
• atlasJSON (JSON object) referencing the packed spritesheet;
• spriteTexture - (texture) a texture created from a packed spritesheet;
• options (number) initializing options;
• scene (scene) REQUIRED

The initializing options set up the data buffers in memory and get the system prepared for display. When making changes to any of the options it is recommended that you dispose the map and re-initialize with the correct options.