Copy of the tron-demo emulator-only template with a new RoomView sketch
that renders the real demo floorplan (src/netdeck/nd_demomap.h, consumed
through MapSource) as an orbiting pseudo-3D flythrough: extruded shaded
boxes for walls/crates/door/terminal, network pylons with link packets,
patrolling entities, distance fog and checker floor. Makefile adds an
include path to ../src/netdeck instead of copying the map headers.
Replace the spinning-cube placeholder with a proper System Shock
Cyberspace fly-through (shodan.fandom.com/wiki/Cyberspace):
- Camera dragged along a gently curving data-current spline with
banking roll and weightless bob; look direction blended toward
straight-ahead so the vanishing point stays centered
- Octagonal tunnel rings + longitudinal ribs with depth fade and
near-plane segment clipping; radius swells between four named
zones (military spur / research grotto / data cistern / security
grid) via smoothstep blends
- Wiki-canon objects recycled around a 256-unit loop: data object
(purple cube), data fragment (yellow square + orange diamonds),
infonode signpost, security mine, integrity restorative, ICE
pyramid growths, and SHODAN's diamond core with Bezier tentacles
+ rotating shield ring once per loop
- NetDeck-style HUD: 3x5 bitmap font, crosshair, LNK/TRACE meters,
zone banners, DIST/VEL/NODE readouts; Space = freeze convention
- 3x3 view matrix built per frame from the path tangent; Bresenham
lines against the direct framebuffer, dimc() depth fading
Verified: clean build (0 warnings), 240-frame smoke, 5000-frame
soak, frame dumps inspected at five flight points.
The $(EMU) target only depended on main.cpp and shim.h, so editing the
sketch (.cpp) did not trigger a rebuild - stale binaries silently ran.
Add the sketch to the prerequisites; propagate to cyberspace-demo copy.
Copy of emulator-template with a TronRoom sketch demonstrating the 3D
toolkit: camera transform (forward fly + sway + bob), 1/z perspective
projection, solid shaded cubes with painter's-algorithm depth sorting,
1/z-scaled billboard entities, depth fog, and world-space scrolling
grids. Respawn margin keeps objects from straddling the camera near
plane. Includes the 60 fps pacing and Makefile sketch-dependency fix.
Copy of emulator-template with the Cyberflythrough sketch (pseudo-3D
grid flight with tracing entities). Host includes the 60 fps pacing and
delta-time Demo sample; APP defaults to Cyberflythrough.
The host busy-spun loop() with no frame limiting, so every frame-based
animation ran at desktop fps (hundreds+). Add SDL_Delay-based pacing to
the 60 Hz contract, and switch the bundled Demo to delta-time updates
(velocities in px/s scaled by measured dt) so speed is correct at any
frame rate.
Make the template foolproof to copy-and-fill for a new demo:
- examples/Conway/ replaced by a neutral examples/Demo/Demo.cpp sample
(bouncing box) documenting the full sketch contract (setup/loop,
emuGfx::fb, emuGfx::dirty, emu::keyboard)
- Makefile passes the sketch path as -DAPP_SRC; main.cpp now includes
APP_SRC instead of hardcoding Conway.cpp, window title uses APP_NAME
- Safety hatch: emulator auto-exits after 10 seconds by default so a
runaway demo can't hang and eat resources; --user-run disables the
cap, --timeout MS adjusts it (default 10000)
- README rewritten as a step-by-step recipe: replace the Demo sketch,
run 'make run'; documents all CLI flags, drops the unimplemented
--dump-interval flag
Verified: fresh copy + sketch swap builds and renders; hatch fires at
10s (and at --timeout 2000); --user-run runs until --frames cap.
Complete self-contained SDL3 emulator-only template for prototyping
sketches without hardware:
- Makefile: single-TU build (host + sketch), run/smoke/clean targets
- shim.h: minimal Arduino API shim (millis, random, String, GPIO stubs)
- src/main.cpp: SDL3 host loop presenting emuGfx::fb, CLI frame dumps
- examples/Conway: Conway.cpp sketch + .ino reference copy
- .gitignore: exclude built binaries and captured BMP frames
The Conway sketch previously started with paused=true, which prevented
render() from being called each frame, leaving the framebuffer all-black
and resulting in a black SDL3 window. Changed to paused=false so the
simulation runs immediately.
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)
- Map: 6 new wall pillars/stubs + 4 new cover crates; all load-bearing
fixtures (blast door, airlock, terminal, LOS/fog test lines) preserved
- Network: 4 -> 7 nodes, 3 -> 6 edges; new Camera node type (C_CAMERA)
sees farther (FOG_CAM_R=6 vs FOG_NODE_R=3) and draws a dotted sight
ring when online; fog radius is now a per-node sight field
- Garrison: 8 -> 12 units (room-1 patrol, server-room guard, corridor
patrol, turret on the door approach)
- Fix link slot/edge index conflation in linkOnEdge(): out-of-order
routes (e.g. JUNC-CAM1 in slot 1) shadowed JUNC-DOOR with a permanent
LINKING... refusal; NetLink now carries its edge id
- Tests: unit/fog_camera_sees_farther, unit/link_slots_dont_shadow_edges
(verified failing against the old code)
The legacy I2S driver buffers i2s_write() data in a TX DMA ring
(8x64 samples = 64 ms @ 8 kHz) and hands a buffer 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 zeroing
wiped it before the DMA reached a single sample: completely silent on
hardware. Longer tones force i2s_write() to block on a full ring,
pacing rendering to real-time playback — hence only long beeps were
audible, and the fade-envelope cap never moved the threshold. Every
game beep <= 80 ms (link-active 10, laser 30, sever 40, bleep/ICE 50,
feedback 80) sat in the dead zone. The emulator never showed it: its
i2s_write shim fed SDL directly and had no ring at all.
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(), reusing each DMA buffer only after the DMA played it. The
sound plays out fully and the ring then loops silence (still kills the
tail-replay bug the zeroing existed for). Keep the envelope cap at
total/4 so short tones keep a steady-state portion.
Emulator shim gains a TX DMA ring model (write/play cursors + bounded
DAC-emitted log) so the bug class reproduces headlessly: unit/
sound_short_tone_reaches_dac fails on the zero_dma code, passes on the
purge (A/B verified); shim_zero_dma_erases_unplayed pins model fidelity;
sound_long_tone_plays_out_fully guards against truncation. SoundEngine
gains a pumpOne() test seam and begin(spawnTask) for deterministic
driving. Full suite: 26 unit + 7 integration + 4 E2E, 0 failures.
Root cause (on device): 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. Verified on device with a diagnostic build: pin0 read
LOW at idle, exactly one latched FALLING edge, clicks never registered.
- sound_engine: set pins.mck_io_num = I2S_PIN_NO_CHANGE explicitly.
- NetDeck: register the trackball click on release with contact-bounce
collapse (the proven CrtTerminal pattern); pollTouch re-arms when
isPressed() stays true but getPoint() reports no points (stuck GT911
IRQ on some units).
- Emulator parity (so this class of bug dies before flashing):
GPIO-matrix pin-ownership model in the shim — i2s_set_pin() claims
its pins, claimed pins are dead inputs (digitalRead LOW, no edges,
loud WARNING on claim/ISR collisions); host pin writes go through
emu::setPin/togglePin with an edge-accurate ISR latch (a full
press+release pulse between dispatches no longer gets swallowed);
E2E inits SDL_INIT_AUDIO so the I2S path actually runs there.
Regression coverage: e2e/trackball_click (fails on the old engine),
unit/shim_claimed_pin_is_dead_input,
unit/shim_edge_survives_same_dispatch_pulse.
- Makefile: firmware step follows the sketch move (root platformio.ini,
src_dir = src/netdeck).
- HW.md: new notes file for emulator-vs-hardware quirks and the
on-device debugging recipe.
On-device verified: clicks register in both views (beacon drops, node
routing). Fast layer 23 unit + 7 integration green. Note: e2e
boot_and_controls + network_journey failures are pre-existing at HEAD
(reproduced on a clean stash before this change).
- Replace hardcoded with in NetDeck.ino (8 occurrences)
- Add to nd_layout.h
- Update test expectations in unit_tests.h and integration_tests.h from units[6] to units[7] to match the new reinforcement slot indexing
This enables supporting more than 7 units in the future.
Replace the fading visibility[] stub with two bitmaps over the tile grid:
fogNow (visible this tick) and fogSeen (persistent historical memory),
re-derived each sim tick via revealLos() Bresenham raycasts from:
- each living marine's 8-tile sight window (= marine fire range, so the
squad never shoots into darkness), and
- each online network node uncovering its connected tiles (3-tile window).
Rendering (renderMap): never-seen -> flat dark gray, historical ->
luma grayscale via gray565(), current -> full palette. Hostiles on
non-visible tiles are hidden in renderUnits. Ad-hoc revealTile() stamps
(marine step, door/HIVE links, hand-placed airlock tiles) removed; fog
refreshes on door toggle and scenario reset.
Tests: 5 new unit tests (initial reveal, wall blocking with face render,
historical persistence, node uncover/sever, gray565 channels) plus a
regression pinning fog sight >= marine fire range.
Port the shared emulator harness (all apps) to SDL 3.4 + SDL3_ttf 3.2:
- window creation without position args; renderer logical size via
SDL_SetRenderLogicalPresentation(LETTERBOX); SDL_RenderTexture;
SDL_SaveBMP_IO frame dumps
- SDL_EVENT_* event scheme, flattened SDL_KeyboardEvent, float mouse
coords; clicks mapped with SDL_ConvertEventToRenderCoordinates, keeping
the Xwayland global-state cross-check from 260a2b3
- audio shim on the stream API (SDL_OpenAudioDeviceStream +
SDL_PutAudioStreamData) since SDL_QueueAudio is gone
- TTF_RenderText_Blended (explicit length); SDL3_ttf header layout
handled via __has_include (Ubuntu installs under SDL3_ttf/)
- e2e freeze-tint pixel assertions updated to the committed
diagonal-stripe pattern (stale since the freeze rework; pre-existing
failures at HEAD under SDL2), sampled away from the freeze text
Full suite green: 14 unit + 7 integration + 3 E2E journeys, 0 failures.
MissileCommand, MiataDrive, NetDeck build; CrtTerminal (missing sndBlip
declaration) and Lotus3 (sketch not in repo) fail identically at HEAD -
pre-existing, out of scope.
The X server can deliver pointer event coords in a scaled space
(observed: exactly half the true window-relative position), so clicks
mapped to half the intended device coords (e.g. tile 19,11 instead of
39,23 at the map's bottom-right corner). Reconstruct the cursor position
from SDL_GetGlobalMouseState() - SDL_GetWindowPosition() (raw root
coords, unaffected by event scaling) when it lands inside the window,
falling back to the raw event coords otherwise. Also map clicks through
the SDL_RenderSetLogicalSize letterbox viewport instead of scaling
against the full window size.
- Replace static horizontal scanlines with diagonal-stripe 8x8 sprite pattern
- Color-key transparency (ND_TRANS16 = 0x1F1F) leaves frozen game view visible
- Lower triangle of each 8x8 cell dims (freeze dim), upper triangle shows game view
- Stamp pattern tiled across viewport in 8x8 grid for 50/50 dim/visible coverage
- renderFreezeTint() called only when paused, integrated into render() pipeline
- All 7 unit tests pass
- stampImage16_P(): PROGMEM 16bpp stamp with color-key transparency
(ND_TRANS16 pixels leave the destination untouched) — TFT_eSprite has
no transparent pushImage variant, so it composites via drawPixel on
both backends (sprite RAM on device, host framebuffer in the emulator)
- shim: pgm_read_byte/word/dword macros (flash is memory-mapped on
host and ESP32 alike)
- pattern: 2px checker of black dots + transparent cells — half-visible
dither, map/units stay readable underneath
- E2E now proves the transparency itself: wall pixels survive under
transparent cells, dots render black, key color never rendered
- replace the nonexistent draw16bppSprite_P(NULL,...) call with
pushImage(bx, by, 8, 8, checkered8x8): device = TFT_eSprite::pushImage
(blits into the fb sprite), emulator = new shim TFT_eSPI::pushImage
blit into the host framebuffer — same signature on both backends
- shim: define PROGMEM (no-op on host/ESP32, flash is memory-mapped)
- pattern data fixed into a real 2px checkerboard (black / 0x1F1F teal)
- E2E pixel assertions updated to the checker geometry
Verified: make netdeck (both targets) + full test suite, 0 failures
- .githooks/pre-commit: runs 'make netdeck-test-unit' (fast layer:
unit + integration) before every commit; bypass with --no-verify
- make hooks: enables the hook for a clone (core.hooksPath .githooks)
- AGENTS.md: toolchain, one-command build/test entry points, hook
install instructions, commit discipline
Builds both targets of the app in one run (pio firmware, then the SDL2
emulator) so a change can never leave one of them silently broken.
Falls back to ~/.platformio/penv/bin/pio when pio is not on PATH.
- src/netdeck/NetDeck.ino (git mv); the ../../src/netdeck include became
a plain "nd_layout.h"
- examples/NetDeck/platformio.ini: src_dir = ../../src/netdeck, -I . for
utilities.h (pio build green: RAM 8.6%, Flash 5.6%)
- emulator Makefile: NetDeck APP_DIR -> ../src/netdeck, extra -I for
utilities.h; make APP=NetDeck + smoke verified green
- STATUS.md: notes the new source layout
Combat half of the MVP vertical slice on the shared coordinate space:
- 2 marines (BFS to the player beacon, stop-and-fire hitscan), cover
crates halve incoming hit chance, overhead + HUD HP meters
- patrol/stationary security droids, heavy droid + ceiling turret on the
objective terminal; feedback spike now spawns a reinforcement droid
- win: marine reaches the terminal (BREACH SUCCESS); loss: SQUAD KIA;
R resets either way; tracers dim in Network view
- firmware build fix: Arduino auto-prototypes break Unit& params
(planPath/unitMove/inCover/acquireTarget now take unit indices)
- HUD fix: R:RESET no longer overlaps RESUME/PAUSE; daemon slots and
SQUAD row spaced out
- STATUS.md: M3 section incl. scope note — BREACH SUCCESS is gated on
the M4 FRENZY/BLIND daemons; loss path + reset verified headlessly
Implements MVP.md §1-§3 (network half of the vertical slice) on the shared
coordinate space:
- 3-room floorplan (airlock/corridor/server room) with blast door + terminal
- 4 nodes: AIRLK root - JUNC - DOOR_CTRL (on the door tile) / HIVE (3s ICE)
- animated link builds (dotted->solid, 1.5s plain / 3.0s ICE), reachability
tree from AIRLK; links offline until the build completes
- DOOR_CTRL toggles the blast door; X severs the hovered link (ICE progress
resets, trace cut short resets safely)
- cracking HIVE spawns a 4s red trace to AIRLK; arrival = feedback spike:
links drop + 3s OVERHEAT lockout (TEMP bar)
- FRENZY/BLIND daemon slots gated on HIVE link (effects land in M4)
- R instant reset via resetScenario() (also fixes root-online init bug)
- boot straight into the paused encounter
- emulator: --tap "x,y@frame" and repeatable --type "text@frame" for
headless scenario testing
Verified headlessly: full trace->feedback run, safe sever, all gating
messages, reset; visual dumps inspected. Spec: src/netdeck/MVP.md.
- render into a full-frame RAM second buffer (TFT_eSprite/PSRAM on device,
SDL shim framebuffer in the emulator) and push to the ST7789 as one
continuous SPI stream per frame (MiataDrive anti-tearing pattern)
- keyboard stale-byte flush at boot end; device-trackball constants branch
- examples/NetDeck/platformio.ini: self-contained firmware build
(pio run -d examples/NetDeck), ESP32-S3 compile verified
(RAM 6.7% / Flash 5.5%), binary at firmware/NetDeck_M1_261114.bin
- STATUS.md: M1 tracker + on-device flashing checklist
- IDEAS.md: capture map-scroll and companion-app ideas
Render every frame into a full-frame TFT_eSprite (16 bpp, PSRAM) and push
it to the panel in one continuous SPI stream — direct scattered draw calls
raced the panel scan-out and flickered. renderRoad split into projection
and draw passes: the sky now fills down to the topmost road row (fixes the
stale band at the horizon over crests) and the nearest segment is extended
to the screen bottom (fixes the wobbling stale strip). fillTrap uses
incremental edge interpolation. SPI raised to 80 MHz via build flag
(Setup210 define guarded) so the frame push fits the 33 ms budget.
sprite_tool.py gains a 'clean' subcommand that tidies the sheet in place:
drops specks (<=4px) and 1px sliver lines left over from the original
checker-keyed extractions, and re-centers every sprite in its cell
(bottom-anchored, 2px margin) so nothing touches the cell edges.
Tree trunks / palm fronds are protected from thin-line removal.
Run on the sheet: 489 junk pixels removed; re-import crops tightened
(e.g. car_white_turn 108x60 -> 92x54, car_yellow_turn 86x60 -> 80x56).
- examples/Lotus3 -> examples/MiataDrive, sketch MiataDrive.ino,
emulator target APP=MiataDrive, platformio src_dir updated
- drop the borrowed photo title background (title_bg.h): the title
screen now renders the game's own start line under the arch with the
selected car parked on the road; color picker labels sit over the
horizon, showcase car doubles as the live preview
- add dedicated README (controls, features, sprite pipeline, gallery)
- commit in-progress work the game now depends on: sound engine events
(engine hum, crash noise) plus the 4-line SDL audio shim in the
emulator host
- sprite_tool.py: export renders sprites.h into sprites_sheet.png
(1120x560, 7x4 grid of 160x140 cells, 14px label strip, magenta bg);
import cuts the sheet back into sprites.h with fixed cell order,
magenta keying, halo cut (magenta excess > 35) and despill.
Round-trip is exact via bit-replicating 565->888 expansion; crops
re-trim tighter on each import.
- sprites_sheet.png: the editable asset sheet, tracked in git.
- sprites.h regenerated by the tool (canonical sprite names).
- Drop the original webp sprite sheets; the PNG sheet is the source now.
Segment-based pseudo-3D road (curves + hills, Jake Gordon technique):
perspective trapezoid rendering near->far with hill clipping, scrolling
rumble strips and lane dashes, depth fog, low camera for planted feel.
Sprites extracted from the provided spritesheet: red Miata player car,
blue/dark/yellow traffic with collision, palms/pines/bushes/billboards,
start-finish arch, tire stacks. Off-road excursions trigger a rollover
crash animation cycling the extra car views with dust, slide and camera
whiplash; rear-ending traffic jolts the camera.
Manual driving by default (arrows/WASD, P toggles demo AI); 3 laps with
checkpoint time, score, speed HUD. SDL emulator target added to the
emulator Makefile and platformio.ini src_dir switched to Lotus3.
The hardware log showed the live mic slots sitting at ~0.6 RMS in
ambient noise. At 37.5 dB the ES7210 was clipping, so the noise floor
slowly climbed to the saturated level and the gate never fired again:
the blip appeared once and then vanished forever.
Use 18 dB analog gain so ambient levels have headroom, lower the gate
to 1.5x the floor so real sounds stand out, and widen the loudness
window to -50..-6 dBFS. The debug line now also prints the
floor-relative signal levels.
The ES7210 power-up transient is loud enough to look like the first
sound. It placed one centred blip right after init and then pinned the
mic pair to whichever slots were loudest at that instant. If that was
the wrong pair, later claps were ignored forever.
Ignore the first 800 ms after starting the codec, and re-evaluate the
mic pair on every clear sound instead of locking once. The pair only
changes after repeating for a few blocks, or immediately when the
current pair is silent while another one is loud. Also enable the
per-second rms/pair debug line so the slot mapping can be verified on
hardware.