# 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: ```text +-------------------------------------------------------------+ | 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: ```cpp 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.