Sprimo/docs/SPRITE_PACK_SCHEMA.md

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

{
  "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.