Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Recolor — deterministic palette-swap bake + colourway pick — sprite-gen reference
Owns: Deterministic palette-swap bake, colourway pick,
variants/and its report · Index: docs/README.md
Split out of the
SKILL.mdhub. Follow this doc when you need to bake N colour variants of one base sheet from a palette map, or when the curation webview is comparing and adopting those baked colourways. Implementation:sprite_gen/effects/recolor.py. View surface:sprite_gen/serve/curator/src/recolor.js+serve_curation._recolor_info.
Why bake, not tint at runtime
Dot art lives and dies by palette control. A baked sheet is QA-able pixel by pixel, costs the renderer nothing, and keeps every colourway under the same geometry contract as the base atlas. Runtime shaders/filters are out of scope — they reintroduce anti-aliased edge bleed and cannot be diffed as assets.
Same input bytes → same output bytes. The bake does no floating-point
resampling; it rewrites RGB only and preserves alpha, so a base
manifest.json.frame_layout describes every variant sheet.
Triggers (agent routing)
Use this path when the user says any of:
- KR: 팔레트 스왑, 팔레트 베이크, 리컬러, 색깔 바꾸기, 컬러웨이, 색 변형, 팔레트 맵, 색갈이, recolor 해줘
- EN: palette swap, recolor, colourway / colorway, bake variants, palette map, recolour the sheet
Not this path: live tint filters, shader recolor, one-off hand-painted recolours that skip the bake report.
Commands
Two subcommands share the module. The console script, the module form, and the
scripts/recolor.py wrapper all reach the same cli.COMMANDS entry (identity,
not a copied flag list — see tests/test_recolor_cli_entrypoint.py).
1. Draft a palette map from a base sheet
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor-palette \
--base <sheet.png> \
--out <palette.json>
- Scans opaque pixels (
alpha > 8by default — same floor as compose-gif). - Emits distinct colours ordered by frequency (desc), then hex (asc) — a total order, so two runs of the same sheet produce the same draft.
--max-colors Nkeeps the top-N only and reports how many pixels were dropped (dropped_colors_pixels) — never a silent cap.- Without
--out, the JSON goes to stdout.
Draft kind: "kind": "sprite-gen-palette". This is authoring scaffolding, not a
swap. Edit the hex list into a recolor spec (next section).
2. Bake N variant sheets from a recolor spec
# Against a finished run dir (default atlas = sprite-sheet-alpha.png,
# default out = <run-dir>/variants/, manifest auto-resolved if present):
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor \
--run-dir <run-dir> \
--spec <recolor-spec.json>
# Against a free-standing sheet (out-dir required):
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor \
--base <sheet.png> \
--spec <recolor-spec.json> \
--out-dir <out-dir> \
[--manifest <manifest.json>]
Exactly one of --base or --run-dir. Two truths for one input are refused.
Flags:
| Flag | Default | Role |
|---|---|---|
--atlas |
sprite-sheet-alpha.png |
filename inside --run-dir |
--out-dir |
<run-dir>/variants (with --run-dir) |
where sheets + report land |
--manifest |
auto <run-dir>/manifest.json if present |
propagate per-variant, repointing sheet-filename fields |
--alpha-threshold |
8 |
opaque floor; sub-threshold pixels keep RGB, are not targets |
--report |
recolor.report.json |
report filename inside out-dir |
Also available as:
$SPRITE_GEN_ROOT/.venv/bin/python -m sprite_gen.cli recolor ...
$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/recolor.py ...
Recolor spec
{
"version": 1,
"kind": "sprite-gen-recolor",
"match": "exact",
"tolerance": 0,
"variants": [
{
"name": "moss",
"map": {
"#b42828": "#3a7a3a",
"#f0c000": "#c8a040"
}
},
{
"name": "azure",
"map": {
"#b42828": "#2850b4",
"#f0c000": "#80c0e0"
}
}
]
}
kindmust besprite-gen-recolor— anything else fails loud.match:exact(default) — a pixel's RGB must equal a source colour to be replaced. Dot art's safe default: anti-aliased edge pixels stay untouched.tolerance— opt-in for soft-edged art. An opaque pixel within Chebyshev distancetoleranceof a source is recoloured to that source's target; nearest source (L2) wins, ties broken by map order. Pure integer arithmetic, so still deterministic.
match: "exact"with a non-zerotoleranceis contradictory and refused — two truths for one behaviour.- Variant
names must be unique; every variant needs a non-emptymap. - Map keys/values are
#RRGGBB(orRRGGBB). A source mapped twice fails loud.
Bake outputs
Under --out-dir (default <run-dir>/variants/):
variants/
moss.png
azure.png
moss.manifest.json # only with --manifest
azure.manifest.json
recolor.report.json # SSoT for "what the bake did"
Geometry is never touched — only RGB on matching opaque pixels. Alpha is
byte-identical to the base sheet. Manifest sheet-filename fields that are
rewritten per variant (when --manifest is set): atlas, game_input,
sprite_sheet_alpha, sprite_sheet. Unknown schema keys are copied verbatim.
Report contract (No Silent Fallback)
recolor.report.json (kind: "sprite-gen-recolor-report") is the one truth for
what the bake did. Per variant it records:
| Field | Meaning |
|---|---|
substituted_pixels |
total opaque pixels rewritten |
substitutions[] |
per source→target hit count (pixels: 0 = source never matched) |
unused_sources[] |
the subset of substitutions with pixels == 0 (typos in the map) |
passthrough_pixels / passthrough_color_count |
opaque colours the map did not cover — left unchanged, but named and counted |
passthrough_colors[] |
top colours by frequency (capped at 64; over-cap is announced as passthrough_colors_truncated, never silent) |
A colour outside the map is never quietly left behind without a name. The
curation view prints these numbers from the report — it does not re-count
pixels. Reader: sprite_gen.effects.recolor.load_report(run_dir).
- No report file →
None("this run has no variants"). - A file at the report path with a foreign
kind→ fail loud. Reading it as "no variants" would hide a bake that wrote somewhere unexpected.
Curation webview — colourway compare and pick
After a bake into <run-dir>/variants/, open the ordinary curation view:
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen curation --run-dir <run-dir>
The server attaches a recolor block to /api/run (serve_curation._recolor_info).
The view (curator/src/recolor.js) shows:
- One stacked stage — all variant sheets occupy the same place; hovering a list row swaps the visible sheet in place (blink comparison). Side-by-side eye travel loses small palette shifts; blink does not.
- Frame-cell thumbnails — one cell cropped from the sheet, not the whole
atlas. The crop box comes from
manifest.frame_layout(first frame of the first state). Origin assumptions are forbidden; no layout → no crop style. - Adopt button — writes the chosen variant name into the curation sidecar.
Adopted pick SSoT
{
"version": 1,
"kind": "sprite-gen-curation",
"recolor": { "picked": "moss" }
}
- Keyed by variant name, not a frame index. A colourway is a colour
decision, not a frame generation — re-baking does not stamp it stale the way
anchors do. Reader:
curation.recolor_pick(curation). - A name that the current bake no longer produces is kept and reported as
pickedKnown: false(banner in the view). It is never silently cleared. - A save from a run that has no recolor section does not author the field; the
server carries the existing pick over (same contract as
anchors). An unrelated edit cannot erase an adopted colourway. - File tree shows a
variants/folder with an adopt badge on the picked name.
Schema detail and the rest of the sidecar live in curation.md.
Typical workflow
# 1. Compose the base atlas first (or start from any finished sheet).
$SPRITE_GEN_ROOT/.venv/bin/python \
$SPRITE_GEN_ROOT/scripts/compose_sprite_atlas.py --run-dir <run>
# 2. Draft the palette from the base sheet.
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor-palette \
--base <run>/sprite-sheet-alpha.png \
--out <run>/palette.draft.json
# 3. Author the recolor spec (edit the draft hex list into source→target maps).
# Save as e.g. <run>/recolor.spec.json with kind "sprite-gen-recolor".
# 4. Bake every colourway in one command.
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen recolor \
--run-dir <run> \
--spec <run>/recolor.spec.json
# 5. Compare and adopt in the curation view.
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen curation --run-dir <run>
Ship the adopted sheet from <run>/variants/<picked>.png (and its sibling
manifest if one was propagated). The base atlas stays the geometry SSoT.
What this is not
- Not a runtime filter. The game loads a baked PNG.
- Not a second atlas composer. Geometry, cell size, and
frame_layoutcome from the base; recolor only rewrites colours. - Not a silent repair tool. Unused sources and passthrough colours are always in the report — fix the map, do not paper over a miss.
Related
../SKILL.md— hub, trigger routing, script mapcuration.md— webview +curation.jsonschema (recolor.picked)run-contract.md— run-dir folder tree (variants/)tests/test_recolor_bake.py— determinism, exact/tolerance, report contracttests/test_recolor_curation_view.py— view payload, pick round-trip, fail-loud foreign reporttests/test_recolor_cli_entrypoint.py— CLI identity across entry formstests/test_recolor_docs.py— doc surface lock (hub + leaf teach the same commands)