Documentation/Sprites.md

# Sprites

This is a guide for how sprite data is stored, parsed, and drawn to the visual canvas in GameStartr projects.
It's built on the [PixelDrawr](https://github.com/FullScreenShenanigans/PixelDrawr) and [PixelRendr](https://github.com/FullScreenShenanigans/PixelRendr) modules.

## Storage

A GameStartr instance's PixelRendr keeps sprite data stored as a library using a [StringFilr](https://github.com/FullScreenShenanigans/StringFilr).
Each sprite is stored as a series of numbers that represents the ordered pixels in a rectangle.

```javascript
"00000001112"
```

A mapping of which numbers represent which color are stored in a global "palette".
    
```javascript
[
    [0, 0, 0, 0],         // transparent
    [255, 255, 255, 255], // white
    [0, 0, 0, 255],       // black
    // ... and so on
]
```
    
Using the above palette, the sprite represents seven transparent pixels, three white pixels, and a black pixel.

Most images are much larger and more complex so a few compression techniques are applied.

1. **[Indexed Color](https://en.wikipedia.org/wiki/Indexed_color)**

    It is necessary to have a consistent number of digits in images, as `010` could be `[0, 1, 0]`, `[0, 10]`, or etc.
    Palettes with more than ten colors therefore have to prefix single-digit numbers with `0`.
    For example, `[1, 14, 1]` would use `["01", "14", "01"]`:

    ```javascript
    "011401011401011401011401011401011401011401"
    ```

    We can avoid this wasted character space by instructing a sprite to only use a subset of the pre-defined palette:

    ```javascript
    "p[1,14]010010010010010010010"
    ```

    The `p[0,14]` tells the renderer that this sprite only uses colors 0 and 14.
    The number 0 then refers to palette number 1 and the number 1 should refer to palette number 14.

2. **[Run-length Encoding](https://en.wikipedia.org/wiki/Run-length_encoding)**

    Take the following wasteful sprite:

    ```javascript
    "p[0]0000000000000000000000000000000000000000000000000"
    ```

    We know the 0 should be repeated 35 times, so the following notation is used to indicate "repeat ('x') 0 35 times (','))":

    ```javascript
    "p[0]x035,"
    ```

3. **Filters**

    Many sprites are different versions of other sprites, often simply identical or miscolored (the only two commands supported so far).
    A library may declare a filter:

    ```javascript
    "Sample": [ "palette", { "00": "03" } ]
    ```

    ...along with its sprites:

    ```javascript
    "foo": "p[0,7,14]000111222000111222000111222",
    "bar": [ "filter", ["foo"], "Sample"]
    ```

    The `"bar"` sprite will be a filtered version of foo, using the `"Sample"` filter.
    The `"Sample"` filter instructs the sprite to replace all instances of `"00"` with `"03"`, making `"bar"` equivalent to:
 
    ```javascript
    "bar": "p[3,7,14]000111222000111222000111222"
    ```
 
    Another instruction you may use is `"same"`, which is equivalent to directly copying a sprite with no changes:

    ```javascript
    "baz": [ "same", ["bar"] ]
    ```

4. **"Multiple" sprites**

    Sprites are oftentimes of variable height.
    Pipes in Mario, for example, have a top opening and a shaft of potentially infinite height.
    Rather than use two objects to represent the two parts, sprites may be directed to have one sub-sprite for the top/bottom or left/right, with a single sub-sprite filling in the middle.
    Pipes, then, would use a top and middle.

    ```javascript
    [ "multiple", "vertical", {
        "top": "{upper image data}",
        "bottom": "{repeated image data}"
    } ]
    ```