# sporel-tool-mapper

Standalone CLI for v2 Sporel map files: encode/decode packed-u32 GIDs, build maps from a text DSL, and inspect stats.

## Install

This is part of the Sporel monorepo workspace. No npm publish — clone the repo and run via `node bin/mapper.js` or symlink the bin entry into `$PATH`.

```bash
node bin/mapper.js <subcommand> [args...]
```

Requires Node ≥18. Zero runtime dependencies.

The `bin` entry in `package.json` exposes the command as `sporel-mapper`, so once globally installed or symlinked into `$PATH` you can invoke `sporel-mapper <subcommand>` directly in place of `node bin/mapper.js <subcommand>`. The examples below use the `node bin/mapper.js` form.

## Subcommands

### `encode <atlas_idx> <tile_id> [rotation]`

Print the packed-u32 GID for the given components.

```bash
$ node bin/mapper.js encode 0 12 1
196
```

### `decode <gid>`

Print the components of a GID. Accepts decimal or `0x...` hex. `gid=0` prints `empty`.

```bash
$ node bin/mapper.js decode 196
atlas=0 tile=12 rotation=1

$ node bin/mapper.js decode 0
empty
```

### `build <spec.txt> <out.json> [--atlas-dir <path> ...]`

Compile a text-DSL map spec into a v2 map JSON file. See `docs/dsl.md` for full syntax (in `sporel-meta`, design spec §4). Minimal example:

```
id border_demo
size 8 8
atlas fa_terrain_v1
layer surface
  fill 0 0 7 7 fa_terrain_v1:grass_field
  set 3 3 fa_terrain_v1:stone_wall_brick rot 1
```

```bash
$ node bin/mapper.js build map.txt out.json --atlas-dir ../sporel-libs/lib-asset/prototype-fa-starter/assets/atlases
```

If the DSL has no `id` directive the output filename basename is used.

### `inspect <map.json> [--atlas-dir <path> ...]`

Read-only stats report. Without `--atlas-dir`, atlas references show as indices only; with it, atlas-id and tile names are resolved.

```bash
$ node bin/mapper.js inspect demo.map.json --atlas-dir ../sporel-libs/lib-asset/prototype-fa-starter/assets/atlases
```

## Encoding

GIDs use the same packed-u32 layout as `lib-core.maps` (see `sporel-libs/lib-core/maps/init.lua`):

```
bit  31 ...... 24 | 23 ............ 4 | 3 .. 2 | 1 .. 0
     [ atlas:8  ] [   tile_id:20    ] [ rot:2 ] [res:2]
```

`gid=0` is the canonical empty cell.

## Tests

```bash
npm test
```

Uses Node's built-in `node --test` runner. No mocking framework.

## Spec

`docs/superpowers/specs/2026-05-23-sporel-tool-mapper-design.md` in the `sporel-meta` repo.