sporel-tool-mapper/README.md

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.

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.

$ 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.

$ 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

$ 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.

$ 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

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.