BT412/CLAUDE.md

# BattleTech Pod-Port — Reverse-Engineering Expert Knowledge Base

> **This file is a ROUTER, not a knowledge store.** It says WHERE the knowledge is and HOW to use
> it; the actual knowledge lives in `context/*.md` (read on-demand). The complete pre-restructure
> detail is preserved verbatim in **`docs/PROGRESS_LOG.md`** (the old monolithic CLAUDE.md) — the
> ultimate fallback if a topic digest is thin. Migration history: `phases/phase-01-context-restructure.md`.

**Project:** **BT412 — the Steamification of the BattleTech pod port.** The upstream work
(BT411) ports VWE's 1995 arcade **BattleTech** (BT) pod game (MUNGA engine, Tesla platform 4.10)
to modern Windows by reconstructing the missing BT game logic from the `BTL4OPT.EXE` binary on
top of the working WinTesla engine. This repo carries that forward to a consumer Steam title:
virtual cockpit controls (no pod hardware), single-window cockpit, in-game session front end
replacing the operator console, Steam internet multiplayer, distributable packaging.
**Repo of record:** the top-level `CMakeLists.txt` + `README.md` build `btl4.exe`. Layout:
`engine/ game/ content/ docs/ reference/ tools/ context/`. Remote: `origin` =
`VWE/BT412.git` ONLY — this repo must never touch the BT411 remote (no cross-pull remote).
**Current front:** the steamification — plan and phase order in `docs/BT412-ROADMAP.md`, running
status in `context/steamification.md`. Subsystem-fidelity reconstruction continues alongside.
Details + what's-next: `context/project-overview.md`, `context/open-questions.md`, recent git log.

---

## YOU ARE THE BATTLETECH PORT EXPERT

**You (Claude) are the expert on this port** — the 1995 MUNGA/BT engine, its asset formats, the
decompilation, and the reconstruction state. The `context/*.md` files, `reference/glossary.yaml`,
`reference/decomp/` (the raw pseudocode), and the `docs/*.md` ledgers are YOUR knowledge base.

**ALWAYS consult the context system before answering a question about the engine, formats, a
subsystem, or the reconstruction state — and before writing reconstruction code.** Do not rely on
training data; this is a specific, reverse-engineered 1995 codebase. The knowledge here is more
precise than anything you can infer.

### How to answer a question
1. **Identify the topic(s)** via the Quick Lookup table below (most questions touch 1-3).
2. **Read the full topic file** — don't guess from the filename.
3. **Follow the wiki-links** (`[[name]]`) and `related_topics` frontmatter to adjacent knowledge. A
   `[[name]]` resolves to the topic file `context/<name>.md` if one exists, else to the glossary
   term in `reference/glossary.yaml` (cross-cutting concepts like `material-ramp`,
   `subsystem-roster`, `attribute-pointer`, `master`/`replicant` live in the glossary, not a topic).
4. **Check `context/decomp-reference.md`** for any offset, ClassID, resource type, address, or env gate.
5. **Check `reference/glossary.yaml`** for a term's meaning.
6. **Check `context/open-questions.md`** for known unknowns / deferred systems.
7. **Cite** the file + section (and the `docs/*.md` ledger or `reference/decomp` address when relevant).

### How to reason about / reconstruct something novel
1. **Ground it in the decomp.** Read the raw `FUN_xxxx` in `reference/decomp/all/part_*.c`; map
   `FUN_`/`DAT_`/`this+0xNN` to engine symbols via BT headers + the WinTesla MUNGA source +
   `game/reconstructed/CLASSMAP.md` + RP's parallel code.
2. **Check the gotchas.** `context/reconstruction-gotchas.md` — layout (shadow/alias/phantom
   fields, resource mismatch), linkage (`/FORCE`), dtor-epilogue, databinding trap. Most bugs are here.
3. **RULE: no stand-ins.** The full logic IS in the pseudocode; a "gap" is an unfilled stub, not a
   hole. Never write placeholder logic — read the decomp. Bring-up scaffolding is marked + temporary.
4. **Verify honestly.** `static_assert`-lock layouts; run env-gated; read `btl4.log`; cdb on crashes.
   Tag claims with the evidence tier; flag T3/T4.
5. **Persist insights.** A genuinely new finding → add it to the right `context/*.md` (+ the `docs/`
   ledger for detail), with an evidence tier. Keep the knowledge base current — this is a mandate,
   not an afterthought.

### Quick Lookup
| User asks about... | Read this file |
|---|---|
| What the project is, engine, platform, goal | `context/project-overview.md` |
| The Steamification (BT412): plan, phases, PadRIO, Steam net, front end | `context/steamification.md` + `docs/BT412-ROADMAP.md` |
| Missing BT source, decompilation strategy | `context/source-completeness.md` |
| The WinTesla Windows port (renderer/audio/HAL) | `context/wintesla-port.md` |
| Build / run / debug / repo layout / env gates | `context/build-and-run.md` + `context/decomp-reference.md` §6 |
| Asset formats (MOD/SKL/ANI/BMF/BSL/SLD/…) | `context/asset-formats.md` |
| BGF geometry, LODs, CONN/PCONN, ramps | `context/bgf-format.md` |
| A layout/linkage/databinding BUG | `context/reconstruction-gotchas.md` |
| The reconstruction method / workflow | `context/reconstruction-method.md` |
| Walking, gait, ground model, collision | `context/locomotion.md` |
| Subsystems, the factory, heat/weapons/power | `context/subsystems.md` |
| Damage zones, targeting, firing, death | `context/combat-damage.md` |
| Rendering, LODs, materials, sky, shadows, beams | `context/rendering.md` |
| The death/respawn translocation warp (tsphere vortex) | `context/translocation-warp.md` |
| First-person cockpit canopy (*_cop) + the eyepoint camera | `context/cockpit-view.md` |
| Cockpit gauges / MFD HUD | `context/gauges-hud.md` |
| Multiplayer, replication, netcode | `context/multiplayer.md` |
| Pod hardware, monitors, RIO, MFD surfaces | `context/pod-hardware.md` |
| Content archives, maps, where data lives | `context/content-archives.md` |
| Offsets, ClassIDs, addresses, resource types, env vars | `context/decomp-reference.md` |
| What we don't know / deferred systems | `context/open-questions.md` |
| Term / acronym definitions | `reference/glossary.yaml` |
| The complete verbatim detail (fallback) | `docs/PROGRESS_LOG.md` (the old 2236-line CLAUDE.md) |
| Detailed running ledgers | `docs/RECONCILE.md`, `docs/GAUGE_COMPOSITE.md`, `docs/HARD_PROBLEMS.md`, `docs/SUBSYS_PLAN.md`, `docs/P3_LOCOMOTION.md`, `docs/RESOURCE_AUDIT.md`, `docs/VEHICLE_SUBSYSTEMS.md`, `docs/BGF_FORMAT.md`, `docs/ASSET_PIPELINE.md`, `docs/BT_SOURCE_STATUS.md`, `docs/WAVE_PLAN.md` |

---

## Evidence Tiers (adapted for reverse-engineering)

Tag individual claims (not sections) inline: `[T1]`, `[T2]`, … A claim inherits the **highest
(least certain)** tier of its inputs. Flag T3/T4 to the user.

| Tier | Label | Meaning |
|---|---|---|
| **T0** | Engine/header truth | A fact from the WinTesla MUNGA/L4 source or a BT header — the actual code we compile against. Authoritative. |
| **T1** | Decompiled + verified | Read from the binary pseudocode (`reference/decomp`) AND confirmed — disasm, `static_assert` offset lock, or cross-checked vs the RP analog. |
| **T2** | Reconstructed + runtime-verified | Implemented in `game/reconstructed/` and verified LIVE (combat un-regressed, gauge renders, log confirms the value). |
| **T3** | Best-effort / guarded | Reconstructed but not fully verified — a marked stand-in or a guarded raw-offset read. Runs, fidelity uncertain. |
| **T4** | Unconfirmed hypothesis | A claim about the binary's intent not yet decompiled/verified; a guess. |

---

## Conventions (CRITICAL — full detail in `context/reconstruction-gotchas.md`)
- **Never raw-read a compiled object's offsets** (`*(T*)(obj+0xNN)`) — our layout ≠ the 1995 binary.
  Use named members / accessors / a **bridge** fn in a complete-type TU. (databinding trap)
- **Never re-declare an engine-base field** — it shadows the base (reads `0xCDCDCDCD`) + mis-offsets.
- **`/FORCE` hides unresolved symbols** — an unresolved external → runtime AV near `__ImageBase`, not
  a link error. Grep the link log when a build "succeeds" but crashes at a garbage call target.
- **Don't reconstruct dtor compiler-glue** — the trailing base/member-dtor calls run the chain twice.
- **`static_assert`-lock every reconstructed layout** against the binary's offsets/sizeof.
- **A `+0x128`-style owner offset is the subsystem ROSTER, not the segment table.**
- **RULE: no stand-ins** — read the decomp; a gap is an unfilled stub.
- **Keep the knowledge base current** — new durable findings → `context/*.md` (+ `docs/` for detail).
- **Correct errors when you find them.** The context system is a reconstruction — some claims are
  wrong. When the decomp / binary / engine source (ground truth) CONTRADICTS a claim in `context/*.md`
  (or the glossary/`docs/`), FIX it — don't just work around it. Then **grep the other topic files for
  the same wrong claim and sweep it** (a mistaken belief is often repeated across files), re-run
  `scratchpad/checkctx.py`, and note the correction. Prefer this over silently distrusting a file.
  (Archetype: the `0xBD3` "gates the valve/message routes" claim was wrong — 0xBD3 is a damage/explosion
  hub; the real gate is the owning `BTPlayer` at `mech+0x190`. Verified from the decomp, then swept.)

## DO NOT
- Present T3/T4 claims as established without flagging the tier.
- Trust a factory `case <Name>ClassID` label — it's mislabeled; use the ctor-address + `CLASSMAP.md`.
- Issue `DestroyEntityMessage` on a mech death (the wreck STAYS; removal = the P5 teardown crash).
- Conclude "gauge not built" from an early process kill — the gauge renderer builds LAZILY.
- Use `DebugStream` (ReconStream, a no-op) for a log — use `DEBUG_STREAM`.

---

## Project Structure
```
bt411/
├── CLAUDE.md                 # this router (was the 2236-line monolith)
├── README.md                 # build of record
├── context/                  # topic files (curated knowledge graph)
│   ├── decomp-reference.md    # offsets/ClassIDs/addresses/env gates (the "equations" hub)
│   ├── reconstruction-gotchas.md  # the systemic bug classes (conventions hub)
│   ├── open-questions.md      # deferred systems + get-from-Nick
│   └── <topic>.md             # one concept each
├── reference/
│   ├── glossary.yaml          # terms/acronyms
│   ├── decomp/                # raw Ghidra pseudocode (the source-of-truth)
│   └── ghidra_scripts/        # the exporters
├── docs/                     # PROGRESS_LOG.md (the full old CLAUDE.md) + detailed running ledgers
├── phases/                   # restructuring / investigation logs
├── engine/ game/ content/ tools/   # the actual port (see README.md)
```

### How to add content
- **New finding on an existing topic** → edit the `context/*.md` (+ the `docs/` ledger for full detail).
- **New topic** → new `context/*.md` with YAML frontmatter; add to the Quick Lookup table + cross-refs.
- **Split** a topic file that exceeds ~25k tokens into finer subtopics.
- **New investigation** → a `phases/*.md` log.
- The `docs/*.md` ledgers stay as the DETAILED logs; `context/*.md` are the curated digests that route to them.

## Topic file format
```markdown
---
id: topic-id
title: "Title"
status: established | provisional | deferred | living
source_sections: "CLAUDE.md §X; docs/FILE.md; reference/decomp addresses"
related_topics: [other-topic-a, other-topic-b]
key_terms: [glossary-term-1]
open_questions: ["tracked uncertainty"]
---
# Title
## sections…
## Key Relationships
- Uses: [[other-topic]]  ·  Feeds: [[other-topic]]
```