89 lines
2.4 KiB
Markdown
89 lines
2.4 KiB
Markdown
# 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.
|