116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# sporel-module-map-editor
|
||
|
||
Interactive map editor for Sporel `.map.json` files. v0.2 series ships
|
||
the Rev 4 UX architecture (see design paper
|
||
`design/2026-05-28-autotile-blob-styles-design.md` §11 in `sporel-meta`):
|
||
top toolbar with mode-switch + actions, right Layers side-panel, bottom
|
||
palette strip of material slot thumbnails, mouse drag-paint, and two
|
||
mutually-exclusive paint modes (Auto-Tile vs Direct).
|
||
|
||
## Run
|
||
|
||
Default — edit the module's in-place work map (`maps/work.map.json`,
|
||
a 16×16 schema-v3 map bound to the `blob_rect_stone` material):
|
||
|
||
```bash
|
||
bash scripts/run-map-editor.sh
|
||
```
|
||
|
||
With a target — copy a real map in, edit, copy back out:
|
||
|
||
```bash
|
||
bash scripts/run-map-editor.sh ~/Projects/Sporel/sporel-modules/spine-prototype/maps/demo.map.json
|
||
```
|
||
|
||
Or via the install layer (per `install-reference.sh`):
|
||
|
||
```text
|
||
Doubleclick C:/Games/Sporel/bin/Sporel.exe → launcher → map-editor
|
||
```
|
||
|
||
## UI
|
||
|
||
- **Top toolbar** (full-width): `Auto-Tile`/`Direct` mode buttons (mutually
|
||
exclusive, Tab toggles), `Save` (S), `Erase` (E), `Rotate` (R),
|
||
`Flip` (H), `Reset` (0), `Help` (I). Each button shows its hotkey
|
||
label inline. The active mode is highlighted.
|
||
- **Right Layers side-panel** (8 rows top-down: `canopy`, `upper_wall`,
|
||
`wall`, `lower_wall`, `topsurface`, `surface`, `subsurface`,
|
||
`foundation`). Per row: visibility eye + active marker + layer name.
|
||
- **Left-click name** → set active layer
|
||
- **Left-click eye** → toggle layer visibility
|
||
- **Right-click row** → also toggles visibility
|
||
- **Bottom palette strip**: 14 swatches (slots 1-14). Real tile
|
||
thumbnails rendered from the active atlas via
|
||
`maps.atlas_tile_uv`. Active slot has a gold border.
|
||
- **Left-click** → set active slot
|
||
- **Status chip** (bottom-left of palette band): mouse-cell, dirty flag
|
||
(`*` when unsaved), and current transform indicator
|
||
(`slot=N rot=N flip=N`) for Direct-mode awareness.
|
||
- **Auto-Tile-mode world overlay**: cell grid (1 px), vertex dots (4 px
|
||
squares), and a snapped-vertex highlight ring (green) at the nearest
|
||
vertex to the cursor.
|
||
- **Cheatsheet modal** (I): centered dim-overlay listing all hotkeys
|
||
+ LMB/RMB drag semantics.
|
||
|
||
## Modes
|
||
|
||
| Mode | LMB on canvas | RMB on canvas | Notes |
|
||
|---|---|---|---|
|
||
| **Auto-Tile** | Paints vertex at snap target — `maps.set_vertex(layer, vx, vy, true)`. Any-corner rule flips up to 4 surrounding cells to material; renderer derives slot/rot/flip from neighbour bitmask. | Clears vertex — `set_vertex(..., false)` | Transform controls ignored (slot is derived from neighbours). |
|
||
| **Direct** | Writes per-cell override — `maps.set_override(layer, x, y, {slot, rot, flip})`. Bare slot int when canonical (rot=0+flip=0). | Clears override — `maps.clear_override(layer, x, y)` | Honours active Rot/Flip from toolbar. Use to force-place a specific orientation that the auto-derived slot wouldn't pick. |
|
||
|
||
Both modes support **drag-paint**: hold LMB (or RMB) and stroke across
|
||
the canvas to apply the action at every hovered vertex/cell. UI hits
|
||
on the toolbar / side-panel / palette never enter drag-mode.
|
||
|
||
## Hotkeys
|
||
|
||
| Key | Action |
|
||
|---|---|
|
||
| `Tab` | Toggle mode (Auto-Tile ↔ Direct) |
|
||
| `I` | Show / hide cheatsheet |
|
||
| `S` | Save current map to `work.map.json` |
|
||
| `E` | Erase tile at mouse cell |
|
||
| `R` | Cycle rotation 0 → 1 → 2 → 3 → 0 (Direct-mode override) |
|
||
| `H` | Toggle flip 0 ↔ 1 (Direct-mode override) |
|
||
| `0` | Reset transform (rot=0, flip=0) |
|
||
| `Esc` | Quit |
|
||
| `LMB-drag` | Stroke-paint (mode-dependent) |
|
||
| `RMB-drag` | Stroke-clear |
|
||
|
||
## Headless / smoke
|
||
|
||
`ci_frames = 30` in `manifest.module`. The editor reads
|
||
`SPOREL_CI=1` and auto-exits after 30 frames so the smoke harness
|
||
can run it without a window-close click.
|
||
|
||
```bash
|
||
SPOREL_CI=1 ./Sporel.exe --module=map-editor # exits with rc=0 after ~0.5 s
|
||
```
|
||
|
||
## Limitations (current scope)
|
||
|
||
- **Single-atlas palette**: the palette draws from `atlas_idx=0` only.
|
||
Multi-atlas selector is a future slice. Workaround: keep one material
|
||
atlas per map for now.
|
||
- **Single Flip flag**: design paper mentions Flip-H + Flip-V as
|
||
separate controls, but the override format only stores one `flip`
|
||
field; combined with `rot` (0-3) the single flip covers all 8 D4
|
||
orientations, so the second button would be redundant.
|
||
- **No modifier hotkeys**: `lib-core.input` doesn't expose modifier
|
||
combos, so Shift+R for CCW rotation isn't supported. Workaround:
|
||
press R three times.
|
||
- **No Decal / Entity sub-selectors**: Direct mode on non-terrain
|
||
layers is unimplemented (lands in `0.2.0d`).
|
||
- **No Material-Properties modal**: `base_color` re-bake trigger
|
||
+ tint editor are deferred (also `0.2.0d`).
|
||
- **No multi-vertex brush sizes / procedural fill / undo-redo** — see
|
||
design paper §11 "Out of scope" for the full list.
|
||
|
||
## Plan + spec
|
||
|
||
- Design paper: `docs/design/2026-05-28-autotile-blob-styles-design.md`
|
||
§11 in `sporel-meta`
|
||
- Plan: `docs/superpowers/plans/2026-05-28-map-editor-blob-v2.md`
|