Propagate the lessons from tron-room-demo's hardware bring-up back into
the canonical template, so demos are hardware-testable from day one:
- Contract change: the sketch renders into emuGfx::fb565 (320x240
uint16_t, RGB565 in PANEL WIRE ORDER - big-endian, the byte sequence
the ST7789 receives over SPI, the same convention TFT_eSprite's
primitives use). The host expands 565 to 8888 for SDL only. Native
little-endian writes look right in the emulator but show byte-swapped
on the panel (seen on hardware: BG 0x0002 -> green, fogged floor
0x0882 -> pink) - the new contract makes that bug impossible.
- Recommended sketch structure: examples/APP/Core.h holds all
rendering/logic device-agnostically (demoInit/demoInput/demoFrame);
the .cpp is a thin emulator shell. Bundled sample demonstrates it.
- New fw/ scaffold: standalone PlatformIO project (shared boards/lib,
T-Deck pin map) with DemoHW.ino driving the same core through a
TFT_eSprite frameBuffer() and reporting true fps + render/push split
over USB serial every 2 s. -O2 explicitly (pio default -Os skews
benchmarks).
- shim.h gains rgb565()/wire565() helpers; Makefile deps now include
the sketch's headers; --dump now also fires on safety-hatch exit (a
long --frames run was silently losing its dump before).
Verified: template builds + smoke renders correct 565 colors; DemoHW
builds clean for ESP32-S3 (328 KB flash).
The ST7789 receives pixel bytes high-byte-first, and TFT_eSprite's
pushSprite sends the sprite buffer raw — which is why the sprite's own
primitives store colors byte-swapped (drawPixel: color = color>>8 |
color<<8). RoomViewCore wrote native little-endian values instead, so
every pixel reached the panel byte-swapped: BG 0x0002 showed as green
(0x0200), the fogged floor 0x0882 as pink (0x8208) — exactly the
symptoms reported from hardware.
The core now stores pixels in panel wire order (toWire byteswap on
store, one 16-bit rotate per pixel); the emulator blit unswaps before
the 565-to-8888 expansion, so its output is pixel-identical. Also add
-O2 to the firmware env: PlatformIO's default -Os optimizes for size
and was likely a large part of the 13 fps report.
Split the sketch into a device-agnostic renderer core (RoomViewCore.h:
RGB565 rasterizer, camera, world sim — no emulator dependencies) plus a
thin emulator shell (keyboard pump + the 565-to-8888 presentation blit).
Add fw/ as a self-contained PlatformIO project (own platformio.ini
pointing at the shared boards/, lib/ and src/netdeck headers — per-env
src_dir is not supported by PlatformIO, so NetDeck's top-level config
stays untouched). fw/RoomViewHW.ino is the firmware twin: the core
rasterizes directly into a TFT_eSprite's frameBuffer() (16-bit, PSRAM)
and presents with the proven NetDeck startWrite/pushSprite/endWrite
pattern. The loop free-runs and reports true throughput over USB serial
every 2 s: fps + average render vs. push split.
Verified: emulator render unchanged (smoke frame identical), pio
RoomViewHW env builds clean for ESP32-S3 (346 KB flash), make netdeck
dual build green.
The face table drew the 'top' quad from corners 0-3, which sit at z0
(the base), while the real top face (corners 4-7 at z1) was backface
culled against the overhead camera — every box rendered open-topped.
Swap the two entries so the top face uses the z1 corners; the top-rim
highlight and face-center backface cull both key off face 0 and now
refer to the true top.
The sketch now draws into a 16-bit 320x240 fb565 — the ST7789 panel's
native format — using the RGB565 palette constants straight from
nd_layout.h (C_FLOOR, C_WALL, C_COVER, C_DOOR, C_AIRLOCK, C_LINK,
C_PACKET, node colors). Shading/fog are integer fixed-point on the
5/6/5 channels so the banding matches what the MCU would produce; the
desktop window sees a 565-to-8888 expansion blit that stands in for the
SPI push (which ships 565 as-is on hardware).
Vendor raylib-esp32 v1.0.3 (63db94b) under lib/ — raylib 6.x core with
the rlsw software renderer plus the ESP32-S3 port layer (SPI display
drivers, async double-buffered flush). raylib/examples, projects, tools
and logo are trimmed (~80 MB of content nothing here compiles); see
lib/raylib-esp32/VENDOR.md for provenance.
New floorplan3d-demo (emulator-template base) renders the NetDeck demo
map (nd_demomap.h) as a 3D floor plan — bulkhead walls, blast door,
cover crates, airlock pad, terminal — through the real on-device 3D
stack on the desktop:
- rcore_emu.c: desktop PLATFORM_CUSTOM layer mirroring rcore_esp32.c,
flushing the RGB565 sw-renderer buffer into emuGfx::fb instead of SPI
- raylib_emu_config.h: same module/limit defines as the device build
- HUD via 3x5 bitmap font into fb: rlsw's 2D textured-quad path
(DrawText/DrawRectangle) misplaces/flips quads and samples wrong
atlas texels in this build; the 3D path is pixel-accurate
Verified: dual build (make netdeck) green, demo smoke test clean at
~59 FPS, 600-frame stability run OK.
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