# 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

```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, 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:

```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
```