ddafcd6486
Sprite-mode bake gains an additive --pixels-per-meter flag. When set, the value is written into sprites.uv.json under atlas_meta. pixels_per_meter. Consumers (lib-core.render path-1 via per-entity sprite_scale) divide their project canonical px/m by this number to auto-scale the rendered quad — atlas-native resolution no longer needs to match the project tile-scale. Unset (legacy bakes): atlas_meta omitted, byte-equal to v0.3.0 output. Tests: 53/53 pass; existing buildUvJson test continues to assert the unset-default shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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).
v0.3.0 adds --mode sprite for diffuse-only atlases of irregularly-sized
sprites with an alias→UV-table sidecar (sprites.uv.json) + stable alias-set
lock for re-bakes. Tilemap-mode remains the default for backward compatibility.
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, irregularly-sized standalone 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