From c66e670336e91a6fbf8cef1d3d3bbdcc13f31830 Mon Sep 17 00:00:00 2001 From: calic Date: Fri, 29 May 2026 09:33:26 +0200 Subject: [PATCH] docs(README): rewrite for v0.2 Rev 4 UI + drag-paint --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 87 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 9d37a30..ff218f8 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,16 @@ # sporel-module-map-editor -Interactive map editor for v2 Sporel map files. Click-to-paint, vertical layer-chip overlay on the left edge, collapsible atlas+tile picker bottom-left. +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: +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 @@ -16,31 +22,94 @@ With a target — copy a real map in, edit, copy back out: 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 -- **Layer chips** (left edge, vertical): top-of-stack down. `Rf` at top toggles roof-edit mode; the other eight chips select the active layer. - - **Left-click** = set active layer (or toggle roof mode) - - **Right-click** = toggle layer visibility (Rf chip ignores right-click) -- **Atlas + tile picker** (bottom-left): collapsed chip shows the active tile. Click to expand; click again or outside to collapse. -- **Status chip** (bottom-right): current mouse-cell coordinate plus a `*` when the map has unsaved changes. +- **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 | |---|---| -| `Left click` on map | Paint cell with active tile (or set roof flag in roof-mode) | -| `E` | Erase the cell under the mouse | -| `R` | Cycle rotation 0 → 1 → 2 → 3 → 0 | -| `S` | Save to disk (overwrites the work map) | +| `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 | -## Limitations (v0.1.0) +## Headless / smoke -- Tile thumbnails in the picker render as gray placeholders with tile-IDs as text — lib-core.maps v0.4.0 does not expose per-tile UVs to Lua, so visual thumbnails are a v0.2.0 task. -- Atlas list in the picker is purely informational; if a map declares multiple atlases, the active atlas is set from `state.lua` defaults at startup and cannot yet be switched via UI (v0.2.0 hit-tests inside the expanded picker). -- Engine bindings `engine.render.draw_rect_lines` and `engine.render.draw_line` are not yet registered — active-chip borders, hidden-layer strikethroughs, and the entity-slot divider will trigger runtime errors when their code paths execute. Adding the bindings is a small engine-side follow-up. -- No undo/redo, no multi-tile brush, no entity placement, no heightmap editing — see the design spec §1 for the full out-of-scope list. +`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. -## Spec +```bash +SPOREL_CI=1 ./Sporel.exe --module=map-editor # exits with rc=0 after ~0.5 s +``` -`docs/superpowers/specs/2026-05-23-sporel-module-map-editor-design.md` in the `sporel-meta` repo. +## 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`