Object Variants & States

Overview

Game objects aren't static. A treasure chest has open and closed states. A door swings from idle to open. A torch flickers between lit and unlit. Each state communicates something to the player, and smooth transitions between states make the world feel responsive.

spritesynth lets you define multiple states per object, each with its own sprite sheet and frame timing.

Step 1: Create the Base Object

Start with the primary object — the idle state:

curl -X POST https://api.spritesynth.com/v1/objects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "pixel art treasure chest, wooden planks, iron bands, closed, top-down view",
    "direction_count": 1,
    "project_id": "your-project-uuid"
  }'

Step 2: Add Interactive States

Add states for different object conditions. For a treasure chest, add an open state:

curl -X POST https://api.spritesynth.com/v1/objects/{object_id}/states \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "open",
    "frame_count": 2,
    "frame_width": 32,
    "frame_height": 32,
    "frame_duration_ms": 200
  }'

For a door, add idle (closed), open, and broken states. For a torch, add idle (lit) and destroyed (unlit) states.

Step 3: Define State Transitions

In your game code, map object states to gameplay events:

closed  → (player interacts) → open
open    → (player closes)    → closed
idle    → (damaged)          → broken
active  → (depleted)         → destroyed

Tips

• Consistent canvas size — Keep the same width and height across all states so transitions don't cause visual jumps.
• Two-frame animations — Simple states like open/close only need 2 frames: start and end positions.
• Destroyed states — Add particle-like debris frames for destruction animations to make them more satisfying.