/sprite-gen

name: sprite-gen
version: 4.3.0
description: "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.0
depends_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.py
modes:
  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](docs/video.md) 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](docs/user-workflow.md), 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

| Task | Entry | Contract |