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.