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]

Modes

The baker supports two output topologies:

Mode	Default	Output
`tilemap` (default)	Paired diffuse + height tiles on a fixed grid (blob-14 + collision sidecar supported)	`<atlas>.diffuse.png` + `<atlas>.height.png` + `<atlas>.atlas.json` + `<atlas>.atlas.lock.json`
`sprite`	Diffuse-only, unregelmäßige Einzel-Sprites	`<atlas>/sprites.diffuse.atlas.png` + `<atlas>/sprites.uv.json` + `<atlas>/sprites.atlas.lock.json`

Select via --mode {tilemap|sprite}. tilemap-mode is the default for backward compatibility with v0.2.0 call-sites.

Flags

Flag	Tilemap	Sprite	Meaning
`--in <source-dir>`	required	required	Source directory.
`--out <atlas-dir>`	required	required	Output directory.
`--atlas-id <id>`	required	required	Stable atlas identifier.
`--mode {tilemap\|sprite}`	default	toggle	Output topology.
`--tile-size <N\|auto>`	yes	ignored	Tile edge length.
`--max-size <N>`	yes	yes	Max atlas dimension (default 4096).
`--pad-px <N>`	yes (default 2)	yes (default 1)	Per-tile/sprite padding.
`--schema blob-14`	yes	warn+ignore	Slot validation (E1+E2).
`--strip-prefix "<s>"`	ignored	yes	Strip leading prefix from sprite filenames before alias normalisation.
`--lock <path>`	yes	yes	Reuse existing lock for stable IDs.
`--blocks-sight-pattern <re>`	yes	ignored	Regex matching tiles that block LOS.
`--verbose`	yes	yes	Detailed diagnostics.

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

Sprite-Mode Output Format

<out>/<atlas-id>/sprites.uv.json carries the alias → UV table:

{
  "atlas_id": "tcbasics",
  "atlas_size": [W, H],
  "sprites": {
    "bed1":   { "x": 0,  "y": 0, "w": 256, "h": 128, "source_file": "Bed1.png" },
    "bench1": { "x": 256,"y": 0, "w": 192, "h":  96, "source_file": "Bench1.png" }
  }
}

sprites.atlas.lock.json carries the stable alias-set + source-file mapping; pass it via --lock on re-bakes to preserve alias ordering when the input set grows. Removed aliases surface as WARN-lines on stderr (dropped from the new lock; consumers referencing the dropped alias will fail at sample-time).

Development

npm install
npm test

3.0 KiB Raw Blame History