88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
npm install
|
|
npm test
|
|
```
|