SiteLink/docs/PODBAY-ECOSYSTEM.md

# The Pod Bay ecosystem — what SiteLink has to work with

Surveyed 2026-07-10 from the sibling repos under `C:\VWE`. Every claim below has a source
pointer so it can be re-verified as those repos evolve.

## 1. Physical bay composition

A Pod Bay is **an air-gapped network of ~20 computers**:

| Count | Machine | Software role |
|------:|---------|---------------|
| 1 | Command console | Operator station: TeslaConsole (pod management) + the game's console/lobby (Firestorm "BattleTech Console" ConLobby, or the era console for BT/RP) + PQS front-of-house |
| 16 | Cockpit computers | Run the game exe in pod mode (`-ctcltype 2` for Firestorm) with cockpit I/O (RIO boards → RioJoy/VRio joystick layer) |
| 1 | Live Cam station | Firestorm: game exe as camera ship (`-ctcltype 3`, `ctcl-camera.ini`) |
| 1 | Mission Review station | Firestorm: `ctcl-mr.ini`; engine has a dedicated `MSRSpectator` project (`firestorm\Gameleap\code\mw4\Code\MSRSpectator`) |
| 1 | Printer | Debriefing / scoresheet output (`printdebriefing` flag in PQS game config) |

Air-gapped is a *feature*: the cockpit boxes run era Windows images, deliberately hardened
and never internet-exposed (TeslaLauncher's `install.bat` hardens the box). SiteLink must
preserve that property — the linked fleet becomes one bigger air-gapped network, not 20×N
machines on the internet.

## 2. Addressing conventions found in the wild

- **Dev/legacy bays:** `200.0.0.x` — pods at `.1–.8` and `.11–.18`, camera ship at `.9`
  (see `firestorm\MW4\ctcl-game.ini` `[teslas]`). Note `200.0.0.0/8` is *public* address
  space — harmless while air-gapped, a real conflict once bays are routed together.
- **FS507D 2016 LAN-center release:** per-machine `10.0.0.x` (release `postinstall.bat`,
  ctcl inis) — already in RFC1918 space, and the convention the SiteLink seed proposal
  generalizes to `10.0.<site>.x`.

## 3. Components and their wire protocols

### TeslaConsole ↔ TeslaLauncher (pod management plane)
- **TCP 53290**, length-prefixed JSON frames over an OFB-encrypted stream; per-pod key
  (`TeslaSuite\Contract\PodRpcProtocol.cs`). Console provisions, installs products on,
  and launches games on pods.
- **First-boot provisioning:** UDP beacons + RSA key exchange (`TeslaSuite\SecureConfig\`)
  — *broadcast-based, local-subnet only*. Provisioning is inherently an on-site act.
- **`local.siteconfig`** (`C:\VWE\local.siteconfig`): .NET BinaryFormatter graph of
  `TeslaConsole.Squad` (mGuid, mName, mOnline) → `TeslaConsole.Pod` records:
  `mId, mIPAddress, mGateway, mDns, mSubnet, mHostName, mKey, mMacAddress, mName,
  mPodArtPath, mHostType, mOnline`. Two consequences for SiteLink:
  1. "Concatenating" siteconfigs = a real deserialize/merge/reserialize tool (or native
     multi-site support in TeslaConsole — buildable, since the console is now rebuilt
     from source). The `Squad` concept maps naturally to "one squad per site".
  2. `mKey` is the credential that lets a console command a pod. **Siteconfig files are
     secrets.** Sharing one with a master console = handing over control of your bay.
- **vPOD** (`TeslaSuite\vPOD\`): impersonates both a pod's launcher (TCP 53290) and a
  game client (Munga TCP 1501). **This is our test double for a whole remote bay** — we
  can prototype every SiteLink flow without touching cockpit hardware.

### Firestorm (MW4/Gameleap engine) — the flagship game
- **Game transport: DirectPlay 4** (`IDirectPlay4A`, TCP/IP service provider, DirectPlay
  reliable protocol enabled) — `firestorm\...\GameOS\Net_Main.cpp:387,2226`.
  - Port: registry value `DirectPlayPort` (`Games_LAN.cpp:2307`); `0` = stock DirectPlay
    ports (TCP/UDP 47624 enumeration + dynamic 2300–2400 range). Setting it fixed makes
    firewalling exact.
  - **Directed join works without broadcast:** `TryToJoinASpecificGame(szIPAddress, name)`
    builds a compound address with `DPAID_INet = host IP` and unicasts the session
    enumeration (`Net_Main.cpp:2887–2937`). Broadcast is only the "browse LAN games"
    path. **This is what makes routed (L3) site-linking viable.**
  - Player cap: compiled default **16** (`MW4Shell.cpp:13319`); engine arrays go to 255.
    A drafted, phased **16→32 plan** exists in `firestorm\CLAUDE.md` (code defaults +
    lobby UI + ≥32 drop zones per map). Two full bays in one match needs it; one bay's
    16 split across two sites does not.
  - Replication is ~O(n²) at the session host — host placement/upstream matters.
- **CTCL (cafe/Tesla control layer):** `ctcl.dll`/`ctcls.dll` + per-role inis
  (`ctcl-game.ini`, `ctcl-camera.ini`, `ctcl-mr.ini`): `[teslas]` maps pod IP → pilot
  seat; `[Games]` lines carry the exe + `-ctcltype` role; aux-message and taunt tables.
  The bay roster is **static config**, which is exactly what a site-ID-based addressing
  scheme can template.
- **Dedicated server exists:** `mw4dedicatedui` project (`...\mw4\Code\mw4dedicatedui`) —
  option to host cross-site matches on a neutral box instead of one bay's console.
- **Dormant internet-era code:** MSN Zone "GUN" matchmaking (`Games_GUN.cpp`,
  `GUNGameList.h`) and GameSpy advertisement (`Games_GSpy.cpp`) — dead services, live
  code paths; a revival hook if SiteLink ever wants a fleet-wide game browser.
- **2016 release integrated Mumble** for voice (FS507D postinstall) — cross-site voice is
  a solved problem: one Mumble server on the shared network.

### BT411 (classic BattleTech, Tesla 4.10 reconstruction)
- **Console-push model over plain TCP:** the console connects to each pod's `-net <port>`
  listener (convention 1501/1601), streams the mission egg in 1040-byte framed chunks,
  then sends `RunMission` twice (`BT411\tools\btconsole.py` documents the full wire
  format, verified against the engine).
- Pods form their mesh from the egg's `[pilots]` list; the console must stay connected
  for the duration (engine quirk: console loss also closes the game listener).
- Cross-site implication: `btconsole.py MP.EGG 10.0.1.11:1501 10.0.2.11:1501` is *already*
  a cross-site game launch, modulo whatever the pod↔pod mesh needs (open question: does
  the `[pilots]` list carry literal IPs? → see BRAINSTORM open questions).
- Status: entity/movement replication works; cross-pod combat in progress.

### Red Planet (RP411 / RP 4.11.4)
- MUNGA engine, console game-control via **Munga protocol, TCP 1501** (vendored
  `Munga Net.dll` in TeslaConsole). Same console-directed model as BT411 (shared engine
  lineage — `MUNGA_L4\L4NET.CPP`).

### PQS — Pod Queue System (front of house)
- XAMPP (Apache/PHP/MySQL) app: registration, callsigns, combined queue displays,
  history/search (`PQS\*.php`).
- The game/console side **polls simple HTTP endpoints**: `getFSgame.php` prints the next
  mission's game type/map/16 condition flags; `getFSplayers.php` the roster. MySQL db
  `pqs`, tables `pqs_gameconfig`, `pqs_queue`, `pqs_mission`.
- Single-site by construction today (localhost MySQL, one queue). Multi-site play needs
  either a shared central PQS or per-site PQS with an event/sync mode.

### Support tooling
- **VncThumbnailViewer** (`C:\VWE\VncThumbnailViewer`): operator monitoring of pod
  screens — works fine across a VPN, and a master console could reuse it for fleet-wide
  eyes-on.
- **RioJoy / VRio**: cockpit hardware I/O → joystick. Purely local to each cockpit;
  SiteLink never touches it.
- **SheepShaver**: classic-Mac emulation (the original 1990s VGL-era console stack) —
  heritage/reference only.
- **blackthorn**: archived site builds (Airlock standard install 2018, Firestorm SMT
  builds) — useful as references for how deployed sites were actually configured.

## 4. Port map (current, single bay)

| Port | Proto | Flow | Purpose |
|------|-------|------|---------|
| 53290 | TCP | console → pod | TeslaLauncher RPC (provision/install/launch), OFB-encrypted framed JSON |
| (local bcast) | UDP | pod ↔ console | SecureConfig first-boot beacons (on-site only) |
| 1501 | TCP | console → pod | Munga game control (RP; BT411 uses same convention, port per `-net`) |
| 47624 + 2300–2400, or fixed `DirectPlayPort` | TCP/UDP | pod ↔ session host | Firestorm DirectPlay 4 session + game traffic |
| 80 | TCP | console/game → PQS box | PQS HTTP endpoints |
| 3306 | TCP | PQS internal | MySQL (localhost today) |
| 64738 | TCP/UDP | all → voice server | Mumble (2016 release convention) |
| 5900 | TCP | operator → pods | VNC monitoring (optional) |