diff --git a/README.md b/README.md index 2273ef5..878eb2b 100644 --- a/README.md +++ b/README.md @@ -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) | `.diffuse.png` + `.height.png` + `.atlas.json` + `.atlas.lock.json` | +| `sprite` | Diffuse-only, unregelmäßige Einzel-Sprites | `/sprites.diffuse.atlas.png` + `/sprites.uv.json` + `/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 ` | Directory of source tile images. | -| `--out ` | Output directory for the baked atlas + sidecars. | -| `--atlas-id ` | Stable atlas identifier written into the lock. | -| `--tile-size ` | Tile edge length in pixels, or `auto` to infer it from the source tiles. | -| `--max-size ` | Maximum atlas dimension in pixels (default 4096). | -| `--pad-px ` | Edge-replicated padding (gutter) applied around each tile, in pixels (Rev 4 §13.3). | -| `--schema ` | 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 ` | Reuse an existing lock to keep tile indices stable. | -| `--blocks-sight-pattern ` | Regex matching tile names that block line of sight. | -| `--verbose` | Print detailed per-tile diagnostics. | +| Flag | Tilemap | Sprite | Meaning | +| --- | --- | --- | --- | +| `--in ` | required | required | Source directory. | +| `--out ` | required | required | Output directory. | +| `--atlas-id ` | required | required | Stable atlas identifier. | +| `--mode {tilemap\|sprite}` | default | toggle | Output topology. | +| `--tile-size ` | yes | ignored | Tile edge length. | +| `--max-size ` | yes | yes | Max atlas dimension (default 4096). | +| `--pad-px ` | yes (default 2) | yes (default 1) | Per-tile/sprite padding. | +| `--schema blob-14` | yes | warn+ignore | Slot validation (E1+E2). | +| `--strip-prefix ""` | ignored | yes | Strip leading prefix from sprite filenames before alias normalisation. | +| `--lock ` | yes | yes | Reuse existing lock for stable IDs. | +| `--blocks-sight-pattern ` | 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 + +`//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 diff --git a/package.json b/package.json index d45a8cf..e95b9ae 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "sporel-tool-atlas-baker", - "version": "0.2.0", - "description": "Bake paired diffuse + height PNG atlases for the Sporel map-lib v0.3.0+ format. v0.2: edge-replicated padding (Rev 4 §13.3), --schema blob-14 E1 slot validation, collision.json sidecar E2 validation + pass-through, alpha-analysis opaque flag. Accepts PNG/WebP/JPG via jimp.", + "version": "0.3.0", + "description": "Bake paired diffuse + height PNG atlases for the Sporel map-lib v0.3.0+ format. v0.2: edge-replicated padding (Rev 4 §13.3), --schema blob-14 E1 slot validation, collision.json sidecar E2 validation + pass-through, alpha-analysis opaque flag. Accepts PNG/WebP/JPG via jimp; v0.3 adds --mode sprite for diffuse-only atlases of irregularly-sized sprites with alias→UV-table sidecar", "bin": { "sporel-atlas-baker": "bin/atlas-baker.js" },