Character State Machines

Overview

A character state machine defines how a character behaves and transitions between actions. Idle flows to walk, walk flows to run, any state can transition to hurt or die. Clean state machines make characters feel responsive and predictable to the player.

Each state in spritesynth has its own sprite sheet, frame count, and timing. The state machine logic lives in your game engine, but the asset structure must support it.

Step 1: Define State Hierarchy

Map the complete state flow before generating assets:

Idle ──> Walk ──> Run
  │        │        │
  └──> Attack      │
  │        └──> Hurt ──> Die
  └──────────────────> Die

Every character needs at minimum: idle, walk, hurt, and die states. Add run, attack, and jump based on gameplay requirements.

Step 2: Generate States with Consistent Timing

Create each state with frame timing that matches the intended feel:

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": "walk",
    "direction": "south",
    "frame_count": 4,
    "frame_width": 32,
    "frame_height": 32,
    "frame_duration_ms": 150
  }'

Generate all states for one direction first. The editor's onion skinning helps verify smooth transitions.

Step 3: Synchronize Frames Across States

Ensure consistent positioning across states — a character shouldn't shift position when transitioning from idle to walk:

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": 200
  }'

Use the editor to align frame positions. All states should share the same canvas size and character origin point.

Tips

• One direction first — Build and approve all states for one direction, then generate the other directions using the same state structure.
• Transition frames — For attack-to-idle transitions, ensure the last attack frame visually connects to the first idle frame.
• Hurt state priority — Hurt should interrupt most states. Keep hurt animations short (2-3 frames) for responsive gameplay.