Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

docs: transparency strategy per provider, v1.60.0

Soohong Kima344ecc4929d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79af451..a1ab641 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## v1.60.0 - Native Alpha
+
+- `sprite-gen gen --transparent` now follows a per-provider transparency strategy declared once on each adapter (`Provider.transparency`). `codex` asks `image_gen` for a genuinely transparent background and publishes the measured alpha (`native`, first choice); `grok` keeps deterministic chroma keying because Grok Imagine returns JPEG only.
+- Added `--alpha-mode auto|native|chroma`. `auto` reads the provider's strategy, `chroma` forces keying on codex for prompts that already carry a key background, and `native` on a chroma-only provider fails before any model call.
+- Native output is verified before publishing: no alpha channel or 0% transparent pixels refuses the run (a drawn checkerboard is never keyed silently), RGB under alpha 0 is scrubbed, and partial alpha is reported untouched.
+- Reports carry an `alpha` block (`strategy` plus stats) next to the existing `chroma` stats, and codex's own `transparentBackground` claim under `extra.transparent_background_reported`.
+- Sprite-row generation is unchanged: rows still carry the request chroma key and are keyed at extraction.
+
## v1.59.0 - Contributor Collection
This release incorporates accepted work from eight community pull requests. Thanks to [@devswha](https://github.com/devswha) for chroma color preservation, [@bokjk](https://github.com/bokjk) for portable manifest paths, [@Dongkyu-ES](https://github.com/Dongkyu-ES) for deterministic CLI tests, engine export, and subject-aware sparse-frame handling, [@napkn34](https://github.com/napkn34) for the Windows provider and publish-lock fixes, and [@monibu1548](https://github.com/monibu1548) for pixel-unfake vertical centering and grounding controls.
diff --git a/README.md b/README.md
index f56879d..1bb7a3e 100644
--- a/README.md
+++ b/README.md
@@ -247,8 +247,10 @@ python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-githu
Provider-backed generation is part of this engine (`sprite_gen.gen`), with
`codex` and `grok` as the supported providers. The general `image-gen` skill is
only a thin shuttle to the same command, so it does not need a second provider
-implementation. See [`docs/gen.md`](docs/gen.md) for the CLI and verification
-contract.
+implementation. Transparent stills follow a per-provider strategy: `codex` asks
+`image_gen` for a real alpha channel (native, first choice) and the measured alpha
+is published; `grok` is keyed out of a chroma background. See
+[`docs/gen.md`](docs/gen.md) for the CLI and verification contract.
## Attribution
diff --git a/SKILL.md b/SKILL.md
index ddf4aea..21947f8 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: sprite-gen
-version: 1.59.0
+version: 1.60.0
description: "Generate clean 2D game sprites and animation atlases with a component-row pipeline: base identity, numeric sprite-request SSoT, per-state layout guides, image-gen row strips, chroma-key alpha cleanup, connected-component frame extraction, cell-based atlas composition, QA reports, and runtime manifest frame_layout. Its curation webview also serves ANY image-candidate set (icons, logos, generated drafts) — agent chat can't render images, this can: unpack_atlas_run --pngs-dir import, then serve_curation side-by-side compare/pick. Palette-swap bake (`sprite-gen recolor`) turns a base sheet + palette map into N colourway sheets; the curation view blink-compares and adopts a pick into curation.json.recolor.picked. Curation triggers (KR/EN): 큐레이션, 큐레이션뷰, 큐레이션 해줘, 이미지 후보 보여줘/안 보임, 나란히 비교, 골라볼게 띄워줘, curation view, show image candidates side by side, let me pick. Recolor triggers (KR/EN): 팔레트 스왑, 팔레트 베이크, 리컬러, 색깔 바꾸기, 컬러웨이, 색 변형, 팔레트 맵, 색갈이, palette swap, recolor, colourway, colorway, bake variants, palette map."
license: Apache-2.0
depends_on:
@@ -245,7 +245,7 @@ $SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image
--ref <run>/base-source.<ext> --ref <run>/references/layout-guides/<state>.png
```
-Use `prompts/<state>.txt` as the prompt; save the selected image as `raw/<state>.png`. `--provider` is optional — the default is **codex** (`SPRITE_GEN_DEFAULT_PROVIDER` env overrides it; an observable grok fallback kicks in only if codex is unavailable). Pass `--provider grok` explicitly for the faster backend; codex adheres tighter to negative constraints. Default policy: [`docs/gen.md`](docs/gen.md#default-provider-selection). Keep the request chroma key on the background (extraction removes it). Reference attachment rules:
+Use `prompts/<state>.txt` as the prompt; save the selected image as `raw/<state>.png`. `--provider` is optional — the default is **codex** (`SPRITE_GEN_DEFAULT_PROVIDER` env overrides it; an observable grok fallback kicks in only if codex is unavailable). Pass `--provider grok` explicitly for the faster backend; codex adheres tighter to negative constraints. Default policy: [`docs/gen.md`](docs/gen.md#default-provider-selection). Keep the request chroma key on the background (extraction removes it) — rows are generated without `--transparent`. For **standalone stills** (`--transparent`), transparency is a per-provider strategy: **codex asks image_gen for real alpha (native, first choice)** and the measured alpha is published; grok is keyed out of a chroma background; `--alpha-mode chroma` forces keying on codex for prompts that already carry a key. Contract: [`docs/gen.md`](docs/gen.md#transparent-output--strategy-per-provider). Reference attachment rules:
**생성 동시성 (maintainer 확정 2026-07-19)**: 여러 행을 뽑는 배치는 **4동시**로 돌린다 —
`sprite-gen gen` 호출을 최대 4개 병렬 (codex 실측 4병렬까지 스로틀 없음; grok 도 4,
diff --git a/docs/gen.md b/docs/gen.md
index b84c5eb..7a00fcc 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -2,15 +2,20 @@
Generation is a first-class engine module (`sprite_gen/gen/`), not an external
skill. One call = a prompt (+ optional reference images) → one **verified** PNG on
-disk, with an optional deterministic transparent-chroma post-process. The general
-`image-gen` skill is a thin shuttle over this command.
+disk, with an optional transparent output whose strategy is decided per provider
+(native alpha or deterministic chroma keying). The general `image-gen` skill is a
+thin shuttle over this command.
Providers (Gemini/OpenRouter/fal/BytePlus are intentionally **not** included):
-| Provider | Backend | Auth | Output truth |
-|---|---|---|---|
-| `codex` | codex `image_gen` | ChatGPT OAuth | inline base64 in the session rollout jsonl, decoded deterministically |
-| `grok` | grok Imagine `image_gen` / `image_edit` | xAI OAuth | file grok is told to write, verified by PNG magic |
+| Provider | Backend | Auth | Output truth | Transparency strategy |
+|---|---|---|---|---|
+| `codex` | codex `image_gen` | ChatGPT OAuth | inline base64 in the session rollout jsonl, decoded deterministically | **`native`** — image_gen returns a real alpha channel when asked (measured, then published) |
+| `grok` | grok Imagine `image_gen` / `image_edit` | xAI OAuth | file grok is told to write, verified by PNG magic | `chroma` — Imagine returns JPEG only; generate on a key and matte it out |
+
+The strategy is declared **once**, on the adapter (`Provider.transparency`), and is
+the only place that says what a backend can do. See
+[Transparent output](#transparent-output--strategy-per-provider).
## Default provider selection
@@ -63,7 +68,7 @@ sprite-gen gen \
--prompt "…" # or --prompt-file PROMPT.txt
--out DEST.png \
[--ref REF.png ...] # repeatable; grok routes refs through image_edit
- [--transparent [--chroma-key magenta|green]] \
+ [--transparent [--alpha-mode auto|native|chroma] [--chroma-key magenta|green]] \
[--white-check CHECK.png] \
[--aspect-ratio 1:1] # grok only (1:1, 16:9, 9:16, 4:3, 3:4, auto)
[--model ID] \
@@ -73,19 +78,44 @@ sprite-gen gen \
Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image.py …` (same args).
-- **Non-transparent**: the raw PNG (chroma background included) is copied to `--out`.
-- **`--transparent`**: the raw is keyed to clean RGBA through the frame extractor's
- canonical YCbCr matte (`remove_chroma_background_ycbcr`). Generate on a `#FF00FF`
- (or `#00FF00`) background — pick the key by subject colour (magenta subjects →
- green key). Gradients and texture within that chroma family are supported. A result
- with `alpha_zero_pct: 0.0`, or any transparent pixel that still carries non-zero
- RGB, **fails loudly before the output or success report is published** (No Silent Fallback).
-- The pre-chroma raw is preserved next to the destination as `<out>.raw.png` for audit.
+- **Non-transparent**: the raw PNG (background included) is copied to `--out`.
+- **`--transparent`**: publishes a clean RGBA PNG using the provider's transparency
+ strategy (below). Either way a result with no transparent area, or any transparent
+ pixel that still carries non-zero RGB, **fails loudly before the output or success
+ report is published** (No Silent Fallback).
+- The pre-process raw is preserved next to the destination as `<out>.raw.png` for audit.
- `--report` writes a `sprite-gen-image-report` JSON: provider, prompt, out/raw paths,
- `raw_bytes`, `elapsed_seconds`, `session_id` (codex), the chroma stats, and the
+ `raw_bytes`, `elapsed_seconds`, `session_id` (codex), an `alpha` block
+ (`strategy` + the measured stats), the `chroma` stats when chroma keying ran, and the
provider-resolution fields (`provider_resolved_from`, and `provider_fallback` when a
codex→grok default fallback occurred).
+## Transparent output — strategy per provider
+
+`--transparent` does not mean "chroma key" any more. Each adapter declares the one
+strategy it can execute, and `--alpha-mode auto` (the default) follows it:
+
+| Strategy | Who | What happens | Refused when |
+|---|---|---|---|
+| `native` | `codex` (**first choice**, 2026-09-08) | The transport prompt asks image_gen for a genuinely transparent background (the bundled `imagegen` skill honours "transparent background" and keeps the generated alpha; codex reports `transparentBackground: true` on the completed item). The decoded PNG's alpha is **measured**: no alpha band or `alpha_zero_pct: 0.0` refuses to publish, RGB under alpha 0 is scrubbed, partial alpha (1–254) is left as produced and reported as `partial_alpha_pct`. | The model drew a checkerboard / flat background (RGB image) — nothing can recover alpha from that, so the run fails instead of silently keying. |
+| `chroma` | `grok` (only option), `codex` with `--alpha-mode chroma` | Generate on a `#FF00FF` (or `#00FF00`) background — pick the key by subject colour (magenta subjects → green key) — and matte it out through the frame extractor's canonical YCbCr matte (`remove_chroma_background_ycbcr`). Gradients and texture within that chroma family are supported. | `alpha_zero_pct: 0.0` after keying, or stale RGB under alpha 0. |
+
+- `--alpha-mode chroma` on codex is for prompts that already carry a key background
+ (the sprite-row pipeline today): the native request is **not** added to the prompt
+ and the raw is keyed like a grok run.
+- `--alpha-mode native` on a `chroma`-only provider **fails loud before any model
+ call** — a strategy the backend cannot execute is not a fallback candidate, and
+ native → chroma never happens silently either (the prompt shapes are different).
+- Why grok is chroma-only: Grok Imagine Image 2.0 returns `image/jpeg` from both the
+ `/v1/images/*` API and the CLI `image_gen`/`image_edit` tools, and the official
+ docs expose no background parameter — its "background removal" is a consumer-app
+ tool (4/4 drawn checkerboards on 2026-09-08). The declaration lives in
+ `sprite_gen/gen/grok_provider.py` and flips only with a new measurement.
+- Measured codex output (2026-09-08, codex 0.153.4): `alpha_zero_pct ≈ 62`, body alpha
+ ≈ 253 (so `partial_alpha_pct` is most of the subject), a ~1 px light fringe on a
+ magenta composite. Downstream extraction treats `alpha ≤ 16` as transparent, so
+ this is usable as-is; alpha snapping is deliberately not applied here.
+
## How each provider works
- **codex** — spawns a fresh `codex exec --json` in an empty sandbox
@@ -126,7 +156,10 @@ exactly that, rather than falling back on its own.
In the component-row pipeline (SKILL.md §2) generate each state row with
`--provider codex` (or `grok`) using `prompts/<state>.txt`, writing `raw/<state>.png`.
-Keep the request chroma key on the background; frame extraction removes it downstream.
+The row prompts still carry the request chroma key on the background and frame
+extraction removes it downstream — rows are generated **without** `--transparent`, so
+the native strategy does not apply to them yet (moving rows to native alpha is a
+separate, measured change).
The correction loop (`sprite-gen correction-loop --provider-command …`) can drive this
`gen` command as its regeneration step so inspect → score → hint → regenerate closes
against a real provider.
diff --git a/pyproject.toml b/pyproject.toml
index f697ed6..83b5fd0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
name = "sprite-gen"
# Release discipline: keep this package metadata version synchronized with
# SKILL.md's `version:` field in the same release commit.
-version = "1.59.0"
+version = "1.60.0"
description = "Component-row pipeline for clean 2D game sprites and animation atlases"
readme = "README.md"
license = "Apache-2.0"