sprite-gen

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.

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	Required side direction.
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.

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.

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
Grok video sprites	video-set	video-pipeline
Ordinary image or edit	gen --provider codex or gen --provider grok (subscription routes)	gen
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 or a fallback	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
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, defaults clear	user-workflow

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 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). Without it every loop is still cut, as filmed, and says so: a warning: line on stderr, jump_repair.applied: false in the loop report, 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 canonical extraction with temporary crop scripts while presenting the result as a pipeline output.