
## Sprite Map Tile Layout

Each sprite map is composed 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) is 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 the 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
```

If you are going to make multiple changes using just one frameID, passing the tileIDs in an array is optimal. It prevents the buffers from 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 need a blank tile. We recommend that you find a single transparent pixel in your packed spritesheet file. You can reference this in the 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."/>


## 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 option property helps the sprite map reserve the proper data buffers in memory and prepare the system 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`: An integer for 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 sprite after framing calculations - default : false
* `colorMultiply`: A Vector3 that will multiply the final color value of the map - default : Vector3(1,1,1)
* `frameRotationDirection`: SpriteMapFrameRotationDirection defines the rotation of the frames in the sprite map - default: `SpriteMapFrameRotationDirection.CW`

After initialization, you can change the rotation and position of the output plane by referencing the sprite map's position and rotation like a standard mesh. For any other option change (like stageSize or layerCount, etc.), it is recommended that you dispose of the map and re-initialize it 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."/>
usage of `frameRotationDirection`: <Playground id="#YCY2IL#2280" title="Usage of frameRotationDirection" description="Rotated sprites in the sprite atlas."/>



## 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
```
