Document Live Cam + Mission Review architecture (CAMERA-REVIEW-NOTES.md)
Researched from the readable RP MUNGA source (BT shares the engine): host roles are assigned per-IP in the mission egg (hostType= on each pilot page); a CameraShip/MissionReview host gets a CameraDirector player that auto-cuts to the top-ranked pilot every 10s, with manual flight via the same cockpit hardware as pods (CameraRIOMapper) and fixed clamped trackside cameras authored in-game into MAPS/<map>.cam. Mission Review records raw NetworkPackets (SpoolFile -> last.spl) and replays them through a networkless playback app with timestamp bias -- the replay re-simulates the battle from replication traffic. Same BTL4OPT.EXE serves every role; standing up Live Cam on the emulated pod LAN is an egg edit, not a build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,192 @@
|
|||||||
|
# Live Cam & Mission Review — how the VWE games did it
|
||||||
|
|
||||||
|
Research notes, 2026-07-08. Sources: `CODE/RP/MUNGA` + `CODE/RP/MUNGA_L4`
|
||||||
|
(the readable Red Planet tree; BattleTech shares the MUNGA engine and has the
|
||||||
|
matching `CODE/BT/BT_L4/BTL4PB.HPP` + `CODE/BT/MUNGA/SPOOLER.HPP`), the
|
||||||
|
`sda4/BTLIVE/MAPS/*.CAM` files, and the mission eggs. Everything below is from
|
||||||
|
the code itself, not conjecture, except where marked.
|
||||||
|
|
||||||
|
Both features ride the same insight: the game is a **replicated-entity
|
||||||
|
network simulation**. Every machine on the mission LAN runs the full sim and
|
||||||
|
mirrors the others' entities from network traffic (master/replicant, see
|
||||||
|
`HOST.HPP`). A spectator view is therefore just *one more host* that renders
|
||||||
|
without piloting — and a replay is just *the same network traffic played back
|
||||||
|
from a file*.
|
||||||
|
|
||||||
|
## 1. Host roles come from the mission egg
|
||||||
|
|
||||||
|
`HOST.HPP:41`:
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
enum HostType {
|
||||||
|
GameMachineHostType, // 0 — a pod
|
||||||
|
CameraShipHostType, // 1 — Live Cam station
|
||||||
|
MissionReviewHostType, // 2 — replay station
|
||||||
|
ConsoleHostType // 3 — the ops console
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
The console assigns a role to every IP on the mission when it authors the
|
||||||
|
egg. Each `[pilots] pilot=<ip>` page carries a **mandatory `hostType=` key**
|
||||||
|
(`MISSION.CPP:480` — boot aborts with *"ERROR: no host type in egg!"* if
|
||||||
|
absent). Our own `cavern.egg` shows a pod: `[200.0.0.113] hostType=0 ...`.
|
||||||
|
|
||||||
|
At player-creation time, `Registry::MakePlayer` (`REGISTRY.CPP:255`) switches
|
||||||
|
on the local host's type:
|
||||||
|
|
||||||
|
- `GameMachineHostType` → an ordinary `Player` (pod pilot);
|
||||||
|
- `CameraShipHostType` / `MissionReviewHostType` → a **`CameraDirector`**
|
||||||
|
player (the comment notes "Not a CameraShip to run on a POD!").
|
||||||
|
- Additionally, if the mission's `gamemodel` field is `"camera"`, the
|
||||||
|
player's *vehicle* gets `CameraShipPlayerFlag` — so a GameMachine host can
|
||||||
|
also fly a camera ("VTV, Mech, CameraShip w/controls" per the comment).
|
||||||
|
|
||||||
|
**The same game EXE serves every role** — pod, camera, review — chosen purely
|
||||||
|
by the egg. This is the actionable heart of it for us (§5).
|
||||||
|
|
||||||
|
## 2. Live Cam = CameraShip + CameraDirector
|
||||||
|
|
||||||
|
Classes: `CAMSHIP.HPP/CPP` (the flying camera vehicle, a `Mover` entity) and
|
||||||
|
`DIRECTOR.HPP/CPP` (the auto-director, a `Player` subclass).
|
||||||
|
|
||||||
|
- **CameraDirector** (`DIRECTOR.CPP:184 BeADirector`): every frame it checks
|
||||||
|
`timeLeftOnPlayer`; when it expires it finds the **top-ranked player**
|
||||||
|
(`FindPlayerByRank(0)` over the "Players" entity group) and, if the leader
|
||||||
|
changed, dispatches a `CameraShip::DirectionMessage{goalEntity,
|
||||||
|
timeOnCamera, focusOffset}` and resets the shot clock to **10 seconds**.
|
||||||
|
So the default broadcast is "follow the leader, re-cut every 10 s".
|
||||||
|
- **HUD** (`DIRECTOR.CPP:118 UpdateHUD` + `CameraShipHUDRenderable` in
|
||||||
|
`L4VIDRND.CPP:2199`): the feed overlays the followed player's identity and
|
||||||
|
a **ranking window** cycling 10 s on / 15 s off — always on during the
|
||||||
|
final 30 s of the mission, hidden once the mission stops.
|
||||||
|
- **CameraShip** (`CAMSHIP.CPP:340 FollowGoal`): aims at
|
||||||
|
`focusOffset × goal->localToWorld`, tracks the goal's linear position, and
|
||||||
|
asks the director for a new goal when `timeOnCamera` runs out. Camera
|
||||||
|
height is operator-adjustable (`ApplyControlledCameraHeight`).
|
||||||
|
|
||||||
|
### Manual camera operation
|
||||||
|
|
||||||
|
`CAMMPPR.HPP` (`CameraControlsMapper` subsystem) + `L4MPPR.HPP`: the camera
|
||||||
|
station reads **the same cockpit hardware as a pod** — there are three
|
||||||
|
concrete mappers: `CameraL4Mapper`, `CameraThrustmasterMapper`, and
|
||||||
|
`CameraRIOMapper` (a full RIO cockpit could fly the camera). Attributes:
|
||||||
|
stick / throttle / pedals / reverse-thrust / drive-camera / slide-or-clamp.
|
||||||
|
Buttons: **DirectorMode** toggle (auto-director vs manual),
|
||||||
|
**Increment/DecrementCamera** (cut between fixed cameras), and
|
||||||
|
**Create/Delete/OutputCameraInstances** — the camera-authoring workflow.
|
||||||
|
|
||||||
|
### Fixed trackside cameras — the `.CAM` files
|
||||||
|
|
||||||
|
`CAMINST.HPP/CPP` + `CAMMGR.CPP` (`CameraInstanceManager`): each map has a
|
||||||
|
notation file **`MAPS/<map>.cam`** (e.g. `sda4/BTLIVE/MAPS/ARENA1.CAM`)
|
||||||
|
holding `[cameraN]` pages:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[camera0]
|
||||||
|
cameraID=0
|
||||||
|
cameraType=DefaultCameraType ; or AlwaysSeesCameraType
|
||||||
|
tranx/y/z = position
|
||||||
|
quatx/y/z/w = orientation
|
||||||
|
minYawClamp/maxYawClamp ; pan limits (radians)
|
||||||
|
minPitchClamp/maxPitchClamp ; tilt limits
|
||||||
|
```
|
||||||
|
|
||||||
|
These are broadcast-style **fixed cameras with pan/tilt clamps**;
|
||||||
|
`CameraInstance::CalculateCameraRotation` pans them to track the goal within
|
||||||
|
the clamps. They were authored *in-game*: the operator flies to a spot,
|
||||||
|
presses CreateCameraInstance, and OutputCameraInstances writes the `.cam`
|
||||||
|
file back out (`CameraInstanceManager::WriteNotationFile`).
|
||||||
|
|
||||||
|
## 3. Mission Review = record the network, replay the network
|
||||||
|
|
||||||
|
### Recording (`SPOOLER.HPP/CPP`, `L4SPLR.HPP`)
|
||||||
|
|
||||||
|
- `SpoolFile` is a `MemoryStream` of **raw `NetworkPacket`s** (header +
|
||||||
|
payload, back to back). States: Empty → Spooling → Stored → Playing.
|
||||||
|
`SpoolPacket()` appends (hard-exits if the RAM buffer fills);
|
||||||
|
`SaveAs`/`Read` move it to/from disk. The canonical file name is
|
||||||
|
**`last.spl`** (`SPOOLER.CPP:251,274`) — same "last mission" convention as
|
||||||
|
`LAST.EGG`.
|
||||||
|
- `MissionReviewApplicationManager` owns a pool of `spool_count` RAM buffers
|
||||||
|
of `spool_size` each.
|
||||||
|
- `L4SpoolingApplication` (+ `L4SpoolingNetworkManager`,
|
||||||
|
`SpoolingInterestManager`) is the **recorder**: its
|
||||||
|
`ReceiveNetworkPacket()` override tees every packet arriving over the
|
||||||
|
mission LAN into the active spool *while also processing it normally* — so
|
||||||
|
the recording host fully participates (renders, directs cameras) as it
|
||||||
|
records. A `missionSpooled` flag tracks state; the spool is stored (→
|
||||||
|
`last.spl`) when the mission stops.
|
||||||
|
|
||||||
|
Because the recorder simply captures **received replication traffic**, the
|
||||||
|
recording is exactly what any spectator host saw: entity creations, state
|
||||||
|
updates, weapon events, kills — everything needed to re-simulate the battle,
|
||||||
|
at a tiny fraction of the size of video.
|
||||||
|
|
||||||
|
### Playback (`BTL4PB.HPP`, `L4SPLR.HPP`)
|
||||||
|
|
||||||
|
- `BTL4PlaybackApplication` (BT flavor of `RPPlaybackApplication`) is a full
|
||||||
|
game application whose network manager is `L4PlaybackNetworkManager` — a
|
||||||
|
`NetworkManager` with **no real network**: `CheckBuffers()` sources
|
||||||
|
packets from the `SpoolFile` instead of the wire.
|
||||||
|
- `SpoolerTask` (an `ApplicationTask`) walks the spool with `NextPacket()`
|
||||||
|
and `DispatchPacket()`s each one into the app, using **`timeBias`** to
|
||||||
|
shift the recorded timestamps onto the playback clock — packets are
|
||||||
|
released on the same relative schedule they were recorded, so the replayed
|
||||||
|
entities move exactly as they did live.
|
||||||
|
- The playback host's player is again a `CameraDirector` (host type switch,
|
||||||
|
§1) — so a review session *is* the Live Cam presentation (auto-cuts to the
|
||||||
|
leader, ranking overlays, fixed trackside cameras) running over recorded
|
||||||
|
traffic. This is what the debrief room / take-home tapes showed.
|
||||||
|
|
||||||
|
### What's NOT in the repo
|
||||||
|
|
||||||
|
The readable tree is partial: `L4SPLR.CPP` (SpoolerTask::Execute pacing,
|
||||||
|
exact spool start/stop triggers) and `BTL4PB.CPP` are missing — only their
|
||||||
|
headers survive. The compiled implementations are in the era binaries. The
|
||||||
|
trigger for "start spooling" (console message vs automatic at mission start)
|
||||||
|
is therefore unconfirmed; the message-handler names
|
||||||
|
(`Run/Stop/AbortMissionMessageHandler` on the spooling app) suggest it simply
|
||||||
|
records from RunMission to StopMission.
|
||||||
|
|
||||||
|
## 4. The physical setup at a center (period context, inferred)
|
||||||
|
|
||||||
|
A "camera ship" machine = one more networked PC with a Division board, its
|
||||||
|
out-the-window video feeding the spectator monitors (and the VHS deck for
|
||||||
|
take-home tapes). The mission-review station = the same machine (or another)
|
||||||
|
replaying `last.spl` into the debrief room after the mission. Both could be
|
||||||
|
driven hands-off (CameraDirector) or by an operator with a joystick/RIO.
|
||||||
|
|
||||||
|
## 5. What this means for OUR pod project
|
||||||
|
|
||||||
|
1. **No new binary needed.** BTL4OPT.EXE already contains all of it. A Live
|
||||||
|
Cam station = a second emulated machine on the pod LAN whose egg page
|
||||||
|
says `hostType=1`. Mission Review = `hostType=2` + a `last.spl`.
|
||||||
|
2. **The console app owns the roles.** When the TeslaSuite console port
|
||||||
|
authors eggs, adding a camera-host page is how you light this up — it's
|
||||||
|
an egg field, not a build variant.
|
||||||
|
3. **We can record spools ourselves.** The spool format is trivial (length-
|
||||||
|
prefixed file of raw NetworkPackets, `SPOOLER.CPP:50-95`); our emulated
|
||||||
|
NIC path (slirp/pcap) could tee mission traffic into a `last.spl`
|
||||||
|
independently of any spooling host — giving Mission Review of any pod
|
||||||
|
session after the fact.
|
||||||
|
4. **Camera authoring works from a cockpit.** `CameraRIOMapper` means the
|
||||||
|
vRIO can fly the camera ship and author `.cam` files for our arenas.
|
||||||
|
5. **Renderer note:** a camera/review host renders through the same Division
|
||||||
|
wire our bridge already decodes — the bridge should work unchanged for a
|
||||||
|
spectator host, modulo the `CameraShipHUDRenderable` overlays (2D HUD
|
||||||
|
layer, same 0x29/0x2b dpl2d path as the pod HUD).
|
||||||
|
|
||||||
|
## Quick reference — the cast
|
||||||
|
|
||||||
|
| Piece | File | Role |
|
||||||
|
|---|---|---|
|
||||||
|
| `HostType` enum | `MUNGA/HOST.HPP` | pod / camera / review / console, set per-IP in the egg (`hostType=`) |
|
||||||
|
| `Registry::MakePlayer` | `MUNGA/REGISTRY.CPP` | host type → `Player` or `CameraDirector` |
|
||||||
|
| `CameraDirector` | `MUNGA/DIRECTOR.*` | auto-director: cut to rank-0 player every 10 s; ranking-window HUD |
|
||||||
|
| `CameraShip` | `MUNGA/CAMSHIP.*` | the flying camera vehicle (a Mover entity) |
|
||||||
|
| `CameraControlsMapper` | `MUNGA/CAMMPPR.*` | stick/throttle/pedals camera flight, director toggle, camera authoring buttons |
|
||||||
|
| `CameraL4/Thrustmaster/RIOMapper` | `MUNGA_L4/L4MPPR.*` | camera station input bindings (RIO cockpit supported) |
|
||||||
|
| `CameraInstance(Manager)` | `MUNGA/CAMINST.*`, `CAMMGR.CPP` | fixed clamped cameras; reads/writes `MAPS/<map>.cam` |
|
||||||
|
| `SpoolFile` | `MUNGA/SPOOLER.*` | NetworkPacket recording; `last.spl` on disk |
|
||||||
|
| `L4SpoolingApplication` | `MUNGA_L4/L4SPLR.HPP` | records the mission LAN while participating |
|
||||||
|
| `BTL4PlaybackApplication` + `SpoolerTask` | `BT_L4/BTL4PB.HPP` | replays the spool with `timeBias` re-timing; no real network |
|
||||||
Reference in New Issue
Block a user