Animation Loops & Timing

Overview

Animation timing determines how a character feels to control. A walk animation at 60ms per frame feels frantic; at 300ms it feels sluggish. The difference of a few milliseconds per frame can make or break the game's feel. Understanding frame duration, loop types, and easing is essential for professional pixel art animation.

Step 1: Choose the Right Frame Rate

Step 2: Create New Animation States

Add a new state to an existing character:

curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "attack",
    "direction": "south",
    "asset_id": "generated_attack_sprite_id",
    "frame_count": 3,
    "frame_width": 32,
    "frame_height": 32,
    "frame_duration_ms": 100
  }'

Use different frame counts per state — attack animations need fewer frames (2-4) than walk cycles (4-8).

Step 3: Set Frame Duration by State

Configure timing per character state in spritesynth:

curl -X PUT https://api.spritesynth.com/v1/characters/{character_id}/states/{state_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frame_duration_ms": 150
  }'

Recommended defaults: idle (500ms), walk (150ms), run (100ms), attack (80ms), hurt (120ms).

Step 4: Export the Animated Character

Download the complete character with all states, frames, and timing metadata:

curl -o animated-character.zip https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
  -H "Authorization: Bearer YOUR_API_KEY"

The exported metadata.json includes frame_duration_ms per state — your game engine reads this to match the timing you configured.

Step 5: Configure Loop Types

Different animations need different loop behaviors:

In your game engine, configure loop behavior based on the state. Attack animations should play once and return to idle. Idle animations should loop continuously.

Tips

• Variable timing within a state — Some frames can be held longer for emphasis (e.g., the wind-up frame in an attack animation at 150ms while the strike plays at 60ms).
• Animation feel checklist — Walk test: character covers ground smoothly. Attack test: the hit frame is readable. Idle test: subtle movement without being distracting.
• Export timing data — spritesynth exports frame durations in the metadata JSON. Your game engine should read these values rather than hardcoding timing.