Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

6.4 KB
Raw Blame

States & Frame Counts — sprite-gen reference

Owns: Which states to request and how many frames each · Index: docs/README.md

SKILL.md 허브에서 분리한 시나리오 상세. 요청할 상태(state) 목록과 프레임 수를 정할 때 이 문서를 따른다.

Video Path State Defaults

Video path defaults apply strictly to the video path, independent of component-row simple states. Mode once executes a single action transitioning from an initial pose to a stable final pose, skipping return motion, with no seam gate or wrap correction. Mode one-shot executes a rest -> action -> rest cycle requiring seam closure.

Six states automatically select once across sprite-gen video-prompt, sprite-gen video-set, and sprite-gen video-loop --cycle auto. Defaults for idle, walk, run, jump, and attack remain unchanged. Cyclic states (idle, walk, run, talk, blink, breathe) reject explicit --cycle once, but overrides allow jump, attack, or custom actions.

These defaults are presets. --play loop|once-return|once-hold|lifetime (video-set, video-prompt) films a motion in the mode the request names — a named state, or a word of your own described with --motion (a punch, typing at a desk, a block) — and the end-frame pin, the prompt's ending, the cut and the strip's loop follow it. The six states below play once-hold only, effect lifetime only, and the cyclic states loop only. See play modes.

Motion prompts request a 0.4 s hold. Anatomy is preserved across body plans (quadruped, legless). Headroom requires symmetric side margins for death and hurt_hold, overhead room for cast and transform, and descent room for land; border contact is refused. Candidate end pose geometry requires median end-window height <= 80% of initial height for death and fall, while the other four require changed geometry (conservative geometric screen; inspect semantic pose visually). A motion of your own played once-hold, or any other state cut --cycle once, is screened by its drawing instead, so a pose that changes inside an unchanged body outline counts and the first drawing come back does not (terminal gate). Root displacement metadata is omitted. See video-pipeline.md for gate and metadata details.

State End Pose
death lying prone on ground
fall grounded resting pose after downward drop
land low crouch after descent
cast raised implement or forward body in casting pose with no effects
hurt_hold held recoil
transform final changed form

Simple MVP Scope

The default user promise is deliberately simple:

A Codex user installs this skill, provides a character/base image and one or more simple actions, then receives a sprite sheet, GIF preview, and QA notes.

Do not frame the default path as game-ready humanoid locomotion. The current Codex/image-gen path is good at short readable pose changes, identity-preserving rows, chroma cleanup, atlas composition, and QA. It is not yet reliable enough to promise precise cyclic locomotion for humanoids.

Default/simple states:

  • idle — stable default. Use 4 frames, loop true.
  • jump — stable default as a short non-loop action. Use 4 frames, loop false.
  • attack — stable default as a short non-loop action. Use 4 frames, loop false.
  • wave — simple gesture, but only stable as non-loop unless the row includes a return-to-idle frame. Use 4 frames, loop false by default; use 5 frames only when the final frame intentionally returns near frame 1.
  • talk, blink, bounce, hurt, celebrate, magic_cast — allowed simple candidates, but still require motion QA before pass.

Experimental states:

  • walk, run, frontwalk, 45_frontwalk, and other cyclic locomotion.
  • Directional cycles that require exact foot-contact alternation or phase symmetry.
  • Any state where the user needs game-ready locomotion rather than a readable preview animation.

For experimental states, report them as experimental in qa-notes.md unless motion QA passes. Never silently promote a weak walk/run row to the same status as simple MVP output.

Quick Path For Simple Animations

When the user asks for "simple sprite animation", prefer this request shape unless they specify otherwise:

{
  "states": {
    "idle": { "frames": 4, "fps": 4, "loop": true, "action": "subtle breathing and one blink" },
    "attack": { "frames": 4, "fps": 8, "loop": false, "action": "simple windup, strike, recovery attack pose sequence with no detached effects" },
    "jump": { "frames": 4, "fps": 8, "loop": false, "action": "simple jump arc: crouch, takeoff, airborne, landing" }
  }
}

Add wave only as a non-loop gesture by default:

"wave": { "frames": 4, "fps": 6, "loop": false, "action": "friendly hand wave gesture; arm changes clearly while feet stay planted" }

Simple MVP pass requires:

  • automated extraction and atlas reports pass
  • qa/<state>.gif reads as the requested simple action
  • loop seam passes for looped states
  • non-loop states have clear start/middle/end pose progression
  • qa-notes.md records pass, best-effort, or experimental per state

Frame Count Guidance

Keep default simple actions short. More frames do not automatically create smoother animation in the current component-row image generation path:

  • 4 frames is the default stable range for simple actions.
  • 5 frames is acceptable when a non-loop gesture needs a return-to-idle pose.
  • 6 frames is the conservative upper edge for simple humanoid one-shot defaults.
  • 8 frames is hatch-pet-style advanced territory, not forbidden. Use it for compact mascots, locomotion rows, or explicit experiments only when extraction/motion QA passes.
  • 9 and 12 frames are not default simple settings. In validation runs, they increased duplicate bodies, empty/sparse frames, slot collapse, and extraction failure before adding useful in-betweens.

If a user asks for 9 or 12 frames, run it as an explicit experiment and report duplicate-heavy, blur/merge, or extract-fail honestly instead of treating it as a normal pass.

Related