scaffold_cycle
Generate a complete walk, run, idle, attack, hurt, or death animation cycle with proper frame counts, phase tags, timing curves, and loop settings.
Instructions
Scaffold one animation cycle: its frames, a tag per phase, and a shaped timing curve.
`kind` is `walk`, `run`, `idle`, `attack`, `hurt` or `death`, and it settles the four
things a scaffolded animation otherwise gets wrong:
* **The frame count.** walk 8 (6 is the budget option, and 4 only reads as a walk
mirrored on a side view), run 6, idle 4, attack 5, hurt 2, death 6. A count outside
the kind's conventional range is accepted with a warning rather than refused.
* **A tag per phase, named for the pose rather than numbered.** An 8-frame walk gets
`walk_contactL`, `walk_downL`, `walk_passL`, `walk_upL` and the same four for the
right step, plus a `walk` tag over the whole cycle, so the frame you are drawing on
says what it is meant to be.
* **Non-uniform durations from the start**, via `apply_timing_curve`: a cycle holds
its extremes, an attack snaps through the strike, a hurt flashes and then holds the
recovery, a death slows to a stop on a held last pose. Uniform timing is the
placeholder every animation starts with and almost none should keep.
* **Loop versus one-shot.** An attack, a hurt and a death do not wrap, so every tag
they get is written with `repeats=1` instead of being left at 0 ("play forever").
That field is what `validate_loop` reads, so a one-shot tagged as a loop makes the
checker report a duplicated seam frame on an animation that has no seam.
Frames are copies of frame 1, there to draw over. Nothing already in the sprite is
deleted, but Aseprite inserts a copied frame rather than appending it, so on a sprite
that already has several frames the new ones land at the front and the existing ones
end up at the end of the cycle; the manifest warns when that happens. Frames past the
cycle are left untagged and untimed, with a warning saying which.
Args:
kind: walk | run | idle | attack | hurt | death.
frames: Override the kind's default frame count.
base_ms: The duration of a passing frame; every other duration is a multiple of
it. Defaults per kind, because a run passes through its poses faster than an
idle breathes.
Returns a ``workflow_manifest.v1`` manifest (kind ``animation_cycle``) whose
`animation` section lists every phase with the frame, tag, duration, timing role and
repeat count it ended up with, read back off the saved sprite rather than restated
from what was asked for.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| frames | No | ||
| base_ms | No | ||
| filename | Yes |