BT412/docs/BT_SOURCE_STATUS.md

# BattleTech (Tesla 4 / rel 4.10) — Source Status & Reconstruction

**Purpose:** brief for a meeting with an original BT programmer. What source we have, what was
missing, where each piece came from, and how we're patching the gaps to get BT running on modern
Windows. **The most useful thing you can tell us is at the bottom (§7).**

**One-line status:** the port now **compiles, links, and boots to a window**, and is running into the
mission/spawn simulation. The engine/renderer/audio came from an existing Windows port (Red Planet);
the BT *game logic* was lost and is being **reconstructed from the shipped binary** + the surviving
headers + Red Planet's parallel code.

---

## 1. The situation in one picture

| Layer | Have it? | Source |
|---|---|---|
| **MUNGA engine + L4 HAL** (renderer, mover, math, scene, net, audio) | ✅ complete | The **Windows port** ("WinTesla", Red Planet 4.11 source) — already bypasses the Division IG board with Direct3D 9 (`L4D3D`) and replaces HMI SOS audio with OpenAL. |
| **BT headers** (`.hpp`: class layouts, vtables, signatures) | ⚠️ **partial** | ~14 survived in the BT source archive (`410srczipped`); the **core ~28 (`mech`, `heat`, `powersub`, weapons, `btplayer`, `hud`, gauges…) were lost** — see §3. |
| **BT game logic** (`mech`, subsystems, weapons, HUD, app…) `.cpp` | ❌ **LOST** | Reconstructed from the shipped binary `BTL4OPT.EXE` (decompiled). |
| **Deployed content** (models, skeletons, skins, animations, missions/eggs) | ✅ present | The pod machine disk image. |

Where a header survived it's an *answer key* for class layout/vtable order (then the binary just
supplies the bodies). Where it didn't (the core mech/weapon/player classes), the layout itself is
inferred from the binary's vtables + `this+offset` usage, cross-checked against the Red Planet analog —
a harder reconstruction, and the part most worth validating against original source if any exists.

---

## 2. Where everything lives (the four archives, in the repo root)

| Archive | What it is | Key contents |
|---|---|---|
| `410srczipped.zip` | **BT source tree** | All `.hpp` headers, geometry/material defs, **428 animations**, and a *partial* set of `.cpp`. Build manifests `CODE/BT/BT/BT.MAK` + `CODE/BT/BT_L4/BTL4.MAK` (the authoritative file lists). |
| `Tesla4NovellTechPC-*.zip` | Pod **technician/test PC** image | The compiled game `btrel410.exe`, Division VPX board diagnostics, shared textures. |
| `Tesla4PodPCNovell-*.zip` | The pod **game machine** image | The full **deployed content tree** at `…/CopyofNovellDisk/REL410/BT/` — per-mech skeletons/skins, models, textures, gauges, **and the mission eggs** (`TEST.EGG`, `LAST.EGG`). Also a copy of the game binary. |
| `Elsewhen RP411 Source-*.zip` | **The Windows port** ("WinTesla", VS2008) | Modernized engine: `WinTesla.sln`, MUNGA + MUNGA_L4 (incl. `L4D3D.cpp` = IG→Direct3D), OpenAL/libsndfile audio, and the **complete Red Planet game logic**. The solution references a `BT410_L4` target **but the BT game source folder is absent** — confirming BT was mid-port and its code isn't here. |

The shipped binary `btrel410.exe` is a PKZIP self-extractor; unwrapped it yields **`BTL4OPT.EXE`**
(1.24 MB, clean PE32) — that's our decompilation + behavioral oracle.

---

## 3. What was missing, precisely (from `BT.MAK` + `BTL4.MAK` = 53 modules)

Every module in the original build manifests is accounted for as follows:

### 3a. Survived as real source (~10) — used as-is
From `CODE/BT/BT/` and `CODE/BT/BT_L4/`:
`BTMSSN` (mission), `BTREG` (registry), `BTTEAM`, `BTSCNRL` (scenario role), `BTCNSL` (console),
`BTTOOL`, `GAUSS` (Gauss rifle), `PPC`, `BTL4ARND` (arena), `BTL4MODE` (mode manager).

### 3b. Lost → reconstructed from the binary (~43 modules)
The heart of the game. **Two cases, depending on whether the header also survived:**

**(i) Header AND `.cpp` lost → both reconstructed** (class layout/vtable inferred from the binary +
RP analog — these are the ones whose layout is *our inference*, not ground truth):
`mech`, `mech2`, `mech3`, `mech4`, `mechsub`, `dmgtable`, `heat`, `heatfamily_reslice`, `powersub`,
`gnrator`, `gyro`, `torso`, `myomers`, `searchlight`, `thermalsight`, `mechweap`, `emitter`,
`projweap`, `missile`, `projtile`, `ammobin`, `btplayer`, `mechmppr`, `btl4vid`, `btl4mppr`, `hud`,
`btl4gaug`, `btl4gau2`, `btl4gau3`.

**(ii) `.hpp` survived, only `.cpp` lost → implementation reconstructed against the real header**
(lower risk — layout is ground truth):
`mechdmg`, `mechtech`, `sensor`, `messmgr`, `mislanch`, `misthrst`, `seeker`, `btl4app`, `btl4mssn`,
`btl4rdr`, `btl4grnd`, `btl4pb`, `btl4galm`, `btdirect`.

(Surviving headers with no reconstruction needed — interface-only or their `.cpp` also survived:
`bt`, `btl4`, `btl4ver`, `btmssn`, `btreg`, `btteam`, `bttool`, `gauss`, `ppc`, `btl4arnd`,
`btl4mode`, `testbt`, `turret`.)

### 3c. Genuinely unaccounted-for (4) — **please confirm with us (§7)**
| Module | Our handling | Question for you |
|---|---|---|
| `btl4` (the `WinMain`/main app) | **Recreated** as `btl4main.cpp`, cloned from RP's launcher `RPL4.CPP`. | Is the real BT main app meaningfully different from RP's? |
| `path` | **Not reconstructed.** Not referenced on the current code path. | What is `path.cpp` — AI pathfinding? Is it needed for single-player bots? |
| `mechbld` | Assumed **offline tool** (mech/model builder), not runtime. | Correct? |
| `btl4tool` | Assumed **offline tool**, not runtime. | Correct? |

### 3d. Missing files, organized by the directory you'd look in

This is the concrete "check your backup drive" list. `BOTH` = `.cpp` and `.hpp` both gone;
`.cpp only` = header survived; `.hpp only` = implementation survived.

**`CODE/BT/BT/`  (game logic)**

| File (module) | What's missing |
|---|---|
| `mech`, `mech2`, `mech3`, `mech4`, `mechsub` | **BOTH** |
| `heat`, `powersub`, `gnrator` | **BOTH** |
| `mechweap`, `emitter`, `projweap`, `missile`, `projtile`, `ammobin` | **BOTH** |
| `gyro`, `torso`, `myomers`, `hud`, `dmgtable` | **BOTH** |
| `btplayer`, `mechmppr` | **BOTH** |
| `path` | **BOTH** (AI pathfinding — see §3c) |
| `mechdmg`, `mechtech`, `sensor`, `messmgr`, `mislanch`, `misthrst`, `seeker`, `btdirect` | `.cpp only` |
| `btcnsl` | `.hpp only` |

**`CODE/BT/BT_L4/`  (app / cockpit / L4 integration)**

| File (module) | What's missing |
|---|---|
| `btl4vid`, `btl4gaug`, `btl4gau2`, `btl4gau3`, `btl4mppr` | **BOTH** |
| `mechbld`, `btl4tool` | **BOTH** (assumed offline tools — see §3c) |
| `btl4` (main app), `btl4app`, `btl4mssn`, `btl4rdr`, `btl4grnd`, `btl4pb`, `btl4galm` | `.cpp only` |

**Present and intact (no help needed):** `CODE/BT/BT/`: `btmssn`, `btreg`, `btteam`, `bttool`,
`gauss`, `ppc`, `turret.hpp`, `bt.hpp` · `CODE/BT/BT_L4/`: `btl4arnd`, `btl4mode`, `btl4.hpp`,
`btl4ver.hpp`, `testbt.hpp`.

---

## 4. How the BT game logic is being reconstructed

`BTL4OPT.EXE` is a near-ideal target: class names, `Class::Method` strings, and **original source
paths in asserts** (`d:\tesla_bt\bt\mech.cpp`) are left in the binary. Per module:

1. Locate the module's function cluster in the decompiled output (asserts + address contiguity).
2. Map vtable slots → methods (vtable order = declaration order, from the surviving header).
3. Map `this+0xNN` offsets → named members (from the header layout).
4. Rewrite the Ghidra pseudo-C into compilable C++, **cross-checking the Red Planet analog** for
   idioms — `VTV`≈`Mech`, `VTVMPPR`≈`mechmppr`, `RPPLAYER`/`BLOCKER`≈`btplayer`, `WEAPSYS`≈weapons,
   `RPL4*`≈the `BT_L4` app layer.
5. Verify behavior against the binary as an oracle.

Result is a **behavior-equivalent reconstruction**, not the original text. Reconstructed files carry a
header banner citing the originating `@ADDR` and the cross-references used.

---

## 5. How it's assembled & patched into a running build

- **Engine:** the WinTesla MUNGA + MUNGA_L4 (193 files) compiles green to `munga_engine.lib`
  (modern MSVC, Win32, targeting the legacy DirectX SDK June 2010 for `d3dx9`/`dinput`).
- **BT game lib (`bt410_l4`):** the 43 reconstructed `.cpp` + the ~10 surviving BT `.cpp` + a small
  `btstubs.cpp` (see below) + a header-forwarding shim (the DOS-era code uses `.hpp` include names;
  WinTesla renamed engine headers to `.h`).
- **Launcher:** `btl4main.cpp` (`WinMain`, cloned from `RPL4.CPP`), drives `BTL4Application`.
- **Link:** `bt410_l4` + `munga_engine.lib` + OpenAL/libsndfile + D3D9/d3dx9/dinput8 → **`btl4.exe`**.

### The patch points we know about (the bring-up worklist)
These are deliberately isolated and flagged `// TODO(bring-up)`:
- **`btstubs.cpp`** — first-link placeholders for: a handful of engine data globals not pulled from the
  static lib (`allPresets`, `FrameTimeScale`); the BT renderable pipeline (`BT*Renderable`); the 2D HUD
  layer (`dpl2d_*`, which libDPL provided and `L4D3D` hasn't yet re-implemented); a few `Mech`/subsystem
  accessors. Each is inert until given a real body.
- **Two stubbed video data files** — `VIDEO\REPLACEMATS.tbl` / `MATREPLACETABLE.tbl` (WinTesla-era
  material-substitution tables, absent from the 1995 content) created empty so video init proceeds.
- **A few reconstructed `BTPlayer`/`Mech` methods** still missing real bodies (currently being
  recovered, in dependency order driven by what the running game asks for next).

---

## 6. Current runtime state (live)

`btl4.exe` boots cleanly: opens `BTL4.RES`, parses the `-egg TEST.EGG` mission (BattleTech / cavern /
freeforall / night), creates the application, initializes the D3D video renderer, **opens its window**,
and enters the mission simulation. The **player-spawn pipeline now executes end-to-end** —
`HuntForDropZone → DropZone reply → BTPlayer::CreatePlayerVehicle → MakeAndLinkViewpointEntity →
Mech::Make → Mech::Mech` (all reconstructed from the binary + RP analog this session).

**Current frontier = the `Mech` object-layout + resource-streaming reconstruction.** The Mech
constructor runs but doesn't yet *stream* its model/subsystems/skeleton: in the reconstruction the
resource layer (`ResourceFind`/`ResourceStream`) is still a no-op placeholder, and ~145 raw
`this[0xNN]` field accesses in `mech.cpp` are backed by a shared scratch bank instead of named members.
This is the single biggest remaining reconstruction task — and, notably, it's **exactly the module
whose original `.hpp` *and* `.cpp` were both lost** (`mech`, see §3d). Recovering the real `mech.*`
would short-circuit this entire pass.

---

## 7. What would help most from you

1. **The real BT game source** — if a backup/dev drive has `CODE/BT/BT/*.cpp` (the lost `mech`,
   subsystems, weapons, HUD, app), it would replace the entire reconstruction. Even a partial set
   shrinks the work dramatically.
2. **`path.cpp`** — what is it (AI pathfinding?), and is it needed for single-player bot missions?
3. **`mechbld` / `btl4tool`** — confirm these are offline tools, not runtime modules.
4. The **mission/egg flow** for standalone (non-networked) play — anything special about how a pod
   launched a single mission vs. the multiplayer console handshake.
5. The **2D HUD / `dpl2d_*` layer** — how the cockpit gauges/radar were drawn, since that's the part of
   libDPL the Direct3D port hasn't reproduced yet.
6. Confirmation that the pod disk image is the **complete content master**, and whether the full
   walk/run **animation set** exists beyond what shipped in the source archive.

---
*Reference docs in this repo: `CLAUDE.md` (overall project), `btbuild/RECONCILE.md` (the detailed
reconstruction + bring-up ledger), `decomp/README.md` (decompilation method).*