
## 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."/>

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