arcattackandClaude Opus 4.8
1cd57ade85
Adapt the spark-lesson / expert-seed.md progressive-context pattern to the bt411 port:
a thin router + context/*.md knowledge graph so the 2236-line CLAUDE.md's deep knowledge
loads on-demand instead of every session.
NON-DESTRUCTIVE foundation pass (live CLAUDE.md unchanged; proposed router is a draft):
- reference/glossary.yaml -- ~45 terms (engine/formats/scene/reconstruction)
- context/decomp-reference.md -- the quantitative hub: resource types, ClassID map,
mech offsets, damage delivery, weapon constants, env gates, tools
- context/reconstruction-gotchas.md -- the 12 systemic bug classes (conventions/DO-NOT hub)
- context/bgf-format.md -- geometry format + CONN/PCONN + LOD-sqrt3 + ramp shading
- context/gauges-hud.md -- the gauge/MFD system (the just-completed wave)
- context/open-questions.md -- deferred systems + get-from-Nick
- context/_ROUTER-DRAFT.md -- the proposed slim CLAUDE.md (identity, protocols,
quick-lookup, evidence tiers T0-T4, conventions, structure)
- phases/phase-01-context-restructure.md -- design + migration plan + status
docs/*.md ledgers stay as the DETAILED logs; context/*.md are the curated digests that
route into them. Remaining: ~10 topic files (project-overview, subsystems, combat-damage,
rendering, locomotion, wintesla-port, build-and-run, ...) then the CLAUDE.md swap.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
154 lines
9.1 KiB
Markdown
154 lines
9.1 KiB
Markdown
# 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
|
|
```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]]
|
|
```
|