BT411/context/_ROUTER-DRAFT.md

BattleTech Pod-Port — Reverse-Engineering Expert Knowledge Base

⚠️ DRAFT of the proposed slim CLAUDE.md. This is the router that would REPLACE the 2236-line CLAUDE.md, moving its deep knowledge into context/*.md. It is a draft for review — the live CLAUDE.md is unchanged until this is approved + the remaining topic files are migrated. See phases/phase-01-context-restructure.md for the migration plan + status.

Project: Port VWE's 1995 arcade BattleTech (BT) pod game (MUNGA engine, Tesla platform 4.10) to modern Windows + the pod hardware, by reconstructing the missing BT game logic from the BTL4OPT.EXE binary on top of the working WinTesla engine. Repo of record: the top-level CMakeLists.txt + README.md build btl4.exe. Layout: engine/ game/ content/ docs/ reference/ tools/ context/.

---

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 [[wiki-links]] and related_topics frontmatter to adjacent topics.
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
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
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
Detailed running ledgers	docs/RECONCILE.md, docs/GAUGE_COMPOSITE.md, docs/HARD_PROBLEMS.md, docs/SUBSYS_PLAN.md, docs/P3_LOCOMOTION.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).

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/                     # detailed running ledgers (RECONCILE, GAUGE_COMPOSITE, HARD_PROBLEMS, …)
├── 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

---
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]]