Sprites Sprite Media Storage

A sprite 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 drawing: its width, height and mode, and an array of frames, each holding an array of layers, each layer holding a grid of pixels.

{
  "id": "9f8c2a4e7b1d40128e5a6c3f0b9d7e21",
  "data": {
    "w": 24,
    "h": 21,
    "mode": "High-res",
    "frames": [
      {
        "layers": [
          {
            "pixels": [ null, null, 1, 1, null ],
            "visible": true
          }
        ]
      }
    ]
  }
}

The whole data record: the id and the data object. The sections below walk the object down through its frames, layers and pixels.

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 drawing.

Field	Type	Description
`id`	String	The item id, 32 hex characters. The key, shared with the item's meta record.
`data`	Object	The drawing: its size, mode and frames. Detailed in Data below.

Data

The data object carries the size and mode the whole sprite is drawn at, and its frames. Width, height and mode live here, on the drawing 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 pixels, a whole number from 1 to 256. Every layer's pixel grid is this wide.
`h`	Number	The height in pixels, a whole number from 1 to 256. Every layer's pixel grid is this tall.
`mode`	String	The platform mode the sprite is drawn in, by name, for example `"High-res"`. Absent, or omitted, for a freeform sprite that names no mode.
`frames`	Array	The animation frames, in order. One or more. Detailed in Frames below.

Frames

frames is an array of frame objects, one per animation frame, played in order. A still sprite has a single frame. Every frame shares the sprite's width, height and mode; each holds its own stack of layers.

Field	Type	Description
`layers`	Array	The frame's layers, back to front. One or more, and for now a frame's only field, so the object has room to carry per frame data such as a hold time later. Detailed in Layers below.

Layers

layers is an array of layer objects, back to front, composited to make the frame. A flat sprite has a single layer. Each layer holds its own grid of pixels and a visible flag.

Field	Type	Description
`pixels`	Array	The layer's pixels in row order, `w` times `h` entries. The pixel at column `c`, row `r` is at index `r × w + c`. Each entry is a pixel value, encoded below.
`visible`	Boolean	Whether the layer is currently shown. A hidden layer, `false`, stays in the data but is left out of the composite and the thumbnail.

A resize crops or pads every layer's array, and a new pad is a transparent pixel, so each array's length always matches w times h. See Sprites.Media.Sprite for the editor that reads and writes it.

Pixel encoding

A pixel is one integer, or empty for transparent. Its meaning depends on how the editor colours the sprite.

Pixel	Editor	Meaning
A packed colour	Freeform	A 32 bit RGBA colour packed into one integer, each byte a channel: red, green, blue, alpha. Opaque white is `4294967295`. See Sprites.Colour for packing and unpacking.
A slot index	Indexed	A whole number from zero, the position in the platform's palette slots. The slot colours belong to the platform pack, not the stored data, so a palette change recolours every pixel on that slot.
Empty	Both	The transparent pixel, an absent value. Held in memory as `undefined` and written as `null` in a JSON export.

Which encoding a sprite uses follows its platform. A freeform sprite packs any colour into each pixel. An indexed sprite, for a machine like the C64, stores a slot index, and the drawn mode is kept in data.mode, beside the frames. The palette itself is fixed by the platform, so it is not saved with the sprite.

Full example

A four by four freeform sprite, an opaque white cross on transparent, as a single frame of a single layer. The pixels array holds sixteen entries in row order: 4294967295 is opaque white, null is transparent.

{
  "w": 4,
  "h": 4,
  "mode": null,
  "frames": [
    {
      "layers": [
        {
          "pixels": [
            null,       4294967295, 4294967295, null,
            4294967295, null,       null,       4294967295,
            4294967295, null,       null,       4294967295,
            null,       4294967295, 4294967295, null
          ],
          "visible": true
        }
      ]
    }
  ]
}

The data object of a freeform sprite. It sits in the data store beside the id.

An indexed sprite has the same shape, with a slot index in place of a packed colour, and its mode named in data.mode. Here two pixels sit on slot 0 and two on slot 1.

{
  "w": 2,
  "h": 2,
  "mode": "High-res",
  "frames": [
    {
      "layers": [
        {
          "pixels": [ 0, 1, 1, 0 ],
          "visible": true
        }
      ]
    }
  ]
}

The data object of an indexed sprite. The slot colours come from the platform pack, not from here.