Asset lint and fix (para art)
para art lint and para art sheet check pixel-art sheets without any image generation
or network calls (Nim, no ML). Build the CLI with nimble build, or run a command directly:
nim c -r tools/para/para.nim art lint path/to/sheets
nim c -r tools/para/para.nim art sheet path/to/sheets --out tmp/contact-sheet.png
Each <name>.png needs a <name>.art.toml sidecar declaring its cell size, style profile, optionally the key colour it was keyed from (for the key rule),
and any per-asset lint waivers (a game's own manifest of this eventually replaces hand
files here). lint checks against one of two built-in example profiles, lowbit and
hibit (once named punchclub, still accepted everywhere a profile is read) - defaults a game overrides once it writes its own art/style.toml (found by
walking up from each linted sheet to the repo root, nearest first; --style PATH overrides
it), whose profile key names the profile it overrides and whose optional
palette (a .hex file path, relative to the style.toml) turns on palette membership for every asset
(except kind = "tile" ground tiles), whatever profile its sidecar names. Each run prints a
style: line per profile saying where its values came from. See tools/para/art/ for the
checks and tests/fixtures/art/ for the twelve sheets the scout report linted (one a synthetic
stand-in; see its CREDITS.md). A sheet
whose declared cells don't tile it (even with a grid waiver) prints unmeasured for its
per-cell columns and fails cells unmeasured, never a silent pass.
para art fix cleans up one raw or degraded sprite at a time, and writes the <name>.art.toml sidecar for each output (cell, profile, pivot and key) so lint can follow it directly. Steps:
background key to hard alpha, pixel-grid recovery, palette lock (when art/style.toml sets
one; not for --tile), orphan-pixel cleanup, a fixed cell with a pivot, and content slicing. Needs
uv on PATH; the pixel work runs as uv run --locked --project tools/art python -m para_art_fix (tools/art/, dependencies pinned in tools/art/uv.lock,
no network calls once uv sync has run once). No image generation, no GPU.
nim c -r tools/para/para.nim art fix path/to/sprite.png --cell 64x64 --profile hibit --out tmp/art/fix
--cell WxH names the sprite's native size (skip it to let pixel-art-fixer/unfake.py
detect it, rejecting a result larger than the profile's biggest cell; a source of a different aspect is padded, never stretched - see tools/art/README.md); fix also snaps the sprite to the profile's colour cap; --pivot and --profile
take a sidecar's pivot/profile values and --style mirrors lint's. --key RRGGBB always keys that colour (pixels that
are already transparent stay so). Without it, keying runs only on a flat key background: an input
that already has transparent pixels (a transparent PNG, a repo sprite, a rerun on fix's own output)
isn't re-keyed, and the four corners must agree on a colour; otherwise nothing is keyed and the
output's key column and help say to pass --key RRGGBB to force keying. Background is flood-filled from the image border
over pixels close (in RGB distance) to the key colour; an enclosed pocket is keyed too when it is
a connected region of at least 4 pixels whose mean colour is close to the key sampled from that
border fill, so a lone key-coloured pixel or a dark key-tinted outline stays sprite.
--fit content trims each source to its opaque bounding box and scales it to fill the --cell less --margin PCT (default 5, every side), bottom-aligned, with one scale shared by every file in the call so one character's poses keep their relative size; --figure-height PX pins the tallest figure instead (details: tools/art/README.md). --outline opts into a last step that recolours offending boundary pixels so the hibit outline rule passes (details and refusals: tools/art/README.md). Stray key-coloured pixels that survive keying are stripped, and lint's key rule fails any left when the sidecar names a key. --key-border-only skips pockets and that strip, for art that uses the key colour inside the sprite. --tile --cell WxH is the mode for one opaque seamless ground tile (no keying or outline; lint's kind = "tile" rules include a 3x3 seamless check; recipe in tools/art/README.md, "Ground tiles"). An output that would overwrite another asset's input or output in the same run fails
instead. Outputs are only (re)written when their decoded pixels
differ from what's already there, so a rerun on already-fixed art changes 0 files. That
guarantee covers the default invocation; an explicit --key keys that colour again even on a rerun. See
tests/test_art_fix_regression.nim for the report's own §6.3 regression numbers (exact
native size, at most 1% of sprite pixels off, 0 pixels changed on a rerun), reproduced here
by degrading real repo sprites in code rather than committing new art.