Files

Axel Meyer ae2885a453 Expand README with concrete usage examples

Covers all four subcommands, the GID bit layout, the test runner,
and a pointer to the design spec in sporel-meta.

2026-05-23 17:01:06 +02:00

2.1 KiB

Raw Blame History

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.

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.

2.1 KiB Raw Blame History