sporel/sporel-tool-atlas-baker
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(atlas-baker): sprite-mode section + flag-table per-mode + version 0.3.0

Browse Source
This commit is contained in:
Axel Meyer
2026-06-16 21:37:36 +02:00
parent f1447b68aa
commit 0780f90c58
2 changed files with 49 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@@ -23,23 +23,58 @@ sporel-atlas-baker \
[--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 | 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. |
| 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