Character States
Add animation states to characters like idle, walk, run, and attack.
Character States
Add animation states to existing characters. Each state defines a specific action or pose (idle, walk, run, attack, hurt, etc.) with its own sprite sheet and frame data.
Endpoint
POST /api/characters/{id}/statesParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | State name: idle, walk, run, attack, hurt, death, cast, jump |
direction | string | No | Direction for this state: south, north, east, west, etc. |
asset_id | string | No | ID of an existing asset to use for this state |
description | string | No | Description for AI generation if no asset provided |
frame_count | integer | No | Number of frames in the animation. Default: 8 |
frame_duration_ms | integer | No | Duration per frame in milliseconds. Default: 100 |
Example
curl -X POST https://api.spritesynth.com/api/characters/chr_xyz/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "south",
"description": "character walking forward with bobbing motion",
"frame_count": 8,
"frame_duration_ms": 100
}'Response
{
"id": "state_abc",
"name": "walk",
"direction": "south",
"asset": {
"url": "https://cdn.spritesynth.com/states/state_abc.png",
"frame_count": 8,
"frame_width": 64,
"frame_height": 64
},
"credits_cost": 3,
"duration_ms": 4500
}Standard States
| State | Description |
|---|---|
idle | Standing still, subtle breathing/bobbing |
walk | Walking cycle |
run | Running cycle (faster, wider stride) |
attack | Combat attack animation |
hurt | Taking damage reaction |
death | Death/fall animation |
cast | Spell casting animation |
jump | Jumping animation |
Tips
- Start with
idleandwalk— these are the most commonly needed states. - Set
frame_duration_mslower for faster animations (e.g. 80ms for run). - Generate all directions for a state before moving to the next state.
Need help?
Join our Discord community for support and tips.
Was this page helpful?