# Sprite Pack Manifest Schema (MVP)

Path: `<pack_dir>/manifest.json`

## Required Fields

- `id` (string): unique sprite pack ID.
- `version` (string): schema/pack version label.
- `image` (string): atlas image filename, e.g. `atlas.png`.
- `frame_width` (u32): frame width in pixels.
- `frame_height` (u32): frame height in pixels.
- `animations` (array): list of animation definitions.
- `anchor` (object): sprite anchor/pivot.

## Animation Definition

- `name` (string)
- `fps` (u16)
- `frames` (array of u32 frame indices)
- `one_shot` (optional bool)

## Anchor Object

- `x` (f32)
- `y` (f32)

## Example

```json
{
  "id": "default",
  "version": "1",
  "image": "atlas.png",
  "frame_width": 64,
  "frame_height": 64,
  "animations": [
    { "name": "idle", "fps": 8, "frames": [0, 1, 2, 3] },
    { "name": "success", "fps": 12, "frames": [20, 21, 22], "one_shot": true }
  ],
  "anchor": { "x": 0.5, "y": 1.0 }
}
```

## Runtime Fallback Behavior

- The selected pack is attempted first.
- If selected pack is missing/invalid, frontend falls back to `default`.
- If `default` is missing/invalid, loading fails with error.

## Alpha Handling

- If the source image already has an alpha channel, runtime uses it directly.
- If the source image is RGB-only, runtime can apply chroma-key conversion:
  - default key color: `#FF00FF`
  - matching pixels become transparent.
- Manifest optional fields:
  - `chroma_key_color` (string `#RRGGBB`)
  - `chroma_key_enabled` (bool)

## Grid Derivation Rule

- Runtime derives atlas grid from image dimensions:
  - `columns = image_width / frame_width`
  - `rows = image_height / frame_height`
- Image dimensions must be divisible by frame dimensions.
- Every animation frame index must be `< columns * rows`.

## Tauri `sprite.png` Override

For `sprimo-tauri`, when manifest `image` is exactly `sprite.png`:

- runtime uses a fixed grid topology of `8` columns x `7` rows.
- frame size is derived from actual image dimensions:
  - `frame_width = image_width / 8`
  - `frame_height = image_height / 7`
- manifest `frame_width` and `frame_height` are ignored for this case.
- animation frame indices are validated against the fixed grid frame count (`56`).

## Recommended 7x8 Row Semantics

For `sprite.png` packs using the fixed `8x7` topology, the project convention is:

- row 1 (`0..7`): `idle`
- row 2 (`8..15`): `happy`, `love`, compatibility alias `active`
- row 3 (`16..23`): `excited`, `celebrate`, compatibility alias `success`
- row 4 (`24..31`): `sleepy`, `snoring`
- row 5 (`32..39`): `working`
- row 6 (`40..47`): `angry`, `surprised`, `shy`, compatibility alias `error`
- row 7 (`48..55`): `dragging`

Default one-shot policy:

- `celebrate` and `success` are one-shot.
- other row animations loop by default.