sprite-gen
"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."
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/aldegad/sprite-gen with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/aldegad/sprite-gen'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/aldegad--sprite-gen)HTML
<a href="/listings/aldegad--sprite-gen"><img src="/api/listings/aldegad--sprite-gen/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# install (Pillow, NumPy) into a fresh virtualenv — the venv is the only supported interpreter python3 -m venv .venv && source .venv/bin/activate pip install -e . sprite-gen --help
**A · atlas rows** — one still to a runtime atlas.
sprite-gen prepare --out-dir <run> --character-id <id> --base-image base.png # request, guides, prompts sprite-gen gen-set --run-dir <run> --provider codex # every state row, 4 at a time sprite-gen extract --run-dir <run> # chroma → transparent frames sprite-gen compose-atlas --run-dir <run> # sprite-sheet-alpha.png + manifest.json sprite-gen curation --run-dir <run> # (optional) pick, nudge, breathe
**B · video → loop** — one still to transparent loops (needs `ffmpeg`, `img2webp`, and your own `grok` login or `XAI_API_KEY`). Walk and run loops have their jump frames repaired and a direction set shares one cycle length through RIFE: install it once with `sprite-gen rife install`. Without it those loops are cut as filmed, with a warning ([loop-repair](docs/loop-repair.md)).
sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/ # per item: video-canvas → video → video-frames → video-loop; set/table.md names every result
Making clips through a video MCP connected to your agent? With ZCRE's (지크), the agent makes the clip on your own ZCRE account and sprite-gen cuts it: `sprite-gen video-prompt --direction side --state walk --no-last-frame` prints the prompt, then `video-frames` and `video-loop` take the mp4, and `video-cycle-align` gives a walk cut in several directions one cycle length. Walk, run and jump only, because ZCRE's Grok Imagine 1.5 has no end frame ([how](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre)).
A watch on one wrist, a pin on one side of the head? Turned over, a right-facing view puts it on the other side, so draw the left-facing views instead: `sprite-gen gen --direction side --facing left --handed "the black smartwatch=left wrist"` says where the item is in that view, `video-set --facing right,left --handed …` films each side and diagonal view both ways from its own still, and `sprite-gen handed-check` checks, frame by frame, that a colour-marked item is on the right side. Mirroring stays the default, since drawing the left views costs as much again ([how](docs/video-pipeline.md#handedness--an-item-on-one-side)).
A title logo whose letters the model draws freely? `sprite-gen logo --provider codex --text "STARFALL" --style "painted fantasy" --out-dir logo/` letters the title into a title screen first, redraws only its lettering on a chroma key and cuts it out with its glow kept, then reads the text back and refuses a misspelt logo ([logo](docs/logo.md)).
**C · utilities** — each stands alone.
sprite-gen cutout icon.png --white-check # white/ivory → matte, magenta/green → chroma engine sprite-gen slice-sheet --sheet sheet.png --chroma-key magenta --grid 3x2 # multi-figure sheet → per-cell cuts sprite-gen unpack-atlas --atlas sheet.png # finished atlas → curator-ready run (or --pngs-dir folder/)
**D · post-processing** — refine a finished sheet without regenerating.
sprite-gen recolor-palette --base <run>/sprite-sheet-alpha.png --out palette.draft.json sprite-gen recolor --run-dir <run> --spec recolor.spec.json # → <run>/variants/ sprite-gen export-aseprite --run-dir <run> # Aseprite JSON for Phaser / Flame
**E · asset tools** — each accepts existing assets, including artwork from other tools.
sprite-gen background-tile --source background.png --period 512 --overlap 32 --out tile.png sprite-gen shadow --source walk.strip.json --out-dir shadows/ sprite-gen inspect-motion --source walk.strip.json --out motion.json
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 157 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- 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:
- ```bash
- $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 |
- |---|---|---|
- | GPT image sprites | `prepare`, `gen-set --provider codex`, `extract`, compose and QA | [atlas-workflow](docs/atlas-workflow.md) |
- | Standalone video / animate a still, pin a last frame, reference images | `video` (`--image`, `--last-frame`, `--reference`) | [video](docs/video.md) |
- | Continue or edit an existing clip | `video-extend`, `video-edit` | [video](docs/video.md) |
- | 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](docs/video.md#sprite-gen-video-resume--ask-again-for-an-unfinished-generation) |
- | Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |
- | A soft part of a walk loop or cycle frames sways with the body (the Sway layer): an ellipse after `video-cycle-align`, `--read-on <sha256>` for a cut, `--stretch-floor D` for least area, `--frames` for full frames, `--breathe` for the breath drive, a flat share to move a region whole, `--gain-across` for across gain, and `--reference` for a way in or out of a loop | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |
- | Where an 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; a seam under a third moving region is not counted | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) |
- | A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import) | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) |
- | A walk or run that stops, from the clip's own start played backwards | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) |
- | Pieces of keyed clips on one canvas played as one move, at the time the caller gives | `video-chain` | [video-pipeline](docs/video-pipeline.md#9-pieces-of-clips-played-as-one-move-video-chain) |
- | Build a talking lower-face pack anchored to every frame of body motions from a reference and keyed clips. | `video-face` | [face-parts](docs/face-parts.md) |
- | Bake a voice and the pack's face layer onto body frames, optionally after a clip's own mouth and sound. | `face-bake` | [face-parts](docs/face-parts.md#face-bake) |
- | Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) |
- | 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](docs/loop-comparison.md#restoring-the-active-cut-from-source) |
- | 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`, and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories. sprite-gen never calls the MCP. | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
- | 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](docs/logo.md) |
- | 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](docs/gen.md) |
- | Pixel art the model draws directly as a grid, 8–48 px, on your Claude subscription (`claude` signed in), or without one on `ANTHROPIC_API_KEY`, **billed per call** | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
- | 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](docs/gen.md#subscription-first--openai-runs-only-when-you-chose-it) |
- | Base and direction anchors | `anchor` | [directional-anchor-workflow](docs/directional-anchor-workflow.md) |
- | Curation view or existing image candidates | `curation`, `unpack-atlas --pngs-dir` | [curation](docs/curation.md) |
- | Uniform background removal or imported sheets | `cutout`, `slice-sheet` | [sheet-slicing](docs/sheet-slicing.md) |
- | Palette swap | `sprite-gen recolor-palette`, `sprite-gen recolor` | [recolor](docs/recolor.md) |
- | Idle breathing as a post-processing layer (the Breathe layer): pixel (default, pixel art) or smooth (large illustrations, video frames: head fixed, chest breathes, shoulders follow; facing values for a turned body); smooth can choose a beat that misses the hands with `--avoid-region`, and a way in or out of a loop carries on its breath with `--loop-cells`, `--start-cell` and `--reference`; pixel can breathe round from the chest with the arms moving sideways (`--chest-round`, `--arms-x`), cells held still (`--hold-mask`), what the arms hold moving whole with them (`--props-mask`), what the arms hold behind the body (a shield hung at the back) moves the same way with the body staying in front (`--props-behind-mask`), and pieces painted one colour move together (`--props-groups colour`, so a sword's reflection follows the sword) | curation sidecar, baked by compose; or `sprite-gen breathe <frames> <out>` on a folder of loop frames | [breathing](docs/breathing.md) |
- | Engine exports | `export-aseprite`, `export-pngs` | [engine-export](docs/engine-export.md) |
- | Background recipe or repeating tile | existing `gen` / `cutout`, then optional `background-tile` | [asset-tools](docs/asset-tools.md#background-recipe) |
- | 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](docs/sheet-slicing.md#props-and-icons-sheet-scale-and-contain-fit) |
- | Standalone projected shadow | `shadow` | [asset-tools](docs/asset-tools.md#projected-shadows) |
- | Duplicate poses, foot contact and stride measurement | `inspect-motion` | [asset-tools](docs/asset-tools.md#motion-and-contact-evidence) |
- | Read a delivery for frames that show a figure's picture again and name them against hold lists | `inspect-holds` | [asset-tools](docs/asset-tools.md#frames-shown-again) |
- | Optional scene placement, lighting, camera and render | `scene-render`, `scene-inspect` | [scene](docs/scene.md) |
- | What the engine can do, for an agent or a tool to read once: every verb and argument, the providers each may call and be billed by (one JSON line, a quarter of every `--help`); a sandbox that reaches the providers through a relay: `SPRITE_GEN_<PROVIDER>_BASE_URL` (`OPENAI`, `XAI`, `ANTHROPIC`) moves a provider's calls and the files it hands back, `SPRITE_GEN_LOGINS=off` runs every call on its API key | `capabilities` | [capabilities](docs/capabilities.md), [provider addresses](docs/gen.md#provider-addresses) |
- | Defaults | `defaults show`, `defaults save` (`--codex-unavailable ask\|grok\|openai`: what to do when codex cannot run), `defaults clear` | [user-workflow](docs/user-workflow.md#one-settings-owner) |
- 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](docs/prompt-assembly.md).
- 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](docs/video-pipeline.md#one-shot-actions----cycle-autoperiodicone-shot).
- 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 once its repairs have run (`video-loop --fill-held auto`; `off` cuts as filmed, with no read again). A loop is read as a ring: a run that ends on its last cell, or a last cell that shows its first cell's picture, is filled too, the first cell kept. A hold the motion means (a run longer than three cells, a cut drawn on twos or threes, the opening and closing pose of a cut played once) stays as filmed and is listed in the strip's `holds`. 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`); for a set it aligns, that is the loop as delivered, filled at the end of the alignment. 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. An effect's lifetime, a Grok clip and `face-bake` are read and warned, not filled: pass the warning on. A cut wanted above its clip's rate is given with `--out-fps`, frames between, never repeats. Details in [loop repair](docs/loop-repair.md#7-held-cells-a-picture-shown-again-and-a-cut-at-a-higher-rate).
- Two rules. When an asset will be shown at a fixed display rate above its clip's (a 60 fps game or scene), give it at that rate with `--out-fps` (`video-cycle-align --out-fps` for an aligned set) instead of letting a cell show over several frames. Before delivering clips joined one after another, or a render made from them, run `sprite-gen inspect-holds` on it (with `--log` and `--log-figure` where the renderer draws figures at a new scale or sub-pixel place each frame, and the strips' `holds` as `--holds`) and tell the user any unlisted hold; `--gate` exits 1 where any hold is on no list.
- 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](docs/video-pipeline.md#root-motion--a-cut-played-once-where-the-body-is-what-it-stands-on-its-air).
- 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 and colour (`prop_plate.rgb`) live in the canvas report, with no second copy; `video-frames` starts from the box and finds the plate again in every frame along with any shaded side or top a model drew on it, so a plate the camera carried off, turned, or thickened into a box is erased too, and the edge pass learns the subject's colours without it. Read the three warning lines a run can print: frames where no plate was found keep whatever of it they show, and in frames where the plate or its shaded side or top meets the subject, look at the subject's edge there; tell the user what any of the three names. Details in [video-pipeline](docs/video-pipeline.md#prop-plate---prop-plate).
- 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](docs/loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again).
- 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](docs/interpreter.md).
- ## 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](docs/loop-repair.md).
- ## Contracts and advanced tools
- [run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) 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](docs/loop-review.md)) — 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](docs/loop-repair.md) section 4).
README.md · README · 199 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <h1 align="center">sprite-gen</h1>
- <p align="center"><b>One drawing in. Game-ready sprites out — as an atlas, or as transparent motion loops.</b></p>
- <p align="center">
- **English** · [한국어](README.ko.md) · [日本語](README.ja.md) · [简体中文](README.zh-Hans.md) · [Español](README.es.md) · [Français](README.fr.md)
- </p>
- <p align="center"><sub>Help cover the model API costs of developing sprite-gen with an optional <a href="https://github.com/sponsors/aldegad">GitHub sponsorship</a>. Choose your amount and a one-time or monthly contribution.</sub></p>
- <p align="center"><sub>Please wishlist <a href="https://store.steampowered.com/app/5045950/">Dungeon Sookuma on Steam</a>, a game in development by the creator of sprite-gen with part of the game art made using this tool.</sub></p>
- <p align="center">
- <a href="https://youtu.be/zVu9YlbPtog"><img src="docs/assets/hero-v2-party.gif" width="960" alt="Animated sprite-gen v2 showcase: paladin, wolf and slime" /></a>
- </p>
- <p align="center"><sub>Each character started as <b>one still image</b>. Grok Imagine brought it to life; sprite-gen extracted the transparent loops, and HyperFrames assembled this showcase.</sub></p>
- <p align="center">
- <img src="docs/assets/village-scene.gif" width="600" alt="A samurai and companions walking through a painted village with layered scenery and projected shadows" />
- </p>
- <p align="center"><sub>A separate village composition made from sprite-gen assets. This GIF preserves the 10-second video at 20 fps with a 256-colour palette.</sub></p>
- ---
- Ask an image model for a "sprite sheet" and you know what you get: a character whose face changes every frame, a background that won't key out, poses that overlap and drift off-grid, and a PNG your game engine can't actually consume. Cute demo, useless asset.
- `sprite-gen` is a Codex/Claude skill and a Python CLI that closes that gap. Give it **one base image** — it drives generation row by row, locks the character's identity, strips the chroma background to real alpha, extracts each pose as a clean transparent frame, and bakes a runtime atlas **with a machine-readable `manifest.json.frame_layout`**. Or hand the same still to a video model and get back a seamless, transparent loop per motion state. For the last 10% that generation never gets right, a **curation webview** lets you compare, reject, nudge and watch the loop live before you bake.
- For side sprites, `video-set` uses `--facing right|left` consistently across canvas placement and clip prompts. Its direction detector is **record-only by default** (`--facing-fix none`) and can be wrong even at high confidence. Use `gen --ref image.png --facing right` to request orientation in the generation prompt; `gen` otherwise preserves orientation. Prompts request direction but cannot guarantee the result. Correction is opt-in: `--facing-fix mirror`, or `gen --facing-fix regen`; review the still before using either. See [facing options](SKILL.md#side-view-facing).
- <p align="center">
- <img src="docs/assets/attack-claudecy-samurai.gif" height="160" alt="Samurai Claudecy two-handed katana cut loop">
- <img src="docs/assets/attack-claudecy-samurai-onehand.gif" height="160" alt="Samurai Claudecy one-handed katana cut loop">
- <img src="docs/assets/attack-slime.gif" height="160" alt="Slime attack loop">
- <img src="docs/assets/attack-fox-hood.gif" height="160" alt="Hooded fox attack loop">
- <img src="docs/assets/attack-paladin.gif" height="160" alt="Paladin attack loop">
- </p>
- <p align="center"><sub>v2.5.3 attack loops straight out of the video pipeline: one still each, Grok Imagine clip, frames gate, automatic loop selection. No manual cut points.</sub></p>
- ## Start with a request
- Ask for **sprites** or **an image**. The agent checks access, asks only for missing provider/motion choices, runs the existing pipeline, and delivers the files. The curation view is optional. Save your choices once to reuse separate sprite and image defaults; a one-off request does not overwrite them. [User workflow and defaults](docs/user-workflow.md).
- ## Pipelines, independent tools and scenes
- The two sprite pipelines are ordered generation flows. Tool groups contain independent commands; scene creation is an optional workflow that consumes finished assets. `sprite-gen --help` prints this map and groups commands by the code domain that owns them.
- ```mermaid
- flowchart LR
- subgraph A["A · atlas rows"]
- direction LR
- a1[prepare] --> a2["gen · gen-set"] --> a3[extract] --> a5[compose-atlas]
- a5 -.-> a4["curation (optional)"]
- a4 --> a5
- end
- subgraph B["B · video → loop"]
- direction LR
- b1[video-canvas] --> b2[video] --> b3[video-frames] --> b4[video-loop]
- end
- subgraph C["C · utilities"]
- direction LR
- c1[cutout] ~~~ c2[slice-sheet] ~~~ c3[unpack-atlas]
- end
- subgraph D["D · post-processing"]
- direction LR
- d1[recolor] ~~~ d2[export-*]
- end
- subgraph E["E · asset tools (independent)"]
- e1[background-tile] ~~~ e2[shadow] ~~~ e3[inspect-motion]
- end
- subgraph S["S · scene (optional)"]
- s1["existing assets + scene.json"] --> s2[scene-render]
- s1 --> s3[scene-inspect]
- end
- ```
- | Pipeline / tool group / workflow | What goes in → what comes out | Docs |
- |---|---|---|
- | **A · atlas rows** | one still + a list of states → `sprite-sheet-alpha.png` + `manifest.json.frame_layout`, with **Breathe** baked on idle poses | [run-contract](docs/run-contract.md) · [breathing](docs/breathing.md) |
- | **B · video → loop** | one still → per state, a seamless transparent GIF / WebP / strip, animated by Grok Imagine and cut at its true period | [video-pipeline](docs/video-pipeline.md) · [video](docs/video.md) |
- | **C · utilities** | an imported image or grid sheet → clean transparent cuts; a finished atlas → a curator-ready run | [sheet-slicing](docs/sheet-slicing.md) · [curation](docs/curation.md) |
- | **D · post-processing** | a finished sheet → deterministic colourways, Aseprite / Phaser / Flame exports | [recolor](docs/recolor.md) · [engine-export](docs/engine-export.md) |
- | **E · asset tools** | independent PNGs or animations → repeating tiles, projected shadows, motion/contact measurements | [asset-tools](docs/asset-tools.md) |
- | **S · scene** | existing assets + placement, camera and lighting → PNG frames, MP4/GIF, inspection and placement metadata | [scene](docs/scene.md) |
- Full index: [`docs/README.md`](docs/README.md). Architecture with domain and pipeline diagrams: [`docs/architecture.md`](docs/architecture.md).
- ## What you actually get
- - **A transparent sprite atlas** (`sprite-sheet-alpha.png`) — real alpha, no leftover chroma fringe, verified against white backgrounds ([why the extractor unmixes instead of peeling](docs/chroma-alpha.md)).
- - **A runtime manifest** (`manifest.json.frame_layout`) — absolute frame rectangles, per-state fps and loop flags. Your engine samples rectangles; it never guesses a grid.
- - **Breathe** — a still idle becomes a living loop, deterministic squash & stretch baked on your curated frames from one sidecar field, anatomy-aware and pixel-true ([details](docs/breathing.md)).
- - **Pixel-art that stays on grid** — the Backbone Lattice measures one grid for the whole subject and holds every cut to it ([details](docs/pixel-unfake.md)).
- - **Motion loops from video** — jumps get a tall canvas, attacks a wide one, the loop point is the clip's own period, and a one-shot action is cut rest → action → rest. Walk cycles count foot crossovers into a clean two-step loop with smoothed seams ([details](docs/video-pipeline.md)).
- - **Deterministic colourways** — `recolor` bakes N variant sheets from a palette map; same input, same output bytes ([details](docs/recolor.md)).
- - **QA you can watch** — per-state GIFs and contact sheets, so motion is judged as motion before anything ships. Cyclic locomotion (walk/run) stays experimental unless motion QA actually passes.
- - **Independent asset tools** — build repeating backgrounds, project shadows from a foot anchor, and inspect timing, duplicate poses and contact evidence. Ambiguous feet produce an unverified measurement ([details](docs/asset-tools.md)).
- - **Optional scene creation** — place existing PNGs, external frame sequences, loop strips or runtime atlases on named planes, with camera motion and shared shadow projection. Sprite generation can finish before this step ([details](docs/scene.md)).
- ## Quickstart
- ```bash
- # install (Pillow, NumPy) into a fresh virtualenv — the venv is the only supported interpreter
- python3 -m venv .venv && source .venv/bin/activate
- pip install -e .
- sprite-gen --help
- ```
- **A · atlas rows** — one still to a runtime atlas.
- ```bash
- sprite-gen prepare --out-dir <run> --character-id <id> --base-image base.png # request, guides, prompts
- sprite-gen gen-set --run-dir <run> --provider codex # every state row, 4 at a time
- sprite-gen extract --run-dir <run> # chroma → transparent frames
- sprite-gen compose-atlas --run-dir <run> # sprite-sheet-alpha.png + manifest.json
- sprite-gen curation --run-dir <run> # (optional) pick, nudge, breathe
- ```
- **B · video → loop** — one still to transparent loops (needs `ffmpeg`, `img2webp`, and your own `grok` login or `XAI_API_KEY`). Walk and run loops have their jump frames repaired and a direction set shares one cycle length through RIFE: install it once with `sprite-gen rife install`. Without it those loops are cut as filmed, with a warning ([loop-repair](docs/loop-repair.md)).
- ```bash
- sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/
- # per item: video-canvas → video → video-frames → video-loop; set/table.md names every result
- ```
- Making clips through a video MCP connected to your agent? With ZCRE's (지크), the agent makes the clip on your own ZCRE account and sprite-gen cuts it: `sprite-gen video-prompt --direction side --state walk --no-last-frame` prints the prompt, then `video-frames` and `video-loop` take the mp4, and `video-cycle-align` gives a walk cut in several directions one cycle length. Walk, run and jump only, because ZCRE's Grok Imagine 1.5 has no end frame ([how](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre)).
- A watch on one wrist, a pin on one side of the head? Turned over, a right-facing view puts it on the other side, so draw the left-facing views instead: `sprite-gen gen --direction side --facing left --handed "the black smartwatch=left wrist"` says where the item is in that view, `video-set --facing right,left --handed …` films each side and diagonal view both ways from its own still, and `sprite-gen handed-check` checks, frame by frame, that a colour-marked item is on the right side. Mirroring stays the default, since drawing the left views costs as much again ([how](docs/video-pipeline.md#handedness--an-item-on-one-side)).
- A title logo whose letters the model draws freely? `sprite-gen logo --provider codex --text "STARFALL" --style "painted fantasy" --out-dir logo/` letters the title into a title screen first, redraws only its lettering on a chroma key and cuts it out with its glow kept, then reads the text back and refuses a misspelt logo ([logo](docs/logo.md)).
- **C · utilities** — each stands alone.
- ```bash
- sprite-gen cutout icon.png --white-check # white/ivory → matte, magenta/green → chroma engine
- sprite-gen slice-sheet --sheet sheet.png --chroma-key magenta --grid 3x2 # multi-figure sheet → per-cell cuts
- sprite-gen unpack-atlas --atlas sheet.png # finished atlas → curator-ready run (or --pngs-dir folder/)
- ```
- **D · post-processing** — refine a finished sheet without regenerating.
- ```bash
- sprite-gen recolor-palette --base <run>/sprite-sheet-alpha.png --out palette.draft.json
- sprite-gen recolor --run-dir <run> --spec recolor.spec.json # → <run>/variants/
- sprite-gen export-aseprite --run-dir <run> # Aseprite JSON for Phaser / Flame
- ```
- **E · asset tools** — each accepts existing assets, including artwork from other tools.
- ```bash
- sprite-gen background-tile --source background.png --period 512 --overlap 32 --out tile.png
- sprite-gen shadow --source walk.strip.json --out-dir shadows/
- sprite-gen inspect-motion --source walk.strip.json --out motion.json
- # Only with known same-foot contact and an isolated foot ROI:
- sprite-gen inspect-motion --source walk.strip.json --contacts 0:4 --foot-box 20,70,32,10 --out stance.json
- ```
- **S · scene** — an optional composition workflow. The [scene contract](docs/scene.md) includes a complete spec.
- ```bash
- sprite-gen scene-render --spec scene.json --out-dir render/ --formats png,mp4 --export-layers
- sprite-gen scene-inspect --spec scene.json --out scene-check.json
- ```
- The agent-facing workflow, gates and contracts live in [`SKILL.md`](SKILL.md).
- ## Install as a skill
- ```bash
- python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
- --repo aldegad/sprite-gen --path . --name sprite-gen
- ```
- Image generation is part of this engine (`sprite_gen.gen`, providers `codex` and `grok` on a subscription you already pay for, plus an `openai` provider for servers and SaaS that bills per call and runs only when you chose it; the general `image-gen` skill is a thin shuttle over it). Every call uses **your own** credential, the subscription login first and an API key only without one, and nothing is shipped with the repo:
- | Calls | First | Without it | Docs |
- |---|---|---|---|
- | `gen --provider codex` | the `codex` ChatGPT login | (a codex signed in with an API key bills that key) | [gen](docs/gen.md) |
- | `gen --provider grok`, `video*` | the `grok` CLI login | `XAI_API_KEY` | [gen](docs/gen.md#direct-grok-calls-and-authentication), [video](docs/video.md) |
- | `pixel-draw` | the `claude` (Claude Code) subscription login | `ANTHROPIC_API_KEY` | [pixel-draw](docs/pixel-draw.md#which-credential-a-call-runs-on) |
- | `gen --provider openai` | — | `OPENAI_API_KEY`, only when you chose it | [gen](docs/gen.md#subscription-first--openai-runs-only-when-you-chose-it) |
- A call on an API key is billed per call and says so on stderr before the request leaves, also inside `gen-set` and `video-set`. A call that names no provider runs on codex; when codex cannot run (not signed in, or its usage used up) it stops and asks (exit 75) — or runs what you chose for that with `sprite-gen defaults save --codex-unavailable grok|openai` ([gen](docs/gen.md#when-codex-cannot-run--ask-or-what-you-chose)). `logo` makes its images and its text checks through `gen`'s providers, on the same credentials.
- `sprite-gen` supports CPython 3.11+; CI runs only 3.14. Python 3.10 is no longer supported. The quickstart needs a Python with working `venv`/`ensurepip`.
- ## Attribution
- The component-row workflow is inspired by the Apache-2.0 licensed `hatch-pet` skill, but targets generic game sprite atlases and includes no pet packages or pet visual assets.
- Community contributions, experiments, and their originating pull requests are documented in [`CONTRIBUTORS.md`](CONTRIBUTORS.md).
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.