Skip to content

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

Merge origin/main into the row scale fix

Soohong Kim5d59db466587
diff --cc docs/pixel-unfake.md
index d19ec60,da3344f..91b1a16
--- a/docs/pixel-unfake.md
+++ b/docs/pixel-unfake.md
@@@ -24,16 -24,8 +24,16 @@@ Optional `fit` object (opt-in; absent m
- `align_x` — `bbox-center` | `centroid` | `foot-centroid` (default) | `alpha-centroid`. Bbox-centering shifts the body left/right whenever a pose's content bbox width changes (extended arm/leg), which reads as per-frame horizontal jitter. `centroid` aligns the whole-alpha centroid; `foot-centroid` aligns the bottom-20% alpha (the legs), so trailing hair/capes do not pull the body off the cell axis — use it when the runtime mirrors the cell for left/right facing (flip pivots on the leg axis instead of teleporting the body). `alpha-centroid` (opt-in, perfectpixel-studio port — github.com/gykim80/perfectpixel-studio `internal/sprite/extract.go`, MIT) aligns the alpha-weighted centroid ignoring soft-matte fringe (α ≤ 10); crucially, in the `pixel_unfake` row path it is applied **per frame** instead of once per row union, so residual registration jitter from `register_row_frames` is cancelled (upstream measured σ 27.2px → 0.2px; jump arcs stay preserved via `ground_frames: false`).
- `align_y` — `center` (default) | `bottom`. Bottom pins feet to a shared baseline (`cell_height - safe_margin_y`).
- `prepare_sprite_run.py` exposes these as `--fit-resample`, `--fit-align-x`, `--fit-align-y`, and `--fit-ground-frames` / `--no-fit-ground-frames`, plus the `pixel_unfake` family below as `--fit-pixel-unfake`, `--fit-logical-height`, `--fit-palette-size`, `--fit-detail-bias`, `--fit-outline {on,off,STRENGTH}`, `--fit-pitch-hint`. CLI flags override the same keys in `--request` JSON; either way the merged result is recorded in the run's `sprite-request.json` `fit` object (SSoT).
+ `prepare_sprite_run.py` exposes these as `--fit-resample`, `--fit-align-x`, `--fit-align-y`, and `--fit-ground-frames` / `--no-fit-ground-frames`, plus the `pixel_unfake` family below as `--fit-pixel-unfake`, `--fit-logical-height`, `--fit-palette-size`, `--fit-detail-bias`, `--fit-outline {on,off,STRENGTH}`, `--fit-pitch-hint`. CLI flags override the same keys in `--request` JSON, one stderr line naming them ([run contract](run-contract.md#1-pipeline-stages)); either way the merged result is recorded in the run's `sprite-request.json` `fit` object (SSoT).
+With `fit.pixel_unfake: false`, extracted poses in each state row share one shrink
+ratio, chosen to fit the widest and tallest poses inside the cell's safe area.
+A raised or extended weapon therefore does not shrink only that pose's body.
+This preserves scale already present in the generated row; it does not repair
+size drift drawn by the image model. Alignment still follows `align_x`/`align_y`,
+and separate state rows can have different shrink ratios. The pixel-unfake path
+and standalone `fit_to_cell` calls keep their existing behavior.
+
## `pixel_unfake` mode
For true pixel-unfake output (game-ready chunky pixel art with intact 1px outlines), use the `pixel_unfake` mode instead of `resample` — it removes ALL non-integer resampling: