sprite-gen

name: sprite-genversion: 3.15.0description: "Generates images and game sprites through GPT or Grok with guided provider choices, separate saved defaults, automatic cleanup and optional curation. Handles sprite requests, ordinary image generation/editing, typography logos (로고, 타이포그래피, 타이틀 글자, 타이틀 로고, wordmark, logo, title lettering: a title screen drawn with the title in it, its lettering lifted out transparent), standalone image-to-video clips (i2v, animate this still, 그록 영상, 이매진 비디오, 스틸 움직여줘, first/last frame, reference-to-video, 영상 이어붙이기, 영상 편집, extend/edit a clip), clips from a video MCP on the agent (ZCRE, 지크 MCP), chroma removal, animation atlases, video loops, 큐레이션뷰, image candidates, 팔레트 스왑, palette swap, recolor, engine exports, repeating backgrounds, projected shadows, talking face layers over body motions (말하는 얼굴, 입 맞추기, 얼굴 층, lip sync, face pack), motion/contact inspection and optional scene composition from existing assets."license: Apache-2.0depends_on:   required_bins:     - name: codex      why: "gen --provider codex (image_gen via ChatGPT OAuth)"    - name: ffmpeg      why: "video-frames (clip -> frames) and video-set"    - name: img2webp      why: "video-loop WebP with exact alpha (libwebp); Pillow's animated writer drops -exact"    - name: node      why: "face-bake: the face pack's player (sprite-gen-face-v1.mjs) picks the frames"    - name: rife-ncnn-vulkan      why: "video-loop jump repair, held-cell fill and video-cycle-align (RIFE v4.25 in-betweens, no test-time augmentation, each image padded to 128; TNTwise's rife-ncnn-vulkan release 20250112). Install once with `sprite-gen rife install` (an 830 MB zip, 45 MB kept, sha256-checked, into the user data directory); SPRITE_GEN_RIFE or PATH override it (nihui's 20221029 on PATH has no rife-v4.25: install, or set SPRITE_GEN_RIFE); SPRITE_GEN_RIFE_MODEL_NAME=rife-v4.6 runs the old model with -x -z, its frames 3.14.0's; Linux without a GPU also needs libvulkan1 mesa-vulkan-drivers. Without it, walk and run loops are cut as filmed with a warning. SPRITE_GEN_RIFE_BACKEND=torch runs the same model in PyTorch instead, for a GPU with no Vulkan (`pip install \"sprite-gen[torch]\"`, then `sprite-gen rife install --backend torch`; SPRITE_GEN_RIFE_DEVICE=cuda or cpu; SPRITE_GEN_RIFE_EXECUTOR=module:attr sends its frames to a GPU elsewhere, rife_torch.serve there)"  required_scripts:     - scripts/prepare_sprite_run.py    - scripts/generate_sprite_image.py    - scripts/gen_set.py    - scripts/generate_sprite_video.py    - scripts/video_canvas.py    - scripts/video_frames.py    - scripts/video_loop.py    - scripts/video_set.py    - scripts/extract_sprite_row_frames.py    - scripts/interpolate_frames.py    - scripts/compose_sprite_atlas.py    - scripts/preview_animation.py    - scripts/compose_selected_cycle.py    - scripts/compose_sprite_gif.py    - scripts/inspect_sprite_run.py    - scripts/score_sprite_run.py    - scripts/run_correction_loop.py    - scripts/curation.py    - scripts/serve_curation.py    - scripts/slice_sheet_cells.py    - scripts/unpack_atlas_run.py    - scripts/export_curated_pngs.py    - scripts/recolor.pymodes:   default: component-row

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

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. 멈추기

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.

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

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. 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.

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.

Every cut is read for held cells (neighbour cells showing the same picture), and by default they are filled with RIFE's frames between and the cut read again (video-loop --fill-held auto; off cuts as filmed). Tell the user each motion's poses over cells in one line from held_fill (poses/cells, before and after, e.g. 24/27 to 27/27). A run whose frames between were all refused stays as filmed and is named in a warning: line: say so with its poses over cells. A cut wanted above its clip's rate is given with --out-fps, frames between, never repeats. Details in loop repair.

A move played once (a jump, a vault: once, once-return, one-shot) carries its root motion in the strip sidecar by default, the cells unchanged: root_motion gives each cell's root (the body's mass centre, cell px), what it stands on, and each air's take-off, landing, seconds and apex; a game reads root to place each cell and moves the body on its own physics. A move cut out of a longer motion is named with video-loop --cycle once --start S --length L, a hand on something the clip does not draw with --contact hand=A:B, metres with --meters-per-px; a jump whose body crosses the canvas is named the same way, because it never comes back to a pose it left: the one-shot cut refuses it and its line names the closest return (the closest return, frames A-B, is R of its departure away), whose frames are where to start the range. To give the air its own length, gravity and speed, --air-retime gravity=G,air=T,speed=V redraws it on that parabola with RIFE's frames between; contacts and the take-off and landing stay as filmed. Tell the user each air in one line, its seconds and its apex (the summary's air, e.g. air 0.42 s, apex 0.21 m). Details in video-pipeline.

For a move over an obstacle that clears a low wall (such as a vault or a jump), paint a flat magenta plate on the green key with video-canvas --prop-plate (which requires --report), then pass that canvas report to video-frames --prop-plate <canvas report json> to erase the plate from keyed frames. The plate box lives in the canvas report, which video-frames reads directly to scale and position the erase box; there is no second copy. If the video model drew the plate off its place by even a single pixel, grey blend lines remain down its sides: tell the user if any keyed frame kept lines of the plate. Details in video-pipeline.

A pinned idle or attack whose last frame the video model drew again has its wrap blended by default (video-loop --wrap-blend auto, a redraw only; off cuts as filmed), with details in loop repair.

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

RIFE is rife-v4.25 with no augmentation by default. SPRITE_GEN_RIFE_MODEL_NAME=rife-v4.6 runs the model of 3.14.0 and before, with -x -z, to make a cut again as it was made then; a --between-cache never hands one model's frames to the other.

Without RIFE, tell the user which loops went unrepaired, which motions' held cells were not filled (held_fill.unmade, or --out-fps not met) and which airs were not retimed (air_retime.why), and offer the install; after it, cut those loops again and run video-cycle-align. 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, 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).