sporel-tool-atlas-baker/README.md

sporel-tool-atlas-baker

Builds paired diffuse + height PNG atlases for the Sporel map-lib v0.3.0+ format.

v0.2.0 adds edge-replicated padding (Rev 4 §13.3), --schema blob-14 slot validation (E1), a collision.json sidecar (E2 validation + pass-through), and alpha-analysis that sets a per-tile tile.opaque flag. Source tiles may be PNG, WebP, or JPG (decoded via jimp).

Usage

sporel-atlas-baker \
  --in <source-dir> \
  --out <atlas-dir> \
  --atlas-id <stable-id> \
  [--tile-size 64 | auto] \
  [--max-size 4096] \
  [--pad-px <N>] \
  [--schema blob-14] \
  [--lock <existing-lock.json>] \
  [--blocks-sight-pattern <regex>] \
  [--verbose]

Flags

Flag	Meaning
--in <source-dir>	Directory of source tile images.
--out <atlas-dir>	Output directory for the baked atlas + sidecars.
--atlas-id <stable-id>	Stable atlas identifier written into the lock.
--tile-size <N|auto>	Tile edge length in pixels, or auto to infer it from the source tiles.
--max-size <N>	Maximum atlas dimension in pixels (default 4096).
--pad-px <N>	Edge-replicated padding (gutter) applied around each tile, in pixels (Rev 4 §13.3).
--schema <blob-14>	Slot-validation schema for the source set. blob-14 is the v0.2 14-slot blob schema (E1); required by lib-core.maps v0.5.1.
--lock <existing-lock.json>	Reuse an existing lock to keep tile indices stable.
--blocks-sight-pattern <regex>	Regex matching tile names that block line of sight.
--verbose	Print detailed per-tile diagnostics.

See sporel-meta/docs/superpowers/specs/2026-05-21-map-multi-layer-design.md §4 for the format spec.

Development

npm install
npm test