Sprites Map Media Storage
A tile map lives in the data store as one record with just two fields: its id and a data object. None of the metadata, the name, media, platform, times, thumbnail or info summary, is here; that is the meta record, kept beside it under the same id. The data object holds the whole map: its width, height and mode, a tile set of sprite references, and one or more layers of tile indices into that set.
{
"id": "1b7f9c2e4a6d40518c3e5f0a2d8b6e94",
"data": {
"w": 32,
"h": 30,
"mode": "Nametable",
"tileset": { "tiles": [ { "id": "a1..." }, { "id": "b2..." } ] },
"layers": [ { "tiles": [ 0, 1, undefined, 1 ] } ]
}
}id and the data object. The sections below walk the object down through its tile set and layers.Contents
The record in the data store is just the id and the data object. Everything a listing shows, the name, size and mode summary, is the meta record, so this store carries only the map.
| Field | Type | Description |
|---|---|---|
id | String | The item id, 32 hex characters. The key, shared with the item's meta record. |
data | Object | The map: its size, mode, tile set and layers. Detailed in Data below. |
Data
The data object carries the size and mode the map is drawn at, its tile set, and its layers. Width, height and mode live here, on the map itself, not on the meta record; the meta record's info summary is a copy for listings.
| Field | Type | Description |
|---|---|---|
w | Number | The width in tiles, a whole number from 1 to 1024. Defaults to the platform's screen width, and grows far past it for a scrolling map. Every layer's tiles array is this wide. |
h | Number | The height in tiles, a whole number from 1 to 1024. Defaults to the platform's screen height. Every layer's tiles array is this tall. |
mode | String | The platform mode the map is drawn in, by name, for example "Nametable". Absent, or omitted, for a freeform map that names no mode. The mode names how many distinct tiles are allowed; see the platform map info. |
tileset | Object | The tile set: the sprites the layers draw from. Detailed in Tile set below. |
layers | Array | The layers, bottom to top, each a grid of tile indices. Detailed in Layers below. |
Tile set
The tileset is an object with a tiles array, the ordered set of tiles the map draws from. A layer cell holds an index into this array. It is an object, not a bare array, so it has room to carry its own fields later, such as the tile size or a shared palette. (The tile set's tiles holds tile objects; a layer's tiles holds integer indexes into it.)
| Field | Type | Description |
|---|---|---|
tiles | Array | The tiles, in order. Starts empty. Each entry is a tile object; the entry at index i is the tile a layer cell holding i shows. |
Each entry of tiles is an object, not a bare id, so a tile can gain its own fields later (a flip, a palette). Today it holds one field.
| Field | Type | Description |
|---|---|---|
id | String | The id of the sprite this tile draws, a sprite record in the store. A live reference: editing that sprite updates every map that uses it. A missing id shows a blank tile. |
The tile set holds references, not copies, so the sprites stay in their own records and one sprite may be a tile in many maps. The record's shared meta refs field lists these referenced sprite ids, so the store tracks which sprites a map uses.
Layers
layers is an array of layer objects, bottom to top, composited to make the map. A flat map has a single layer. Each layer is an object with a tiles array, so a layer has room to carry sibling arrays later, such as a per-cell attribute plane, one entry to a cell alongside the tile.
| Field | Type | Description |
|---|---|---|
tiles | Array | The tile indices in row order, w times h entries. The cell at column c, row r is at index r × w + c. Detailed in Tile cells below. |
Tile cells
Each entry of a layer's tiles array names a tile of the tile set, or is empty.
| Cell | Type | Meaning |
|---|---|---|
| A tile index | Number | A whole number from zero, the position of the tile in tileset.tiles. When the tile set has no entry at that index, the cell shows a blank tile. |
| Empty | — | No tile in this layer here, so the layer below shows through; on the bottom layer it is a blank tile. The absent value is always undefined, never null. A resize pads new cells with it. |
The layers composite top down: for each cell the topmost layer with a tile there wins, and an empty cell lets the layer below show through. A resize crops or pads every layer's array, and a new pad is an empty cell, so each array's length always matches w times h. See Sprites.Media.Map for the editor that reads and writes it.
Room to grow
The shape is deliberately made of objects, not bare arrays, so it grows without a migration. An editor keeps any field it does not touch through a paint or a resize, so a map saved now reads back unchanged once these are added.
| Where | Planned use |
|---|---|
| A layer's own fields | A sibling array beside tiles, such as an attributes plane, one entry to a cell, holding what a machine attaches per tile: a palette choice, a flip, a priority. A machine whose colour is coarser than a tile, like the NES, holds its attributes at the block size the platform pack names. |
| A tile set entry's own fields | Fields beside id on a sprites entry, such as a default flip or palette for that tile wherever it is placed. |
| The tile set's own fields | Fields beside sprites on tileset, such as the tile size or a shared palette for the whole set. |
Size and scrolling
A map opens at the size of the platform's screen, the tiles a machine shows at once, but may grow to any size up to 1024 a side. A world larger than the machine's hardware map is edited whole here, then streamed at run time through the smaller hardware map, which the machine treats as a scrolling window. The platform pack names the screen size and the hardware map size, so the editor can mark both on a large map; the stored data is just the whole map, its layers of tiles.
Full example
A four by three NES map in the Nametable mode. Its tile set holds two sprites; the single layer draws a border of tile 1 around tile 0, with two empty cells. The tiles array holds twelve entries in row order: a number is a tile index into tileset.sprites, null is empty.
{
"w": 4,
"h": 3,
"mode": "Nametable",
"tileset": {
"tiles": [ { "id": "a1..." }, { "id": "b2..." } ]
},
"layers": [
{
"tiles": [
1, 1, 1, 1,
1, 0, undefined, 1,
1, 1, 1, 1
]
}
]
}data object of a tile map: a tile set of two sprite references and one layer of tile indices into it.