Files
lilygo-t-deck/src/netdeck/STATUS.md
T
Dejvino b38d5d4b56 Extract map-specific data into a generic MapSource interface
One interface (nd_mapsource.h) now owns everything map-specific: tiles,
rooms/doors/cameras, the network graph (nodes + edges with roles replacing
the hardcoded N_AIRLK/N_DOOR/N_HIVE indices) and the entity spawn list.
The scenario populates its structures once via selectMap() and never checks
which map is active.

- DemoMapSource: self-contained demo grid (moved out of the sketch), demo
  node/edge/spawn tables
- GenMapSource: adapts the random MapGenerator — now with L-corridors for
  guaranteed connectivity, doors that lead somewhere, airlock pad, terminal
  and crates (never on corridor tiles); network graph derived from the room
  chain, marine-first spawn list with droid patrols
- NetDeck.ino: all source branching removed; red trace follows the real
  active-link path (BFS HIVE->ROOT); reinforcement spawns near the blast door
- Tests: MapTest validates 50 generated runs + demo via the interface with
  an airlock flood-fill; new generated-map integration journey; test node
  handles resolve through the source (no hardcoded indices)
2026-11-15 18:21:35 +01:00

18 KiB
Raw Blame History

NetDeck — Breach & Board: Milestone Status

Source of truth for gameplay/architecture: DESIGN.md. This file tracks milestone progress (DESIGN.md §7). Update it when a milestone lands.

Milestone Scope Status
M0 — Emulator SDL2 emulator support + M1 surface tested locally done
M1 — Hardware Sandbox Full-frame sprite rendering to ST7789, shared tactical view + HUD, cursor, Space freeze, P view switch compiled + emulator-verified; on-device check pending
M2 — Network Graph & Traces 4-node sub-net in shared space (AIRLK→JUNC→DOOR/HIVE), animated link routing (1.5 s / 3.0 s ICE), door control, red trace → feedback spike + OVERHEAT, X sever, R reset done (emulator-verified)
M3 — Squad vs. Droids 2 marines (BFS to the player beacon, continue walking while firing), patrol/stationary droids, heavy droid + ceiling turret on the terminal, cover crates, tracers/HP bars, win/loss banners, reinforcement on feedback spike done (emulator-verified; firmware build fixed)
M3 — Squad vs. Droids Ship floorplan in Cameras view, 3 marines → beacon, 4 droids, gunfire planned
M4 — Cyber-Physical Bridge Hive link + 1 FRENZY.EXE turns droids on each other (shared coordinate space) done

M0 (done)

  • src/netdeck/nd_layout.h — shared constants: 320x192 tactical view + HUD bar (one coordinate space), palette, fixed-timestep timings.
  • examples/NetDeck/NetDeck.ino — sandbox app: 40x24 demo floorplan and an 8-node sub-net graph in the same coordinate space (door nodes pinned to their bulkhead door tiles); two view modes — Cameras (full ship view, network as dotted outlines) and Network (ship dimmed ~35%, full graph with labels and packets), switched with P (Tab kept as legacy alias); trackball cursor (edge-ISRs + momentum, tile snap in Cameras / node target in Network); keyboard @ 0x55 (Space freeze, 1-4/X/R groundwork); tap-to-cursor via GT911; 20 Hz sim accumulator (pause-verified frame-identical).
  • Emulator: make APP=NetDeck run / smoke from emulator/; host gained Tab key mapping (emulator/src/main.cpp).

M1 (this milestone)

  • Flicker-free full-frame rendering (examples/NetDeck/NetDeck.ino): all drawing goes into a RAM second buffer — TFT_eSprite fb (PSRAM, 320x240x16) on device, the SDL shim framebuffer in the emulator — and is pushed as one continuous SPI stream (present() → startWrite() / fb.pushSprite(0,0) / endWrite()), the proven MiataDrive anti-tearing pattern (commit d542d6f).
  • Firmware build: self-contained examples/NetDeck/platformio.ini (pio run -d examples/NetDeck; board + libs resolved against the repo root boards/ and lib/). ESP32-S3 / arduino-esp32 2.0.9: RAM 6.7%, Flash 5.5%, binary at firmware/NetDeck_M1_261114.bin.
  • Keyboard bring-up: stale-byte flush from the 0x55 controller at boot end (before the first frame), on top of the 1400 ms boot grace.
  • Trackball device branch: TB_IMPULSE/TB_FRICTION constants split for device vs emulator edge rates.
  • Emulator frames are pixel-identical to the M0 baseline (regression verified: cameras / network / freeze / beacon click).

Flashing + on-device checklist (needs the physical T-Deck)

  1. pio run -d examples/NetDeck -t upload (or flash firmware/NetDeck_M1_261114.bin).
  2. Boot screen M1 // SANDBOX shows for 1.4 s, then the Cameras view.
  3. P flips to Network view (dimmed ship + labeled graph), Tab too.
  4. Space freezes (CRT scanlines, sim/packets halt); cursor stays live.
  5. Trackball: smooth momentum cursor, tile snap in Cameras, node targeting in Network; Enter = beacon drop / node select; screen tap works too.

M2 (done — emulator-verified)

Implements the sub-net half of the MVP vertical slice (MVP.md §1–§3, validation spec added in this commit) on the shared 320x192 coordinate space:

  • 3-room floorplan (airlock / main corridor / server room) with the Room2/Room3 blast door (+) and the objective terminal T.
  • 4-node sub-net pinned to map tiles: AIRLK root (always online) — JUNC — DOOR_CTRL (on the blast door tile) / HIVE (3 s ICE). Click an adjacent offline node to route a link: animated dotted line turning solid over 1.5 s (3.0 s through ICE); offline until the build completes.
  • DOOR_CTRL (once online) toggles the blast door open/closed — open doors also un-block LOS/movement for the combat milestone.
  • X severs the hovered link (distance cursor→segment): everything beyond it drops, ICE progress resets; severing during a trace resets the trace safely.
  • Red trace: cracking HIVE spawns a 4 s red pulse back to AIRLK; arrival = feedback spike → all links drop + 3 s OVERHEAT lockout (TEMP bar). FRENZY/BLIND daemons are gated until a HIVE link is up (effects land in M4).
  • R resets the scenario instantly to the paused, re-armed state (resetScenario()), which also fixes the AIRLK-root-online bug.
  • Boot goes straight into the paused encounter; HUD shows daemon slots, TEMP bar, and R: RESET.
  • Emulator host (emulator/src/main.cpp): headless testing support — repeatable --tap "x,y@frame" screen-tap injection and repeatable --type "text@frame" scheduled keyboard input.
  • Verified headlessly: full route→door→ICE→trace→feedback→cooldown run, safe-sever run (trace reset, no spike), all gating messages (NO HIVE LINK / NO UPLINK / OVERHEAT / LINK SEVERED / NO NODE), and r reset; visual frame dumps inspected.

M3 (done — emulator-verified)

Implements the combat half of the MVP vertical slice (MVP.md §1) on top of the M2 sub-net, in the same 320x192 coordinate space:

  • Squad: 2 identical marines spawning in the airlock; BFS pathfinding to the player-placed beacon (re-planned while blocked or every 8 ticks), continues walking while firing hitscan combat with inCover() cover rule (adjacent crate halves incoming hit chance), overhead HP bars + live SQUAD meters in the HUD.
  • Enemies: 1 patrolling + 1 stationary security droid in the corridor; 1 heavy droid (2 dmg) + 1 stationary ceiling turret (high ROF) guarding the objective terminal at tile (34,7). Units may not share a tile; walls and the closed blast door block both movement (BFS) and sight (Bresenham).
  • Feedback spike consequence: the M2 spike now queues a reinforcement droid spawning in the server room by the blast door.
  • Flow: win = a marine reaches the terminal (BREACH SUCCESS), loss = both marines down (SQUAD KIA); blinking 1-line banner, R resets either way. Tracers (2-tick) render in Cameras view, dimmed in Network view.
  • Emulator verification (headless, scripted taps/keys): marines clear both corridor droids; ICE→trace→feedback→reinforcement→cooldown still works on top of combat; loss path + r reset verified; frame dumps inspected (units, HP bars, tracers, banners).
  • Firmware build fix (this commit): the first M3 draft did not compile on-device — the Arduino preprocessor injects auto-prototypes above the Unit struct, and functions taking Unit&/const Unit& parameters (planPath, unitMove, inCover, acquireTarget) broke the generated prototypes. The emulator (plain C++) never sees this. All four now take a unit index instead of a reference; pio run -d examples/NetDeck is green again.
  • HUD layout fix (this commit): R: RESET no longer overlaps RESUME/PAUSE (right column re-spaced: SPACE/RESUME/R:RESET/VIEW), daemon slots and the SQUAD row got real gaps (frame-dump verified).

Known scope note: the win path is gated on M4

Scripted runs show the encounter plays out but BREACH SUCCESS is not reachable yet: the marines reliably clear the corridor droids, then die at the blast door to the heavy droid + turret. The intended counter — 1 FRENZY / 2 BLIND — lands in M4 (keys already arm and show the gating message). The litmus-test loop (crack HIVE, FRENZY the turret, dash the squad through) completes in M4; until then the loss path + reset are the verifiable branches. On-device check still pending (inherits the M1 checklist in §M1 above).

M4 (done — Cyber-Physical Bridge)

Activating FRENZY.EXE via key 1 while a HIVE link is online corrupts droid IFF targeting for 6 seconds. Infected droids turn red and shoot the nearest unit — friend or foe — causing droids in the shared coordinate space to turn on each other. This creates a tactical opening for the marines to cross open corridors or press the advantage at the blast door. The frenzy timer decrements each 20 Hz tick and expires automatically.

<script kind of boundary: This effect is the M4 centerpiece: it exploits the shared coordinate space so that a network link to the Droid Hive node directly controls local droid behavior. --> ### Map sources: generic MapSource interface (this change) All map-specific data now lives behind one interface (`nd_mapsource.h`), so the scenario populates its structures **once** (`selectMap()` → `resetScenario()`) and never checks which map is active — the demo floorplan and the random `MapGenerator` are interchangeable: - **`nd_mapsource.h`** (new): `MapSource` abstract interface exposing tiles, rooms/doors/cameras, the network graph (`NetNodeDef`/`NetEdgeDef` with **roles** `NR_ROOT/NR_DOOR/NR_HIVE/NR_CAMERA` replacing the old hardcoded `N_AIRLK/N_DOOR/N_HIVE` indices), and the entity spawn list (`UnitSpawn`, marines first — slots 0/1 are the squad). Shared helpers: role lookups (`rootNode()/hiveNode()/doorNode()`) and `findTile()` for the `'A'`/`'T'` anchor tiles. Pool bounds `MAX_NODES`/`MAX_EDGES`. - **`nd_demomap.h`** (rewritten): self-contained `DemoMapSource` — the real 24x40 demo grid (moved out of the sketch; the stale 19x38 array is gone), demo node/edge/spawn tables, blast door + room regions. `isDemo()` and the `setMapRows()` workaround were dropped as unnecessary. - **`nd_mapgen.h`** (reworked): the generator now produces playable maps — solid hull, carved rooms, **L-corridors between room centers** (full walkable connectivity; corridor tiles recorded so crates never block a link), doors only on walls that lead somewhere (with a deterministic fallback so every room gets one), airlock pad `'A'` + objective terminal `'T'` in the hive room, cover crates, and no unit letters written into the tile grid (the old code wrote `'T'` for turrets — clashing with the terminal). `GenMapSource` adapts the result to the interface: network graph derived from the room chain (AIRLK root online, HIVE on the hive room, DOOR node pinned to the hive door tile) and a marine-first spawn list with droid patrol endpoints (spawn tile ↔ room center). - **`NetDeck.ino`**: every map-source branch removed (`g_useDemoMap` is gone); node/edge tables, spawn placement, terminal/airlock anchors, reinforcement spawn point (near the blast door, hive side) and the win tile all come from the active source. The red trace now follows the actual active-link path (BFS HIVE→ROOT) instead of the hardcoded HIVE→JUNC→AIRLK segments; the reinforcement droid uses the first slot after the spawn list. - **Tests**: `MapTest.cpp` (standalone, also compiled into the firmware as before) now validates 50 generated runs + the demo source through the interface: room count, marine-first spawns, role nodes, graph connectivity from the root, and a **flood-fill from the airlock** proving the terminal and every spawn are reachable. New integration journey `generated_map_source_journey` switches the running scenario to `GenMapSource`, routes a link and steps combat, then restores the demo map. Test node handles resolve via the source (`nodeByLabel` / role globals) — no hardcoded indices left in the tests. - Verified: `make netdeck` (both targets), `make netdeck-test` — 28 unit + 8 integration + 4 E2E journeys, 0 failures; plus a 2000-run generator fuzz (all maps flood-connected, all role nodes present). ### Headless test structure Tests live in `emulator/tests/` (see its README): **unit** + **integration** suites share one fast deterministic binary (`NetDeck-tests` — 21 tests, single-TU sketch inclusion, sim stepped tick by tick), and **E2E** is a separate build (`NetDeck-e2e`) driving the real `loop()` through the device input pipeline with transcript + pixel assertions. One command from the repo root: `make netdeck-test` (`make netdeck` builds both firmware + emulator). ### Source layout (this commit) The sketch moved from `examples/NetDeck/NetDeck.ino` to `src/netdeck/NetDeck.ino`, next to `nd_layout.h` (the relative include became a plain `#include "nd_layout.h"`). Build configs stay put: `examples/NetDeck/platformio.ini` now sets `src_dir = ../../src/netdeck` (plus `-I .` for `utilities.h`), and the emulator Makefile points NetDeck's `APP_DIR` at `../src/netdeck`. `pio run -d examples/NetDeck` and `make APP=NetDeck` are both verified green from the new location. ### Emulator host: migrated SDL2 → SDL3 The shared emulator harness (`emulator/src/main.cpp`, all apps) now builds against SDL 3 (3.4.x) + SDL3_ttf. Notable API moves encountered: window creation lost the position args; renderer logical size is now `SDL_SetRenderLogicalPresentation(..., SDL_LOGICAL_PRESENTATION_LETTERBOX)`; `SDL_RenderCopy` → `SDL_RenderTexture`; event types renamed to the `SDL_EVENT_*` scheme with float mouse coords; `SDL_KeyboardEvent.keysym.sym` → `e.key.key`; the audio queue model became an audio stream (`SDL_OpenAudioDeviceStream` + `SDL_PutAudioStreamData`); frame dumps use `SDL_SaveBMP_IO`; `TTF_RenderUTF8_Blended` → `TTF_RenderText_Blended` (with explicit length) and Ubuntu installs SDL3_ttf headers under `/usr/include/SDL3_ttf` (handled via `__has_include`). The Xwayland pointer-coords workaround (global-state reconstruction, commit 260a2b3) is kept alongside the official `SDL_ConvertEventToRenderCoordinates()` until verified on this desktop. Ubuntu 24.04 → 26.04 note: SDL2 dev is now 2.24 (the floor for `SDL_GetWindowSizeInPixels`); SDL3 arrives from the repos. E2E freeze-tint pixel assertions were stale since the diagonal-stripe rework (pre-existing failures at HEAD under SDL2 too) — updated to the committed pattern, sampled away from the freeze text. Full suite green: 14 unit + 7 integration + 3 E2E journeys, 0 failures. ### Hardware fix: trackball click dead on device (fixed this commit) The sound engine zero-initialized `i2s_pin_config_t`, leaving `mck_io_num == 0`; `i2s_set_pin()` then claimed **GPIO0** — an MCLK-capable pin on the S3 and the trackball centre / BOOT line — as its MCLK output, so clicks never registered on hardware (verified with an on-device diagnostic build: `pin0=0` at idle, one latched FALLING edge). Fix: `pins.mck_io_num = I2S_PIN_NO_CHANGE` in `sound_engine.cpp`; the click now also registers on release with contact-bounce collapse (the proven `CrtTerminal` pattern). The emulator gained a GPIO-matrix pin-ownership model + edge-accurate ISR latch so this class of bug reproduces there (`e2e/trackball_click` fails on the old code, passes on the fix) — see [HW.md](HW.md). ### Sound fix: short beeps silent on hardware (fixed this commit) Two stacked defects, and both only bite real hardware — the emulator's `i2s_write` shim fed SDL directly and had no DMA ring, so neither ever reproduced there: 1. **TX DMA ring zeroing erased short sounds entirely (the real killer).** The legacy I2S driver copies `i2s_write()` data into a TX DMA ring (8 × 64 samples = 512 samples = **64 ms** @ 8 kHz) and consumes it at the sample rate; a buffer is handed back to `i2s_write()` only after the DMA finished playing it. After the last queued event the sound task called `i2s_zero_dma_buffer()`, which memsets the whole ring instantly — erasing everything not yet played. Any sound ≤ 64 ms was written into free ring space without ever blocking, so the render finished in microseconds and the zeroing wiped it before the DMA reached a single sample: **completely silent**. Sounds longer than the ring force `i2s_write()` to block, pacing rendering to real-time playback, so their beginning had already played — which is why only long beeps were audible and the threshold never moved with the fade envelope. Every game beep ≤ 80 ms (link-active 10 ms, laser 30 ms, sever 40 ms, bleep/ICE 50 ms, feedback 80 ms) sat in that dead zone. Fix: replace the instant zeroing with a **paced silence purge** — once the queue drains, write one ring + one chunk of zero samples through `i2s_write()`, which reuses each DMA buffer only after the DMA finished playing it. The sound plays out fully, then the ring loops silence (the zeroing existed to stop the tail replaying forever; the purge still does that job, without the erase race). 2. **Fade envelope ate short tones.** `envelope()` capped the fade at `total / 2`, so a 10 ms tone (80 samples) spent its whole duration in fade-in + fade-out — zero steady-state samples even if the samples had reached the DAC. Fix: cap at `total / 4` (10 ms tone now keeps ~41 steady-state samples; ≥ 50 ms tones unchanged). The emulator shim gained a TX DMA ring model (write/play cursors + a bounded "what the DAC emitted" log) so this class of bug reproduces headlessly: `unit/sound_short_tone_reaches_dac` fails on the zero_dma code and passes on the purge (A/B verified), `unit/sound_long_tone_plays_out_fully` guards the purge against truncating long tones, and `unit/shim_zero_dma_erases_unplayed` pins the model's fidelity to the legacy driver semantics. Reflash required: `pio run -t upload`.