Sprite Gen

Generation entry points: make sprites, make an image, or animate a still into a video. Existing generation, extraction and export tools do the work; the user chooses the result and provider. For repeat a background, project a shadow, inspect motion or compose a scene, use the independent routes below directly with existing assets.

Start every generation request here

For a standalone video clip, read video and use sprite-gen video. This route works from any agent engine and delivers a verified MP4 plus report. For sprites or ordinary images, use the guides below.

Read user-workflow, then run the appropriate read-only guide:

$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind image

Pass choices already stated in the request. The guide checks access, combines explicit choices with saved defaults, and returns only missing questions. Follow its start and finish stages. Always pass the resolved provider explicitly to generation tools. Deliver checked files before offering the curation view; save defaults only when the user agrees. The complete conversation and settings contract is owned by the linked document, not duplicated in individual pipeline docs.

When codex cannot run — exit 75

A call that names no provider (gen, logo, gen-set, video-set's mid-step redraw) runs on codex. When codex cannot run here — not signed in, or the codex usage of the account used up — and the user's choice for that is to ask (the default), the command generates nothing, prints one stderr line starting sprite-gen ask codex-unavailable: followed by JSON, and ends with exit 75. That is a question for the user, not a failure: never answer it yourself, never retry without the answer, never switch provider on your own.

Ask it in these words, with the reason from the line's cause (login: "로그인이 없어요", usage-limit: "사용량을 다 썼어요"):

지피티(codex)를 지금 쓸 수 없어요 — {이유}. 어떻게 할까요?

1. OpenAI API 로 만들기 (호출당 과금)
2. 그록으로 만들기
3. 멈추기

Then run the same command again with the answer's flag from the line's choices — 1: choices.openai (--provider openai; video-set: --still-provider openai), 2: choices.grok — or, for 3 (멈추기), stop and say nothing was generated. When the user says to do the same from now on, save it: sprite-gen defaults save --codex-unavailable openai|grok|ask --expected-revision <revision from defaults show>. A saved grok or openai runs without asking and says so on stderr and in the report (provider_fallback). The rule is gen's.

Side-view facing

Keep the side still, canvas placement and motion prompt facing the same direction. video-set observes each side input once before canvas placement and uses the requested --facing for both the canvas and clip prompt. Observation is record-only by default; it never changes the requested direction. Image correction requires explicit opt-in.

Command option	Values and default	Behavior
gen --facing	preserve (default), right, left	With --ref, an explicit direction adds a prompt requirement and checks the generated still.
gen --facing-fix	none (default), mirror, regen	Record without correction; opt into mirroring an observed opposite or regenerating once and rechecking. A still-opposite regeneration is mirrored.
video --direction	side, front, back, front_diagonal, back_diagonal; unset by default	side opts into facing inspection and a matching prompt requirement; the others skip it. The two diagonals are three-quarter views turned right (VIEW_TEXT); a walk or run in one is filmed pinned (pins_last_frame).
video --facing, video-set --facing	right (default), left; video-set also right,left	Required side direction. right,left films every side and diagonal view both ways, each from its own still (--base side@left=…); none is mirrored.
gen --direction, --handed; video-prompt / video-set --handed	a view; "<item>=<left|right> [part]"	An item on one of the character's own sides: the still and clip prompts say where it is in each view, and mirroring is refused.
video-prompt / video-set / gen --direction / prepare --body-plan	biped (default), quadruped, legless; or "<figure>=<plan>" per figure of a scene	What the subject stands on: no clip, attack, redraw, still view or sheet row prompt names a part it lacks (a horse is not walked on a person's legs, stood up, given arms in a walk sheet or told to strike with its hands), and a scene says it per figure.
video --facing-fix, video-set --facing-fix	none (default), mirror	Record the observation; opt into mirroring an observed opposite in a copy. Batch side inspection is enabled by default.
video-set --play, --motion; video-prompt --play, --motion	loop, once-return, once-hold, lifetime; in video-set "<state>=…" or "<item>=…"	How a motion plays, and its own words: a word the engine does not name (punch, type_at_desk) is filmed in that mode; a once-return strip plays once and ends on its first pose (loop: false, returns: true). Without --play a named state plays as its preset (play modes).

Direction is requested through the generation and motion prompts, which cannot guarantee model compliance. The detector can be wrong even at high confidence: review the still before choosing mirror or regen. Generation reports record direction, model, requested direction, model-reported confidence and correction under extra.facing; video reports and batch items use facing. final_direction is an observation or a value derived from it, not independent verification; final_direction_source identifies which. An uncertain or failed inspection records unknown and its reason and continues without correction; front-facing observations also remain unchanged. Mirroring does not preserve left/right accessory handedness. It stays the default, since drawing the left-facing views costs as much again; for a character with a watch on one wrist or a pin on one side, offer to draw them instead with --handed and check them with handed-check (a colour-marked item, frame by frame; --board for the eye) — handedness. In a side view an item on the far wrist or hand shows each time that arm swings forward, never hidden for the whole walk: draw that side still mid-stride with the far arm out in front of the body and the item in view (video-prompt says so under still_needs), do not hold the arms still, and check the loop with handed-check --state walk.

Execution routes

Task	Entry	Contract
GPT image sprites	prepare, gen-set --provider codex, extract, compose and QA	atlas-workflow
Standalone video / animate a still, pin a last frame, reference images	video (--image, --last-frame, --reference)	video
Continue or edit an existing clip	video-extend, video-edit	video
A clip run left unfinished (its line or report names a request_id): ask for it again, never submit it again	video-resume --request-id <id>	video
Grok video sprites	video-set	video-pipeline
A soft part of a walk loop follows the body (a chest, a belly): an ellipse in the first cell, after video-cycle-align — --read-on <sha256> where it was read on the cut the loop was aligned from; --stretch-floor D to keep a least area	video-follow	video-pipeline
Where that ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved	video-follow-inspect	video-pipeline
A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import): rows in compass order S SW W NW N NE E SE from each loop's --view, one cell size, every row as cut, an optional centre picture (--center) at the rows' standing height; loops of different lengths are laid and said to differ (same_length false) — align the set first	video-set-sheet	video-pipeline
A walk or run that stops, from the clip's own start played backwards: a one-shot strip (loop: false, hold_last: true), GIF, WebP and report beside the loop, ending on the still as filmed; leaves the loop from the cell nearest the entry (from_cell), drift taken out across the frames by a straight share; a seam past 1.4 steps (--seam-max), a run-up that comes back to a pose it left (another motion, however short) or one over 1.5 cycles (--run-up-max) refused; ghost screen checked, cells placed and anchored to match the loop's pivot	video-stop	video-pipeline
Compare the currently displayed loop with a final candidate, including after follow-through	video-loop-compare	loop-comparison
Restore post-processing damage in the current cut from its exact source times, preserving normal cells and playback	video-source-manifest → video-loop-repair → video-loop-compare	source restoration
Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크)	video-canvas, video-prompt --no-last-frame, the agent's own MCP tools (quote, user approval, generate, save the mp4), then video-frames and video-loop (a walk or run with --anchor motion-auto, which holds its size), and for a walk or run cut in two or more directions video-cycle-align --view … over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass --cycles <loop>=<k>; a loop the report lists under unnamed_feet — its view could not tell the feet apart, or only by too small a margin (low-margin): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left	right). video-set is not run on this route, so the set stage it runs by default (--align-cycles auto) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's grok-imagine-video-1.5has no end frame, so idle, attack and diagonal walks are refused unless--unpinned`
Typography logo, wordmark or title lettering (로고, 타이포그래피, 타이틀 글자): the title lettered into a title screen or poster first, then only its lettering redrawn on a key and cut out with its glow; the text is read back and a misspelt logo refused	logo --text … --style … (--mood to start from a picture you have, --lettering to cut again for nothing)	logo
Ordinary image or edit	gen --provider codex or gen --provider grok (the subscription login first; without one grok uses XAI_API_KEY, and a codex signed in with an API key bills it — both per call, said on stderr)	gen
Pixel art the model draws directly as a grid, 8–48 px (best at 32 or less): an icon, a prop, a monster, a character still, four directions, a walk draft, a tile, or a hand-drawn motion of up to 64 frames drawn four a call (--motion, {name, pose} frames, --duration-ms), in a style of your own (--style) — on your Claude subscription (claude signed in), or without one on ANTHROPIC_API_KEY, billed per call; grid.txt is the truth, --grid re-renders an edited one, --resume collects a batch instead of buying it twice	pixel-draw	pixel-draw
Image generation with no login available (server, container, SaaS)	gen --provider openai — server/SaaS route on OPENAI_API_KEY, billed per call, never a default; it runs only when named, or when the user chose it for a codex that cannot run	gen
Base and direction anchors	anchor	directional-anchor-workflow
Curation view or existing image candidates	curation, unpack-atlas --pngs-dir	curation
Uniform background removal or imported sheets	cutout, slice-sheet	sheet-slicing
Palette swap	sprite-gen recolor-palette, sprite-gen recolor	recolor
Rig layer composition	sprite-gen compose-layers	layer-tracks
Idle breathing	curation choice, baked by compose	breathing
Engine exports	export-aseprite, export-pngs	engine-export
Background recipe or repeating tile	existing gen / cutout, then optional background-tile	asset-tools
Ground tile that repeats both ways	gen (opaque), then background-tile --axis xy	asset-tools
Game UI kit: panel, buttons, card, HP/XP bar frames and fills, timer badge, item slot, counter plate, on/off dots, joystick base and knob as sliced elements	gen --transparent --aspect-ratio 2:3 --layout-guide ui-kit (1:1: the seven frames alone), then ui-kit; the seven frames are required, and a band element whose box is empty is left out and named under missing	ui-kit
Props or icons on a transparent sheet	slice-sheet --chroma-key none --alpha-floor 64, props with --scale sheet --fit contain, icons with --fit contain	sheet-slicing
Painted props, a ground tile and a UI kit in a game pack	game-pack request version 2 (images, tiles, ui)	game-pack
Standalone projected shadow	shadow	asset-tools
Duplicate poses, foot contact and stride measurement	inspect-motion	asset-tools
Optional scene placement, lighting, camera and render	scene-render, scene-inspect	scene
Defaults	defaults show, defaults save (--codex-unavailable ask|grok|openai: what to do when codex cannot run), defaults clear	user-workflow

Say a thing once: what an option says, leave out of the prompt. --direction, --facing, --handed, the key background and video --direction side each add their own sentence after your text, in one place; without --handed every prompt is 2.22.0's, byte for byte, and only the handed sentences are left out where your text already has them. Your prompt carries the subject, its design and its pose. Text that says the opposite of an option ("facing left" with --facing right, the item on the other wrist) is sent as written with a warning (extra.prompt_notes, video-prompt's warnings): fix the prompt, do not send it — prompt-assembly.

gen --transparent with --ref plans a chroma key (adding the key's background line to a prompt that names none), and publishes a result that already came back transparent on its own alpha instead of keying its outline away; alpha.strategy_source in the report says which (refs-attached keyed, refs-attached-raw-alpha not). A key background painted as a transparency checkerboard is refused before keying (chroma: the background is a painted transparency checkerboard …): generate again — gen.

Use existing automatic pipeline stages for background removal, extraction, alignment and export. Do not ask users to select each script. For a direct utility request, run that utility; no unrelated generation questions are needed. Preserve the row pipeline and component extraction for image sprites. One-shot grid generation and fixed cell cutting are not an alternative sprite-generation route.

For attack repeat coverage, observed one-shot returns and structured loop failure reports, follow video-pipeline.

Scene creation consumes finished assets and remains optional. Asset metadata owns frames, native durations and anchors; scene specs own placement, scale, playback rate, planes, camera and light. Measure stride only with declared same-foot contact and an isolated foot ROI; unknown contact stays unverified. Apply only a verified report for the exact selected asset with an explicit scene direction. Never infer walking direction from the bottommost silhouette, reverse frames or change source assets to make a scene work.

실행 인터프리터

SPRITE_GEN_ROOT is the absolute installed repository path. Use $SPRITE_GEN_ROOT/.venv/bin/sprite-gen or $SPRITE_GEN_ROOT/.venv/bin/python; do not assume an activated shell. 폴백 금지: create a missing venv or report the failure, never use an arbitrary global Python. NumPy 가 없는 인터프리터 fails at package import. Setup and diagnosis: interpreter.

RIFE for walk and run loops

video-loop repairs a walk's or run's jump frames, eases a part that rushes on its way at the wrap, closes a two-step cut's wrap that a part on its own beat leaves open with the clip's frames a cycle apart, and gives its filmed ghosts way (a half-drawn frame the video model left, ghost_given_way), and video-set gives a direction set one cycle length, both with RIFE in-betweens. Install it once per machine: $SPRITE_GEN_ROOT/.venv/bin/sprite-gen rife install (pinned rife-ncnn-vulkan 20221029 and model rife-v4.6, SHA-256 checked, into the user data directory, ending with a check frame; Linux without a GPU first needs libvulkan1 mesa-vulkan-drivers). Every call runs the binary's test-time augmentation -x -z; on a CPU it costs 15 to 19 times a plain call, so a CPU-only machine aligning a set may set SPRITE_GEN_RIFE_TTA= (none) or -z. Without it every loop is still cut — a jump or a rush as filmed, each filmed ghost given way to the clean frame beside it — and what was left unrepaired says so: a warning: line on stderr and jump_repair.rife with jump_repair.unmade (the jump left as filmed) or jump_repair.ease_skipped (the rush) in the loop report (applied alone is not the sign: a ghost given way reads true), cycle_align.<state>.applied: false and warnings in set.report.json. When that happens, tell the user which loops went unrepaired and offer the install; after it, cut those loops again and run video-cycle-align. video-loop --repair on and video-cycle-align fail without RIFE instead. loop-repair.

Contracts and advanced tools

run-contract owns numeric requests, run layout, atomic publication and curated exports. architecture explains domain ownership. docs index lists every specialized feature and QA procedure. sprite-gen --help derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with video-loop --max-len or --cycle fixed, video-cycle-align --length, --between auto (the default: a made frame that melted or carries a ghost takes the nearer source frame, and a filmed ghost frame a clean one beside it; a made frame the report names as a possible cross-fade of two drawings, look, is kept — look at it, and where the legs show twice use --between nearest or film that direction again) or --between nearest, or --cycles <loop>=<k> once you have counted a suspect loop's strides, or --foot <loop>=left|right (video-set --align-foot <item>=…) once you have looked at the first strike frame of a loop the report lists under unnamed_feet), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle (loop-review) — and a clip the engine names for one: when the alignment report's retake lists a loop (reason held-drawings: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there; or filmed-ghost: a filmed ghost frame has filmed ghosts on both sides, so no clean frame stands there and the loop shows it — reasons lists both where both apply), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it (loop-repair section 4). video-loop --anchor motion-auto already cuts a walk two steps long — one cycle — where a staff held above the head closes only there (cycle.steps, strip.json steps: 2; video-cycle-align aligns it as the one cycle it is). Where the clip shows its feet pass, it counts the steps on those crossings and cuts two of them, joined at the walk's own point (cycle.step_count, steps: 2, loop-repair section 3, "The step count"). When its report's cycle.step_screen says suspect (a slow walk cut one step long, its feet not read), or video-cycle-align stops on a loop under one_step, count the steps in the loop (how often each foot lands) and cut it again with video-loop --steps 1 if it is one step (--steps 2 if it is two); never stretch or double it by hand. When video-loop warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), or that the held part does not close at the wrap below its top, that part does not close at the cut: look at the loop, and try --cycle fixed with another cut before filming again; a walk refused for no cycle names in its report's cycle.candidates the windows it measured, best first, for a cut you must deliver anyway (loop-repair section 3, "The seam pop" and "The held side").