
## 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 perform picking, you can use `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. If 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."/>


When sprites overlap, 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 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 major use case, as shown in this section, is 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 initialization parameters.

A sprite map is displayed on a standard plane mesh in 3D space and can be transformed in 3D space. The rendering speed is based on the use of texture buffers, and each map requires only one draw call.

Since the plane is split into a grid of tiles of the same size, the cells of the packed spritesheet should also be the same size.

It uses the *Babylon.js (JSON Array for SpriteMap)* format from [TexturePacker](https://www.codeandweb.com/texturepacker) and benefits from the rotation, extrude, and padding properties. *Soon, 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 *SpriteMap*.

![spritesheet](/img/how_to/Sprites/legends.webp)

The beginning of the JSON file format for the packed spritesheet above 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 atlas JSON and the spritesheet texture have been loaded, we can create the sprite map, setting two of the option 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
);
```

Once the sprite map is created, sprites are assigned to the tiles in the grid by their frameID, which is 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 map with 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()
```
This creates 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 Packed Manager
*Available from BJS version 4.1*

A packed spritesheet will look something like this.

![Packed Spritesheet](/img/how_to/Sprites/pack1.webp);

with sprite cells of different sizes arranged to optimize the file size.

The corresponding JSON file will have a format based on that produced by the [TexturePacker](https://www.codeandweb.com/texturepacker) app with the following settings:

- Data format: *Babylon.js (JSON Hash for SpritePackedManager)* 
- Trim: None
- Allow Rotation: Off


```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 *Babylon.js (JSON Array for SpriteMap)* format for packed spritesheets. JSON files are not interchangeable between *SpritePackedManager* and *SpriteMap*.

The minimal format required by *SpritePackedManager* is below. Although it currently uses only 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}
		}
	}
}
```
Remember, 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."/>

As with 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 can 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

Picking