Files
lilygo-t-deck/src/netdeck/DESIGN.md
T
Dejvino 2bfd6c6428 NetDeck M0: emulator sandbox + design doc
- src/netdeck: DESIGN.md (RTwP cyber-tactical ship crawler for T-Deck),
  STATUS.md milestone tracker, nd_layout.h shared constants
- examples/NetDeck: M0 sandbox — 40x24 ship floorplan and 8-node sub-net
  in one shared coordinate space (door nodes pinned to bulkhead door
  tiles); Cameras/Network view modes via P (network overlaid as dotted
  outlines vs dimmed ship + full graph); trackball cursor (edge ISRs +
  momentum); Space tactical freeze with CRT scanlines; 20 Hz fixed-step
  sim (pause-verified frame-identical); keyboard @ I2C 0x55 groundwork
  for M2-M4
- emulator: APP=NetDeck support + Tab key host mapping
- platformio.ini: NetDeck src_dir ready for firmware build
2026-11-14 10:37:35 +01:00

13 KiB
Raw Blame History

Game Design Document: NetDeck — Breach & Board

Target Hardware: LILYGO T-Deck / T-Deck Plus (ESP32-S3, 320x240 ST7789 IPS Display, I²C QWERTY Keyboard, Quadrature Trackball)

Genre: Real-Time-with-Pause (RTwP) Cyber-Tactical Ship Crawler

Session Length: 10–15 minutes per run (3–5 derelict decks per sector)

Visual Style: High-contrast 16-bit cyberpunk pixel art + crisp vector network overlays (RGB565)


1. High Concept & Core Fantasy

You are not a soldier on the ground—you are the Tactical Netrunner strapped into a ruggedized portable cyberdeck in the breach airlock. Your 3-person marine fireteam is breaching derelict megacorp vessels overrun by rogue security droids and hostile ship-AI subsystems.

Your marines are brave, heavily armed, and hopelessly outmatched by armored combat droids in a straight firefight. Your T-Deck is the in-universe hardware. You pause time (Space), route signal bridges across the ship's corrupted local network, compile offensive viruses, and inject live payloads directly into enemy droids and ship systems—turning automated turrets against their masters, blinding droid optics while your squad crosses a kill-zone, or detonating an overclocked mech inside a choke point.


2. Core Gameplay Loop

  1. Infiltrate (Sector Map — 30 sec): Choose the next derelict ship compartment or cargo barge on a branching 4-node sector graph (e.g., Med-Bay, Reactor Core, Server Vault, Command Bridge).
  2. Breach & Plan (Tactical Freeze — Space): Every encounter starts paused. Inspect the 6–8 room ship cross-section in Cameras view (P to flip to Network view) — both layers share one coordinate space, so the network is always overlaid exactly on the rooms it spans. Place squad waypoint beacons and queue your initial network link.
  3. Execute & Adapt (Real-Time Simulation): Unpause. Your marines advance autonomously toward your priority beacon, taking cover and engaging targets. Simultaneously, packets flow across your network links while the enemy Ship-AI traces your intrusion and launches counter-viruses.
  4. Extract & Upgrade (1 min): Clear all hostile droids or extract the ship's Data Core. Spend harvested Scrap and Cycles to upgrade marine gear, unlock new exploit daemons, or expand your deck's RAM/thermal capacity.

3. Screen Architecture (320x240 Pixel Budget)

The 320x240 display is partitioned into a full-width Shared Tactical View plus the HUD bar. Physical reality and the logical network occupy the same coordinate space: a bulkhead door in the ship cross-section has its network Door Node rendered at the exact same spot, so a signal path visually corresponds to a physical route through the ship:

+-------------------------------------------------------------+
|              SHARED TACTICAL VIEW (320 x 192)               |
|                                                             |
|   C) CAMERAS MODE            N) NETWORK MODE                |
|   - full top-down ship view  - ship view dimmed underneath  |
|   - Marines, Droids,         - full network graph on top:   |
|     Turrets, doors             5 to 7 nodes, live packet    |
|   - network lightly           flow, ICE locks & traces,    |
|     overlaid as outlines       counter-virus waves          |
|   - Priority Beacon marker                                  |
|                                                             |
+-------------------------------------------------------------+
| DECK HUD (320 x 48)                                         |
| [1:FRENZY] [2:BLIND] [3:OVRCLK] [4:PATCH] | RAM:4/6 TEMP:42%|
| SQUAD: [M1:||||.] [M2:|||||] [3:||...]     | [SPACE: PAUSE]  |
+-------------------------------------------------------------+

  • Shared Tactical View (320x192) — two render modes over one 40x24 tile grid (8x8 tiles):
  • Cameras mode (C key / default): the physical deck is fully visible — walls, blast doors, cover crates, marines, and droids rendered in muted steel-blues and industrial grays so bright neon projectiles and virus status indicators pop immediately. The network is lightly overlaid as outlines: nodes as hollow 12x12 icon outlines, links as thin dim traces.
  • Network mode (N key): the physical view is dimmed (desaturated palette ghosts) and the network is drawn fully on top: filled 12x12 node icons, solid links pulsing with animated data packets showing bandwidth direction and trace progress, node labels.
  • P toggles between the modes at any time, including mid-freeze while planning.
  • Bottom Bar — Cyberdeck HUD (320x48): Displays your 4 slotted exploit daemons with cooldown bars, available RAM, CPU Thermal Load (overheating locks out commands for 4 seconds), your 3 marines' health/suppression pips, and the current view mode.

4. Controls & Hardware Mapping

Designed specifically around the T-Deck's dual-hand ergonomics (left thumb on QWERTY, right thumb on trackball):

Input Action Context
Space Toggle Tactical Freeze (Pause / Resume) Global (instant time-stop with CRT scanline tint)
Trackball Move Move cursor smoothly across the view Cursor snaps to tiles (Cameras) or nodes (Network)
Trackball Click Primary Action Cameras: Drop Squad Priority Beacon / Toggle Door


Network: Select Node / Route Link | | P | Switch View: Cameras ⇄ Network | Flips the render mode over the shared coordinate space; Tab is a legacy alias | | **1 – 4** | Execute / Arm Slotted Exploit Daemon | Injects selected virus into the currently targeted node | | X | Sever Link (Kill-Switch) | Immediately cuts the highlighted network bridge to stop enemy counter-hacks | | R | Order Tactical Retreat | Recalls squad toward the breach airlock | | **Q / E** | Cycle Target Node / Squad Focus | Quick keyboard-only target cycling |


5. Dual-Layer Mechanics: Squad vs. Sub-Net

A. The Boarding Squad (Autonomous Tactical AI)

You do not micromanage individual footsteps or shots. Instead, you command via Intent:

  • 3 Marine Classes:
  1. Breacher (Shotgun / Weld Torch): High armor, prioritizes front-line cover, automatically welds open sealed doors when near your beacon.
  2. Gunner (Pulse Rifle): Suppresses droids, pinning them in place and reducing their movement speed.
  3. Tech-Medic (Carbine / Nanite Kit): Automatically heals adjacent wounded marines when out of direct line-of-fire and deploys portable signal repeaters.
  • Squad AI Behavior: Marines pathfind toward your Priority Beacon using A* / BFS, automatically snapping to adjacent cover tiles when enemies enter line-of-sight.

B. The Sub-Net & Offensive Viruses

You start connected only to the Airlock Access Node. To affect droids deep inside the ship, you must establish a chain of links across intermediate junctions (Power, Comms, Security, Droid Hive).

  • Node Types:

  • Junction: Unprotected relay; fast to bridge, zero bandwidth penalty.

  • ICE-Locked Firewall: Requires holding a link for 3 seconds to crack before traffic passes through.

  • Droid Hive Node: Controls all security droids in a specific room group. Once bridged, any exploit (1-4) you trigger injects directly into every droid linked to that hive!

  • Door / Turret Controller: Toggling this node lets you slam blast doors shut (splitting enemy groups) or flip ceiling turrets to friendly fire.

  • Starter Exploit Daemons (Keys 1–4):

  1. FRENZY.EXE (2 RAM): Corrupts droid IFF targeting for 6 seconds. Infected droids immediately shoot the nearest unit—friend or foe.
  2. BLIND_OPTICS.SH (1 RAM): Floods droid visual sensors with static for 8 seconds. Accuracy drops by 80%, letting your squad rush across open corridors safely.
  3. OVERCLOCK.BIN (3 RAM): Forces droid servos past thermal limits. They move and fire 50% faster for 4 seconds, then violently explode, dealing heavy AoE damage to adjacent tiles.
  4. ICE_PATCH.SYS (1 RAM): Purges an enemy counter-virus creeping down one of your active links and cools your deck's CPU temp by 15%.

C. Enemy Counter-Hacking (The Tension Engine)

Whenever you maintain a link to a Droid Hive or Turret Node, the Ship-AI initiates a Trace:

  • A red pulse travels backward from the enemy node toward your Airlock Node along your active links.
  • If the red trace reaches your Airlock Node, it triggers a Feedback Spike: your CPU Temp jumps +50%, your active links drop, and a random room near your squad vents oxygen or spawns reinforcements.
  • Counterplay: Watch the trace pulse in real time, hit X to sever the link at the last millisecond before the spike hits your airlock, let things cool down, and re-engage from a different angle.

6. ESP32-S3 Technical Architecture

Memory & Framebuffer Budget

  • Display Buffer: 320 * 240 * 2 bytes (RGB565) = 153,600 bytes (~150 KB). Allocate two DMA-capable buffers in internal SRAM (heap_caps_malloc(153600, MALLOC_CAP_DMA)) for tear-free double-buffered SPI transfers to the ST7789 display.
  • Game State & Sprites: Store static sprite atlases (8x8 and 16x16 RGB565 bitmaps + 1-bit transparency masks) in Flash (PROGMEM / const), and keep active level grids, A* pathfinding cost maps, and particle pools in SRAM/PSRAM.

Fixed-Timestep Engine Loop

Decouple rendering from simulation so real-time combat and packet traces run deterministically regardless of frame rate:

constexpr uint32_t SIM_TICK_MS = 50; // 20 Hz deterministic logic tick
uint32_t accumulator = 0;
uint32_t last_frame_ms = millis();

void loop() {
    uint32_t now = millis();
    uint32_t dt = now - last_frame_ms;
    last_frame_ms = now;

    poll_keyboard_i2c();   // Non-blocking read from ESP32-C3 keyboard controller
    poll_trackball_gpio(); // Accumulate quadrature deltas from GPIO interrupts

    if (!game_state.paused) {
        accumulator += dt;
        while (accumulator >= SIM_TICK_MS) {
            step_network_simulation(); // Advance packet flows, ICE cracks, enemy traces
            step_squad_and_droid_ai(); // Line-of-sight checks, cover, gunfire, virus timers
            accumulator -= SIM_TICK_MS;
        }
    }

    render_tactical_view(back_buffer); // 320x192: ship tiles + network overlay,
                                       // dimmed / brightened per view mode (P)
    render_hud_bar(back_buffer);      // Bottom 320x48: daemons, RAM, Temp, squad pips
    render_cursor(back_buffer);       // Cross-mode trackball cursor

    swap_buffers_dma();               // Async SPI flush to ST7789
}

T-Deck Hardware Gotchas to Handle Early

  1. Shared SPI Bus Contention: The ST7789 display (MOSI 41, SCLK 40, CS 12, DC 11) shares the SPI bus with the SD card and LoRa module. Load any external map/audio assets from SD during mission load screens only—never touch the SD card or LoRa SPI lines inside the active render loop.
  2. Power Rail Initialization: Always set GPIO 10 (BOARD_POWERON) HIGH at the very start of setup() before initializing the display, trackball, or I²C keyboard (SDA 18, SCL 8, address 0x55), or peripherals will brown out on battery power.
  3. Trackball Acceleration: The T-Deck trackball generates raw GPIO pulses (Up 3, Down 15, Left 1, Right 2, Click 0). Apply a simple velocity multiplier (e.g., 1x for single-step precision clicks, 2.5x when >4 pulses arrive within 30 ms) so sweeping across the 320px screen feels snappy without sacrificing single-tile accuracy.

7. Minimum Viable Prototype (MVP) Milestone Plan

  • Milestone 0 — Emulator: Milestone 1 prepared and tested locally, without HW. This is an AI-native project.
  • Milestone 1 — Hardware Sandbox: Boot screen on ST7789 via DMA, render shared tactical view (Cameras + Network overlay) + HUD layout, verify smooth trackball cursor + Space pause toggle + P view switch.
  • Milestone 2 — Network Graph & Traces: Build a 6-node static network in Network view, with door nodes pinned to their bulkhead tiles in the shared space. Allow clicking nodes to form links, cracking an ICE node, and triggering a red enemy trace pulse that can be severed with X.
  • Milestone 3 — Autonomous Squad vs. Droids: Build a 6-room ship floorplan visible in Cameras view. Spawn 3 marines moving toward a clicked Priority Beacon and exchanging fire with 4 droids.
  • Milestone 4 — The Cyber-Physical Bridge: Exploit the shared coordinate space. Linking to a Droid Hive node and pressing 1 (FRENZY.EXE) turns the droids in the corresponding room red and forces them to attack each other.