BT411/README.md

# BattleTech 4.11 (bt411)

A standalone Windows port of **Virtual World Entertainment's arcade *BattleTech*** (Tesla
platform, release 4.10, ~1995–96), reconstructed on the shared **RP411 Windows engine**. The
game boots, renders, and runs a single-player **drive → animate → target → fire → damage →
destroy** loop across all 8 maps, with two-instance multiplayer entity replication working.

This repo is a clean, self-contained extraction of the BattleTech-specific work from the larger
reverse-engineering workspace — engine + game + content + build, with nothing from Red Planet or
the raw archive dumps. It builds and runs out of the box.

> **License:** the game content (`content/`) and the original binary are proprietary to Virtual
> World / the pod owner. This repository is **private**; do not redistribute.

---

## Layout

```
CMakeLists.txt      one build: munga_engine lib + bt410_l4 game lib + btl4.exe
engine/
  MUNGA/            shared 2007 sim/render engine (149 .cpp + headers)
  MUNGA_L4/         Win32/D3D9 HAL + renderer + asset loaders (44 .cpp), incl.
                    our BT work: bgfload / L4D3D / L4VIDEO + the image codec
  shim/             minimal ATL shim (USES_CONVERSION/W2A)
  lib/              OpenAL32 / libsndfile import libs + runtime DLLs
game/
  reconstructed/    the reconstructed BT game logic (mech, subsystems, HUD, app; ~47 .cpp)
  original/BT,BT_L4 surviving original BT source + all BT headers
  fwd/              header shims forwarding <NAME.hpp> -> the engine's NAME.h
  btl4main.cpp      WinMain launcher / entry point
content/            runtime data: BTL4.RES, VIDEO/, GAUGE/, AUDIO/, *.EGG, BTDPL.INI
context/            progressive knowledge graph — 18 on-demand topic files (routed by CLAUDE.md)
docs/               format specs + reconstruction ledgers + PROGRESS_LOG.md (full history)
reference/
  decomp/           raw Ghidra pseudocode — source-of-truth for ongoing recon
  ghidra_scripts/   the headless decomp exporter
  glossary.yaml     term / acronym definitions
phases/             restructuring / investigation logs
tools/              btconsole.py (MP console emulator), map/resource scanners
run/                run.cmd helper
CLAUDE.md           knowledge-base ROUTER — identity, protocols, quick-lookup, conventions
```

## Prerequisites

- **Visual Studio 2019 BuildTools** (MSVC v142, x86). The Community install on the original dev
  box was broken, hence the explicit BuildTools instance in the configure line below; adjust to
  your install.
- **CMake ≥ 3.20**.
- **Legacy DirectX SDK (June 2010)** — the engine uses `d3dx9`/`dinput`/`dxerr`, removed from the
  modern Windows SDK. Default path `C:/Program Files (x86)/Microsoft DirectX SDK (June 2010)`;
  override with `-DDXSDK=<path>`. (The installer may throw a harmless **S1023** error — dismiss it;
  the SDK headers/libs install before the failing redist step.)

OpenAL/libsndfile import libs + DLLs are vendored under `engine/lib/`; the DLLs are copied next to
the exe automatically at build time.

## Build (32-bit / Win32)

```
cmake -S . -B build -G "Visual Studio 16 2019" -A Win32 ^
      -DCMAKE_GENERATOR_INSTANCE="C:/Program Files (x86)/Microsoft Visual Studio/2019/BuildTools"
cmake --build build --config Debug
```

Must be **Win32** — the DirectX SDK link libs are `Lib/x86`. The link uses `/FORCE`: the 1995
headers define free functions/globals without `inline`/`extern`, so identical symbols appear in
many translation units (~124 `LNK2005`); `/FORCE:MULTIPLE` keeps the first. `UNRESOLVED` tolerates
a dead offline-tool factory in `mech3.cpp` that is never called at runtime. (Cleanup task: move
those definitions to single TUs + neutralize the dead factory, then drop `/FORCE`.)

## Run

```
run\run.cmd            REM boots DEV.EGG (grass / day)
run\run.cmd DBASE.EGG  REM any egg in content/
```

The working directory **must** be `content/` (the engine resolves `BTL4.RES`, `VIDEO\`,
`BTDPL.INI`, and eggs relative to cwd); `run.cmd` handles that. Maps available in `BTL4.RES`:
`cavern grass rav polar3 polar4 arena1 arena2 dbase` — switch via a copied egg's `map=` field.

### Useful env-var flags (default OFF unless noted)

The authentic stack (gait, collision, real controls) is **default-on**; set `=0` to fall back.
Debug/harness flags: `BT_FORCE_THROTTLE=1` (auto-walk), `BT_SPAWN_ENEMY=1` (spawn a target dummy),
`BT_FORCE_FIRE=1` (auto-fire), `BT_HEAPCHECK=1` (whole-heap validation — slow), `BT_BSL=0` (legacy
texture decode), `BT_DEV_GAUGES=1` (render the cockpit MFDs in a dev window), `BT_LOG=<file>`.
Interactive: **WASD** drive, **Space/Ctrl** fire, **X** all-stop. The complete env-gate table is in
`context/decomp-reference.md` §6 (routed from `CLAUDE.md`).

## Multiplayer (two instances, one box)

```
instance A:  btl4.exe -egg MP.EGG -net 1501   (BT_LOG=mp_a.log)
instance B:  btl4.exe -net 1601               (BT_LOG=mp_b.log)
console:     python tools/btconsole.py MP.EGG 127.0.0.1:1501 127.0.0.1:1601
```

`-net <port>` enables networked mode; the console emulator delivers the mission egg and the launch
command. Entity + movement replication works; cross-pod combat is in progress.

## Status & continuing the work

The engine, renderer, audio, HAL, build, locomotion, collision, damage, render fidelity, the full
cockpit **gauge / MFD system** (every config binding resolves + every widget builds), and the
projectile / missile weapon families are done. Active fronts: per-subsystem polish (the gyroscope
integrator; the `0xBD3` message manager that gates the valve / status-message control routes) and
cross-pod MP combat. `reference/decomp/` holds the raw pseudocode every reconstruction is verified
against.

**Start with `CLAUDE.md`** — it is the router into the progressive knowledge base: a quick-lookup
table pointing to the `context/*.md` topic files (loaded on demand), the evidence-tier and
convention rules, and `context/open-questions.md` for what's deferred / next. The complete
pre-restructure history is preserved verbatim in `docs/PROGRESS_LOG.md`; `docs/*.md` holds the
detailed running ledgers.