95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# 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.
|