
## Sprite Packed Manager
*Available from BJS version 4.1*

A packed spritesheet will look something like this

![Packed Spritesheet](/img/how_to/Sprites/pack1.png);

with sprite cells of different sizes arranged to optimize the file size.

The corresponding JSON file will have the format which is based on that produced using the _TexturePacker_ app with output file framework set to JSON Hash format and Trim to None and Allow Rotation to Off. A frame is another way of talking about a cell.

```javascript
{   "frames": {
		"eye.png": {
			"frame": {"x":0,"y":148,"w":400,"h":400},
			"rotated": false,
			"trimmed": false,
			"spriteSourceSize": {"x":0,"y":0,"w":400,"h":400},
			"sourceSize": {"w":400,"h":400}
		},
		"redman.png": {
			"frame": {"x":0,"y":0,"w":55,"h":97},
			"rotated": false,
			"trimmed": false,
			"spriteSourceSize": {"x":0,"y":0,"w":55,"h":97},
			"sourceSize": {"w":55,"h":97}
			},
		"spot.png": {
			"frame": {"x":199,"y":0,"w":148,"h":148},
			"rotated": false,
			"trimmed": false,
			"spriteSourceSize": {"x":0,"y":0,"w":148,"h":148},
			"sourceSize": {"w":148,"h":148}
		},
		"triangle.png": {
			"frame": {"x":55,"y":0,"w":144,"h":72},
			"rotated": false,
			"trimmed": false,
			"spriteSourceSize": {"x":0,"y":0,"w":144,"h":72},
			"sourceSize": {"w":144,"h":72}
		}
	},
	"meta": {
		"app": "https://www.codeandweb.com/texturepacker",
		"version": "1.0",
		"image": "pack1.png",
		"format": "RGBA8888",
		"size": {"w":400,"h":548},
		"scale": "1",
		"smartupdate": "$TexturePacker:SmartUpdate:c5944b8d86d99a167f95924d4a62d5c3:3ed0ae95f00621580b477fcf2f6edb75:5d0ff2351eb79b7bb8a91bc3358bcff4$"
	}
}
```

**Note:** *SpriteMap* uses the JSON Array format for packed spritesheets. JSON files are not interchangeable between *SpritePackedManager* and *SpritMap*.

The minimal format required by *SpritePackedManager* is below. Although currently it only uses the frame property it may be able to use others in the future. 

```javascript
{   "frames": {
		"eye.png": {
			"frame": {"x":0,"y":148,"w":400,"h":400}
		},
		"redman.png": {
			"frame": {"x":0,"y":0,"w":55,"h":97}
			},
		"spot.png": {
			"frame": {"x":199,"y":0,"w":148,"h":148}
		},
		"triangle.png": {
			"frame": {"x":55,"y":0,"w":144,"h":72}
		}
	}
}
```
Reminder the above minimal format is only suitable for the *SpritePackedManager*.

When you create a sprite instance using the packed manager you refer to the cell (frame) to use by its name rather than its index number.

The above JSON is stored in the file *pack1.json* 
```javascript
const mySpritePackedManager = new BABYLON.SpritePackedManager("spm", "textures/pack1.png", 4);

const sprite = new BABYLON.Sprite("sprite", mySpritePackedManager);
sprite.cellRef = "spot.png";
```

Multiple sprites from *pack1.json<Playground id="#YCY2IL#8" title="Multiple Sprites From 1 .json File" description="Simple example of loading multiple sprites from one .json file."/>

The same as for the sprite manager you can apply the following properties,

```javascript
sprite.width = 0.3;
sprite.height = 0.4;
sprite.position =new BABYLON.Vector3(1, 1, 1);
sprite.angle = Math.PI/4;
sprite.invertU = true; //vertical reflection
sprite.invertV = true; //horizontal reflection
```


You are able to animate using a packed spritesheet with *playAnimation*. You must ensure that the frames for the animation are consecutive and in the correct order in the JSON file.

Slide show animation from JSON file: <Playground id="#YCY2IL#5" title="Slide Show From .json" description="Simple example of a slide show loaded from a .json file."/>
Slide show animation with in-line JSON to show order of slides: <Playground id="#YCY2IL#13" title="Slide Show Animation With In-Line .json" description="Simple example of a slide show animation with in-line .json."/>


## Picking
Sprites managed by either the sprite or packed manager can be selected, or picked, provided both the sprite and the manager are set to pickable. This is done as follows

```javascript
mySpriteManager.isPickable = true;
mySpritePackedManager.isPickable = true;
mySprite.isPickable = true;
```

To do so, you need to:
- Turn on picking on the sprites you want: `sprite.isPickable = true;`
- Enable SpriteManager to support picking: `spriteManager.isPickable = true;`

To do picking you can use the `scene.pickSprite`:

```
var pickResult = scene.pickSprite(this.pointerX, this.pointerY);
if (pickResult.hit) {
	pickResult.pickedSprite.angle += 0.5;
}
```

Pick and rotate selected sprite with sprite manager: <Playground id="#YCY2IL#9" title="Pick And Rotate A Selected Sprite" description="Simple example of picking a sprite and rotating it." isMain={true} category="Sprites"/>
Pick and rotate selected sprite with sprite packed manager: <Playground id="#YCY2IL#10" title="Pick and Rotate A Selected Sprite With Sprite Packed Manager" description="Simple example of selecting a sprite from a sprite packed manager and rotating it."/>

For performance reasons the default is to indicate a hit if the sprite is picked within its bounding rectangle. When you do not want a hit inside a transparent region of the sprite you need to add the following
```javascript
mySprite.useAlphaForPicking = true;
```
and picking will only work if alpha > 0.5.

Transparent regions not reacting to pick: <Playground id="#YCY2IL#11" title="Transparent Regions No Picking" description="Simple example showing how you cannot pick transparent regions of sprites."/>


Where sprites are overlapping you can use *multiPickSprite* to get all the sprites under the mouse:

```
const pickResult = scene.multiPickSprite(this.pointerX, this.pointerY);
for (let i = 0; i < pickResult.length; i++) {
    	pickResult[i].pickedSprite.angle += Math.PI / 4;
}
```

multipicking of overlapping sprites: <Playground id="#YCY2IL#12" title="Multipicking Overlapping Sprites" description="Simple example of multipicking of overlapping sprites."/>


## Sprite Manager

Take a single sprite image example, i.e. just one cell.

![palm tree](/img/getstarted/palmtree.png)

Using an image format which contain alpha channel for transparency, like .png, allows complex shapes to be displayed.

Create the sprite manager for the trees
```javascript
const spriteManagerTrees = new BABYLON.SpriteManager("treesManager", path to palm.png, 2000, {width: 512, height: 1024});
```
Drawing sprites just uses a name and the sprite manager linking to the sprite image. For an accurately scaled representation of the image the width and height of the sprite should be in the same ratio as the sprite image.
```javascript
const tree = new BABYLON.Sprite("tree", spriteManagerTrees); 
tree.width = 1;
tree.height = 2;
```

single sprite image <Playground id="#YCY2IL" title="Single Sprite Image" description="Simple example of a single sprite image." isMain={true} category="Sprites"/>

You can alter the cell width and height after creation using these properties *mySpriteManager.cellWidth* and *mySpriteManager.cellWidth*

with single image size altered <Playground id="#YCY2IL#1" title="Single Sprite Image Altered" description="Simple example of a single sprite image altered."/>
multiple trees <Playground id="#YCY2IL#2" title="Multiple Sprites Example" description="Simple example of multiple sprites."/>

As well as width and height you can apply the following properties,

```javascript
sprite.position =new BABYLON.Vector3(1, 1, 1);
sprite.angle = Math.PI/4;
sprite.invertU = true; //vertical reflection
sprite.invertV = true; //horizontal reflection
```

Please note that the z-axis position of a sprite will affect its size on the screen, i.e, sprites with a higher z-axis value will appear farther away and such, will be smaller on the screen: <Playground id="#YCY2IL#811" title="Sprite size affected by z position" description="An example of how the z axis position affects a sprite size."/>

A spritesheet example

![uniform spritesheet](/img/how_to/Sprites/08-2.png)

There are 44 cells in the above spritesheet, each one 64 x 64 pixels. Since the cells are square you can just use  the cell size rather than its width and height. Create the sprite manager with
```javascript
const spriteManagerPlayer = new BABYLON.SpriteManager("playerManager","path to Player.png", 1, 64);
```
which can then be use to produce just one sprite instance.

```javascript
const player = new BABYLON.Sprite("player", spriteManagerPlayer); 
player.cellIndex = 1;
```
![Elements](/img/how_to/Sprites/08-1.png)

Since the cells are square the default values for player width and height are 1 and the ratio is correct they are not needed. However the if the sprite is to draw from a cell with index other than 0 it must be specified.

Sprites from different cells: <Playground id="#YCY2IL#3" title="Sprites From Different Cells" description="Simple example of sprites from different cells" isMain={true} category="Sprites"/>

It is by changing of cell numbers that you produce a sprite animation.

To begin an animation, use:
```javascript
mySprite.playAnimation(start cell, end cell, loop, delay);
```
The sprite will be animated from the start cell to the end cell. when *loop* is set to true the animation will loop. The delay is the time delay between the frames of the animation (the smaller it is, the faster the animation). The cells must be in animation frame order.

Sprite animation: <Playground id="#YCY2IL#4" title="Sprite Animation" description="Simple example of how to handle sprite animation." isMain={true} category="Sprites"/>



## Sprite Map 
*Available from BJS version 4.1*

A sprite map allows you to display layers of sprites on a grid and can render thousands (dare I say millions?) of animated sprites on screen.  A large area of use, as used in this section, is in 2D and 2.5D games but other applications can also benefit. The only current limitation of this system is that the positions of the sprites are static within the grid and are dictated by the sprite map's initializing parameters. 

A  sprite map is displayed on a standard plane mesh in 3D space. and has the ability to be transformed in 3d space.  The speed of rendering is based on the the use of texture buffers and each map only requires one draw call.

Since the plane is split into a grid of tiles of the same size the cells of the packed spritesheet should be of the same size.

It uses the full JSON Array format of _TexturePacker_ and benefits from using the properties, rotation, extrude and padding.  *Soon the trim support will be functional as well*

**Note:** *SpritePackedManager* uses the JSON Hash format for packed spritesheets. JSON files are not interchangeable between *SpritePackedManager* and *SpritMap*.

![spritesheet](/img/how_to/Sprites/legends.png)

The start of the JSON file format for the above packed spritesheet is shown below.

```json
{
    "frames": [
        {
	        "filename": "blank.png",
	        "frame": {"x":221,"y":221,"w":1,"h":1},
	        "rotated": false,
	        "trimmed": false,
	        "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
	        "sourceSize": {"w":32,"h":32}
        },
        {
	        "filename": "Falling-Water-0.png",
	        "frame": {"x":1,"y":1,"w":32,"h":32},
	        "rotated": false,
	        "trimmed": false,
	        "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
	        "sourceSize": {"w":32,"h":32}
        },
        {
	        "filename": "Falling-Water-1.png",
	        "frame": {"x":1,"y":36,"w":32,"h":32},
	        "rotated": false,
	        "trimmed": false,
	        "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
	        "sourceSize": {"w":32,"h":32}
        },
        . . . . . . 
        . . . . . .

        {
	        "filename": "Torch-A-3.png",
	        "frame": {"x":141,"y":211,"w":32,"h":32},
	        "rotated": false,
	        "trimmed": false,
	        "spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
	        "sourceSize": {"w":32,"h":32}
        }
    ]
}
```
The complete JSON file can be found on the Github [Babylon.js repository](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/playground/textures/spriteMap/none_trimmed/Legends_Level_A.json)

First we will start with a background that uses a 2 x 2 grid of tiles and just 4 sprites.


```javascript
let backgroundSize = new BABYLON.Vector2(2, 2); //set the size of the sprite map stage
```

Once the altlas JSON and the spritesheet texture have been loaded we can create the sprite map, setting two of the options parameter properties
```javascript
let background = new BABYLON.SpriteMap('background', atlasJSON, spriteSheet,
    {
        stageSize: backgroundSize,
        flipU: true//, //Sometimes you need to flip, depending on the sprite format.
    },
    scene
);
```

One the sprite map is created sprites are assigned to the tiles, in the grid, by their frameID, their index in the frames array. 

For simplicity and variation we choose indices 9, 18, 27 and 26 for the frameIDs
```javascript
for(let i = 0; i < 4; i++){
    background.changeTiles(0, new BABYLON.Vector2(i % 2, Math.floor(i / 2)), 9 * i + 9)
}
```
The parameters are

- _layerID_ - _(number)_ the index of sprite map layer
- _tileID_ - _(Vector2 | Vector2[])_ Vector2 identifies tile by its x position across and y position up
- _frameID_ - _(number)_ the index number in the frames array


A 2 x 2 single layer sprite map, JSON loaded from file: <Playground id="#YCY2IL#14" title="Single Layer Sprite Map From A File" description="Simple example of a 2x2 single layer sprite map loaded from a .json file."/>

Once created you can export the sprite map to save it and then load it into another sprite sheet of the same structure.

## Saving a Sprite Map
After you have created a sprite map you can export this composition for later use, with

```javascript
mySpriteMap.saveTileMaps()
```
creating a *.tilemaps* file.

When importing it you must make sure that the sprite map you are importing it into has the same tile layout and number of layers as the one it was exported from.  You import it with

```javascript
spriteMap.loadTileMaps(url); //url is the location of the .tilemaps file
```


## Sprite Map Animations
A sprite map animation is created, as you would expect, from a sequence of frameIDs from the frames array. The sequence does not have to be in consecutive order of frameIDs. For example, animation frame 0 could draw the sprite from frameID 19 and animation frame 1 could draw the sprite from frameID 6. Also each animation frame can have its own independent timing.

The terms of frame and animation frame are not to be confused.  Frame is a reference to the position of the sprite on the atlas, and the animation frame is the specific frame that is being displayed at that moment

One limitation is that you can have only one animation sequence assigned per frame.  This does not limit you though, as you can make duplicate frame references in your JSON file and then just assign a different animation to the added frame.

All animations are assumed to be looping though they may all have different timings globally and per animation frame.

![sprite map animation](/img/how_to/Sprites/water_anim.png)

Lets assume their frameIDs in order are 24, 25, 26, 27, 28, 29, 30 and 31 and we want to play them in this order. We start with frameID 24 and add this to the tiles, or rather any tile that contains frameID 24 will show the animation.

In order for the animation to run we must set the *maxAnimationFrames* options property. In this case their are 8 frames

```javascript
let backgroundSize = new BABYLON.Vector2(1, 1);
let background = new BABYLON.SpriteMap('background', atlasJSON, spriteSheet, {
    stageSize: backgroundSize,
    maxAnimationFrames:8,
    flipU: true
    },
    scene); 

background.changeTiles(0, new BABYLON.Vector2(0, 0), 24); // set the single tile to frameID 24
```

We want the animation to change frames every eighth of a second, 1 / 8.  
After 1 eighth of a second we want frameID 24 to become frameID 25,  
after 2 eights of a second we want frameID 24 to become frameID 26,  
after 3 eights of a second we want frameID 24 to become frameID 27,  
and so on

We can slow or speed up the timing change by adding a speed factor, giving

```javascript
let eighth = 1 / 8
let speed = 0.005
background.addAnimationToTile(24, 0, 25, eighth * 1, speed);
background.addAnimationToTile(24, 1, 26, eighth * 2, speed);
background.addAnimationToTile(24, 2, 27, eighth * 3, speed);
background.addAnimationToTile(24, 3, 28, eighth * 4, speed);
background.addAnimationToTile(24, 4, 29, eighth * 5, speed);
background.addAnimationToTile(24, 5, 30, eighth * 6, speed);
background.addAnimationToTile(24, 6, 31, eighth * 7, speed);
background.addAnimationToTile(24, 7, 24, 1, 	 	 speed);
```

Single tile animation: <Playground id="#YCY2IL#26" title="Single Tile Animation" description="Simple example of single tile animation."/>

More generally to create an animation use
```javascript
spriteMap.addAnimationToTile(frameID, animationFrame, nextFrameID, animationFrameDisplayTiming, globalSpeed)
```
* frameID: Integer ID of the sprite frame to assign the animation to.
* animationFrame: Integer ID of the animation frame to assign data to.
* nextFrameID:  Integer ID of the next sprite frame in the animation.
* animationFrameDisplayTiming: Float between 0-1 of when the animation frame will be displayed.  This will be described more below.
* globalSpeed: Float scalar of the speed of the animation.

Each Sprite Map has a timing value being passed to the shader that displays it.  In the shader it modulates the time value between 0-1 essentially looping the time at a set rate.  Each tile looks to see if it has animation data assigned and then check if it is on the correct animation frame for that time.  This is determined by checking if the animation frames display timing value is below the modulated time.  This time value is further controlled by scalar that can speed up or slow down the animation across all its animation frames.

Fortunately you only have to compose the animations once if multiple SpriteMaps use the same data, you can just pass the animation map to the system directly from another and it will propagate all the animations over.

```javascript
spriteMap1.animationMap = spriteMap0.animationMap
```


## Sprite Map Multi-Plane Example
We are going to build a scene with a far distance, mid distance and near distance sprite map. The far and mid distance levels will be built following the methods examined earlier in the section. The near distance level is loaded from a pre-created sprite map that has been made and saved. A blank tile is added to the front of the frames array.

## Far Distance Level
Large parts of this, background, sprite map will be hidden by those in the mid and near distance. It contains all the animations that will be used by this sprite map and the others.

The steps for this are: create and set the background sprite map; the animations; position in the far distance, z = -5; and assign frameIDs to tiles.

Far distance sprite map <Playground id="#YCY2IL#25" title="Far Distance Sprite Map" description="Simple example of a far distance sprite map."/>

## Mid Distance Level
The steps for this are: create and set the levelBase sprite map and assign frameIDs to tiles, includinh using blank tiles to create a hole through which the far distance level can be seen. The default is mid distance with position with z = 0; In the complete example this line

```javascript
levelBase.animationMap = background.animationMap
```
will be added to copy the animation map to animated the frames in levelBase.

Mid distance sprite map: <Playground id="#YCY2IL#23" title="Mid Distance Sprite map" description="Simple example of a mid distance sprite map."/>

## Near Distance Level
The near distance map is an example of loading a pre-created and exported sprite map.

The steps for this are: create and set the levelStage sprite map with a structure matching the one to be imported; load the *.tilemap* file; and position in the near distance, z = 5.

Near distance sprite map: <Playground id="#YCY2IL#28" title="Near Distance Sprite Map" description="Simple example of a near distance sprite map." image="/img/playgroundsAndNMEs/pg-YCY2IL-28.png"/>

## Complete Example
The three distance levels are now combined into one, the camera is changed to a universal one and positioned so that the levels fill the screen. The copy of the background animation map is copied over to the levelBase sprite map.

Complete example: <Playground id="#YCY2IL#29" title="Complete Sprite Map Example" description="Complete example of a sprite map."/>


## Sprite Map Options
The options parameter object, when creating a sprite map, contains a number of properties
```javascript
const spriteMap = new BABYLON.SpriteMap(name, atlasJSON, spriteTexture, options, scene);
```

Each of the options properties helps the sprite map reserve the proper data buffers in memory and get the system prepared for display. 

* stageSize: A Vector2 of the number of "tiles" in the system - default : Vector2(1,1)
* outputSize: A Vector2 of size of the output plane in World Units - default : Vector2(1,1)
* outputPosition: A Vector3 of position of the output plane in World Units - default : Vector3.Zero
* outputRotation: A Vector3 of rotation of the output plane in World Units - default : Vector3.Zero
* layerCount: A Integer of the number of "layers" in the system - default : 1
* maxAnimationFrames: The maximum number of frames in any animation on the sheet - default : 0
* baseTile: The frame ID of the initial tile to propagate into the system - default : 0
* flipU: A Boolean flag to trigger flipping the vertical results of the spite after framing calculations - default : false
* colorMultiply: A Vector3 that will multiply the final color value of the map - default : Vector3(1,1,1)

After initialization you can change the rotation and position of the output plane by referencing the spriteMaps.position | rotation like a standard mesh.  For any other option change (like stageSize, or layerCount etc...) its recommended that you dispose the map and re-initialize with the correct options.

## Examples of Option Properties
base tile used to fill whole grid: <Playground id="#YCY2IL#16" title="Base Tile Used To Fill Whole Grid" description="Simple example of a base tile used to fill a whole grid."/>
outputSize changes size and ratio of plane: <Playground id="#YCY2IL#17" title="OutputSize Changes Size And Ratio Of Plane" description="Simple example showing outputSize changing the size and ratio of a plane."/>
two layers individual sprites in layer 1 on top of base tile in layer 0: <Playground id="#YCY2IL#18" title="Two Layre Individual Sprites" description="Simple example of two layers individual sprites in layer 1 on top of base tile in layer 0."/>
color multiplied by red: <Playground id="#YCY2IL#19" title="Color Multipled By Red" description="Simple example of color multiplied by red."/>


## Sprite Map Tile Layout

Each sprite map is comprised of tiles of equal size, filling the output plane and forming a grid. Tiles are identified by their position on the grid. For 36 tiles laid out in 9 rows with 4 columns in each; (0, 0) is the bottom left hand corner tile and (3, 8) the top right hand corner tile. Tiles can be placed on top of one another in layers - more on layers later.

```javascript
tileID = new Vector2(2, 6);
```

Given the frameID (index in frames array) you can set one or more tiles to contain the sprite referenced by this frameID
```javascript
spriteMap.changeTiles(layerID, tileID, frameID) //Change one tile
spriteMap.changeTiles(layerID, [tileID0, tileID1, ... tileIDn], frameID); //Change multiple tiles to sprite at frameID
```

When you are going to make multiple changes using just one frameID then passing the tileIDs in an array is optimal. It prevents the buffers having to be updated for each tile instead of in batches. 

Change a whole row of stones to Roman columns <Playground id="#YCY2IL#20" title="Sprite Map Tile Layout" description="Simple example showing sprite map tile layouts."/>

You will often find the need for a blank tile. We recommend that you find a single transparent pixel on your packed spritesheet file You can reference this in JSON file.  

In the spritesheet file used in these docs there is a transparent pixel at x = 221, y = 221 so we make a cell frame of width = height = 1 and maintain the same source sizes as the other frames. Adding the following to your JSON gives a blank tile.
```
{
	"filename": "blank.png",
	"frame": {"x":221,"y":221,"w":1,"h":1},
	"rotated": false,
	"trimmed": false,
	"spriteSourceSize": {"x":0,"y":0,"w":32,"h":32},
	"sourceSize": {"w":32,"h":32}
},
```
<Playground id="#YCY2IL#21" title="Blank Tile Added to JSON" description="Simple example of adding a blank tile to a JSON file."/>


## Snippet Server

Starting with Babylon.js v4.2, you can save, load and edit sprite managers using the Inspector. These code snippets are saved on the Babylon.js snippet server. Make a note of the snippet Id shown in when you save it.

![Snippet](/img/how_to/Sprites/snippet_screen.png)

When you have a snippet Id, you can easily load the manager using the following code:

```javascript
var spriteManagerPlayer = BABYLON.SpriteManager.CreateFromSnippetAsync(snippetID, scene).then(manager => {
        scene.debugLayer.show();
        scene.debugLayer.select(manager);
 });
```

Live example: <Playground id="#G9VPHQ" title="Sprite Snippet Server Example" description="Simple example of loading a sprite manager from the snippet server."/>

You can also specify "_BLANK" for the snippet Id, in this case the system will create an empty one for you to work on:

```
BABYLON.SpriteManager.CreateFromSnippetAsync("_BLANK", scene);
```


## Sprites

![Elements](/img/how_to/Sprites/08.png)

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.

```javascript
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

```javascript
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

```javascript
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:

```javascript
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.



# Sprites

Sprites are 2D images and always face the camera. They can used to display animated characters, and particles, and to simulate 3D complex objects like trees.  

For animation individual sprite images are collected together in a single file called a spritesheet.

* A uniform spritesheet is one where all the sprites are exactly the same size and arranged in order in the file. When you read the term spritesheet in the documentation you can usually assume that it is referring to a uniform spritesheet. A uniform spritesheet is overseen by a *Sprite Manager*.
* A packed spritesheet is one where the sprites can be of different sizes and often packed in such a way as to minimize the overall size of the file. Usually the full term of _packed spritesheet_ will be used for such a spritesheet. A packed spritesheet is overseen by a *Sprite Packed Manager*. * available from BJS version 4.1*

For sprites the use of one of these managers is mandatory, even for one sprite. They optimize GPU resources by grouping in one place multiple instances of a sprite. 

Also available, for any grid like implementation (in a 2d or 2.5d game level for instance) that require thousands of sprites to be animated and rendered, is a special system called a *Sprite Map*, *available from BJS version 4.1*


# In-Depth layerMask

`layerMask` is a property you can find on many objects and may be a bit difficult to grasp at first. This page should give you a good understanding of how it works accross Babylon.js objects.

## layerMask meaning

`layerMask` is a value that can be assigned to different objects (like meshes, cameras, layers, particle systems, etc) and is used to determine the visibility of this object from another one (for eg, if a mesh is visible from a camera or if a layer should be displayed after a given camera is processed).

The only two things to understand with `layerMask` are that:
* it can be any number from 0 to 0xFFFFFFFF (or 4294967295, but it’s easier to write 0xFFFFFFFF)
* when computing a visibility flag, two values of `layerMask` are **AND**ed and if the result is different from 0 the flag is true

So, for eg, if `camera.layerMask = 35` and `mesh.layerMask = 2`, `35 & 2 == 2 != 0` so the mesh is visible from this camera. We often show these numbers in hexadecimal because doing the **AND** as a mental calculation is easier that way: `35=0x23` and `2=0x02` and `35 & 2 == 0x23 & 0x02` and from this latter representation it’s easier to see that the result is 2 (well, at least when you are a bit comfortable with hexadecimal!).

## Usage in Babylon.js

In Babylon, by default all `layerMask` properties are `0x0FFFFFFF` (for Camera, Mesh, Layer, …). So, when it comes to determine a visibility, `0x0FFFFFFF & 0x0FFFFFFF != 0` and everything is always visible (at least from the standpoint of the `layerMask` test).

As you can see, there are 4 bits not set by default in the `layerMask` (the leading `0` before the first `F`). It’s to ease the use of `layerMask`, as a common usage is to make some meshes hidden from a camera. To achieve that, you need to set a `layerMask` on the meshes so that the **AND** operation with the `layerMask` of the camera (`0x0FFFFFFF` by default) is 0: you can use `0x10000000`, `0x20000000`, `0x40000000` or `0x80000000`. Now you see why showing these numbers in hexadecimal helps: it’s a lot easier to see that `0x10000000 & 0x0FFFFFFF = 0` than `268435456 & 268435455`!

If the default value for `layerMask` was `0xFFFFFFFF`, you would also need to update the `layerMask` of your camera to have your meshes invisible from it because `0xFFFFFFFF` is a all-one 32 bit value. So the `0x0FFFFFFF` value is simply a default value that can help make your life a little easier, but in all generality you can put any value in the `layerMask` property of cameras, meshes, layers, etc (as in the `35 & 2` example above) and simply understand how it is used to compute visibility.


Sprites

Coming next

Introduction To Sprites

Dive into learning the basics of sprites in Babylon.js.

Sprite Manager

Learn all about sprite management in Babylon.js.

Sprite Packed Manager

Learn about the sprite packed manager in Babylon.js.

Picking Sprites

Learn about picking sprites in Babylon.js.

Sprite Map

Learn about sprite maps in Babylon.js.

Sprite Map Tile Layout

Learn all about sprite map tile layout in Babylon.js.

Sprite Map Options

Learn all about sprite map options in Babylon.js.

Sprite Map Animations

Learn all about sprite map animations in Babylon.js.

Sprite Map Example

Check out an in depth sprite map example in Babylon.js.

Sprite Snippet Server

Learn about saving and loading sprites from the Babylon.js snippet server.