From 8b0933bc16190d93799543d4efc46ded77a9a27a Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Thu, 9 Jul 2026 18:52:02 -0500
Subject: [PATCH] Add emulator/LAUNCH.md -- pod launch cheat-sheet (net/RP/egg
 confs, flags, mirror, shutdown)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 emulator/LAUNCH.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 emulator/LAUNCH.md

diff --git a/emulator/LAUNCH.md b/emulator/LAUNCH.md
new file mode 100644
index 0000000..36b2e51
--- /dev/null
+++ b/emulator/LAUNCH.md
@@ -0,0 +1,93 @@
+# Pod launch cheat-sheet
+
+All commands run from a **normal (non-elevated) PowerShell** at the repo root
+(`C:\VWE\TeslaRel410`). `render-bridge\launch_pod.ps1` prepends Npcap to PATH,
+stops any previous run (pod + bridge), and starts DOSBox-X + the GL render
+bridge. Do NOT launch from an elevated shell (the launcher can't stop an
+elevated previous instance).
+
+Boot to netnub-ready is ~4 min with sound (the SoundFont upload); add `-NoSound`
+to skip it.
+
+## Networked (console-driven) — the main ones
+
+```powershell
+# BT, LOOPED drops (auto-relaunches netnub per mission -- production parity)
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\net_loop.conf
+
+# BT, single mission then DOS pause (no loop)
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\net_full.conf
+
+# Red Planet, networked (single-shot; RP-native -- use the .NET console)
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\net_rp.conf -Mipmap
+
+# Network diagnostic boot (packet stack only, no game; NCSA Telnet suite on E:)
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\net_diag.conf
+```
+
+Console side:
+- **Host .NET TeslaConsole** talks to the pod directly (bridge IP 200.0.0.1 +
+  Npcap `SendToRxAdapters`; both survive reboot). RP-native.
+- **Mac SheepShaver Console 4.10** needs the mirror daemon (below), started
+  AFTER the pod is up. Drove both BT and RP historically.
+
+## Mac-console mirror (run AFTER the pod is up)
+
+```powershell
+# Lets SheepShaver Console 4.10 reach the pod (pod->Mac mirror + Mac->pod reinject)
+Start-Process pythonw 'C:\VWE\TeslaRel410\emulator\net-tools\tap2_mirror.py'
+```
+
+## Solo -egg (no console/network -- dev bypass, fast)
+
+```powershell
+# BT arena city mission (the launcher default if -Conf is omitted)
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\render-bridge\gauge_arena_sound.conf
+
+# BT arena2 / ravine variants
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\render-bridge\gauge_arena2_sound.conf
+& .\emulator\render-bridge\launch_pod.ps1 -Conf .\emulator\render-bridge\gauge_rav_sound.conf
+```
+
+## Flags (append to any launch)
+
+| Flag | Effect |
+|------|--------|
+| `-Mipmap` | mip-filter minified textures (fixes RP checkerboard-floor shimmer; harmless for BT; NON-authentic, default off) |
+| `-NoSound` | skip the ~4-min SoundFont upload (fast boot, no audio) |
+| `-NoBridge` | pod only, no GL render window |
+| `-ShowNative` | also show the native Division window (black-cleared wire-decode diagnostic) |
+| `-BridgePos '2020,20'` | move the GL render window (SDL honors it at creation) |
+
+## Shutdown
+
+```powershell
+# stop pod + bridge + mirror from their pid files
+foreach ($pf in 'pod_pid.txt','bridge_pid.txt','tap2_mirror_pid.txt') {
+  $p = Get-Content "$env:LOCALAPPDATA\Temp\vwe-pod\$pf" -ErrorAction SilentlyContinue
+  if ($p) { Stop-Process -Id $p -Force -ErrorAction SilentlyContinue }
+}
+Get-CimInstance Win32_Process -Filter "Name like 'py%'" |
+  ? { $_.CommandLine -match 'live_bridge|tap2_mirror' } |
+  % { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
+```
+
+## Reminders / gotchas
+
+- **ONE CONSOLE AT A TIME.** `netnub -p` accepts a single console connection;
+  whoever connects first owns the pod. To switch Mac <-> .NET: quit the unused
+  one, wait the pod's ~60s loop for a fresh netnub, then bring up the other.
+  Diagnose with `Get-NetTCPConnection -RemoteAddress 200.0.0.113` (owning
+  process). See NET-NOTES.md.
+- **VDB display diagnostics** (per-game head work, e.g. RP) are opt-in env vars
+  set BEFORE launching, all default-off: `$env:VDB_SCAN='1'` (VRAM content
+  locator), `$env:VDB_PALDUMP='C:\...\rppal'` (dump the 3 CLUTs),
+  `$env:VDB_BASE='0x100000'` (read-base override), `$env:VDB_REALSTRIDE='1'`,
+  `$env:VDB_APPLYMASK='1'`. See VDB-NOTES.md.
+- **RP gauges** need the granularity fix already committed
+  (REL410/RP/GAUGE/L4GAUGE.INI granularityInKB=64). See VDB-NOTES.md.
+- Confs carry the NIC on **IRQ 10** (COM2/plasma owns IRQ 3). net_loop /
+  net_full / net_rp / net_diag all have sound + plasma + the 0x340 NIC.
+
+Net map: pod 200.0.0.113, .NET console/host 200.0.0.1, Mac console 200.0.0.10,
+netnub TCP 1501.