context-system: bootstrap the progressive-context expert knowledge base (foundation)
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>
This commit is contained in:
arcattack
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
401b290949
commit
1cd57ade85
@@ -0,0 +1,153 @@
|
||||
# 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]]
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: bgf-format
|
||||
title: "BGF Model Format (DIV-BIZ2 geometry) + the render gotchas"
|
||||
status: established
|
||||
source_sections: "docs/BGF_FORMAT.md (full spec); CLAUDE.md §5, §10 render-fidelity notes"
|
||||
related_topics: [asset-formats, rendering, decomp-reference]
|
||||
key_terms: [BGF, DIV-BIZ2, PMESH, CONN, PCONN, LOD, material-ramp, SV_SPECIAL]
|
||||
open_questions:
|
||||
- "Replacement-LOD selection for NON-additive multi-LOD models (hot-spot/reference semantics)"
|
||||
---
|
||||
|
||||
# BGF Model Format
|
||||
|
||||
`.BGF` = **`DIV-BIZ2`** little-endian nested Tag-Length-Value geometry. Full byte-level parsing
|
||||
spec (verified against all 1275 content `.BGF` files) lives in **`docs/BGF_FORMAT.md`** — this
|
||||
topic captures the structure + the hard-won gotchas that cost real debugging. Loader of record:
|
||||
`engine/MUNGA_L4/bgfload.cpp` (game-callable via `LoadBgfFile`); standalone reference reader
|
||||
`DivLoader/VGCDivLoader.cpp`. Tag names: `dsys/PFBIZTAG.H`.
|
||||
|
||||
## Structure
|
||||
`OBJECT → LOD → PATCH (geogroup) → PMESH`. Interleaved float32 verts; **QUAD faces (must
|
||||
triangulate `[a b c][a c d]`)**; materials referenced by `library:material` name (resolved
|
||||
against the map's `.BMF` libs). Damage/articulation are **name-driven via `SV_SPECIAL` (0x2037)
|
||||
`dz_*` tokens**, not stored geometry. [T1]
|
||||
|
||||
## Indices — the CONN/PCONN story (two corrections)
|
||||
A PMESH carries faces in `CONNECTION_LIST` (0x0047) and/or `PCONN_LIST`:
|
||||
- `CONNECTION_LIST` is a **FLAT TRIANGLE LIST** (3 indices/face) — NOT "one polygon, fan-triangulate"
|
||||
(the original doc was wrong; fan-triangulating turned buttec's 115 tris into 341 fan-garbage).
|
||||
Corpus-verified: ALL 3488 CONN chunks have n%3==0. [T2]
|
||||
- **CONN and PCONN COEXIST** — a pmesh can carry quads/hexes in PCONN PLUS loose triangles in
|
||||
CONN. **370 of 841 GEO models** had mixed pmeshes silently dropping their CONN triangles until
|
||||
both were processed always (the "turret base missing panels" bug). `ppf=6` hexagons exist. [T2]
|
||||
|
||||
## LODs — the √3 decode
|
||||
Each LOD chunk carries a `0x2046` header = **[near..far) viewing band**. The board selected the
|
||||
LOD whose band contains the camera distance.
|
||||
- **√3 range decode:** every stored band value is the authored euclidean distance ÷ √3 (92% of
|
||||
the corpus is exactly nice-number/√3; hand-conversion typos prove it). Multiply parsed bands by
|
||||
`√3` (`kLodRangeScale=1.7320508`). [T2]
|
||||
- **Metric = the instance-transformed OBJECT ORIGIN distance**, ONE shared `d` for all LODs of an
|
||||
object (a bounding-sphere-SURFACE metric desyncs sibling bands — wrong). [T2]
|
||||
- **ADDITIVE_LODS** (object-level `SV_SPECIAL` token, 135 pod BGFs — all arena structures): at eye
|
||||
distance d, EVERY LOD with `d < OutDist` draws (near detail ADDS onto coarser massing). Non-additive
|
||||
keep first-LOD-only (the 2007 engine's own behavior). [T2]
|
||||
- **PUNCH** (patch-level `SV_SPECIAL`): cutout geogroups — black texels = HOLES (alpha-test in the
|
||||
opaque pass). Coplanar shells inside one LOD z-fight → depth-bias by submission ordinal. [T2]
|
||||
|
||||
## Shading model (from libDPL DPLTYPES.H)
|
||||
Shading is selected PER-GEOMETRY by vertex type:
|
||||
- **No-normal geometry** (XYZ_UV / XYZ_RGBA_UV: mesas/ground/sky/buildings/mech, WHITE baked
|
||||
verts) is UNLIT, colorized by the material's 2-endpoint **RAMP** (see [[material-ramp]]).
|
||||
- **Normal-bearing geometry** (XYZ_N_UV: ~150 vehicle/missile files) is LIT by the map light.
|
||||
- **Applying the ramp to lit geometry = the "dusty white blobs" bug** — gate on `hasNormals`. [T2]
|
||||
|
||||
## Skeleton assembly
|
||||
A mech is not one BGF — it's a `.SKL` skeleton (a DCS tree of joints) whose each joint's
|
||||
`Object=part.bgf` is loaded + posed, then animated by `.ANI` clips. See [[asset-formats]] /
|
||||
[[locomotion]] for skeleton + animation. [T1]
|
||||
|
||||
## Key Relationships
|
||||
- Detailed spec: `docs/BGF_FORMAT.md`.
|
||||
- Consumed by: [[rendering]] (the D3D9 draw path), [[locomotion]] (skeleton parts).
|
||||
- Related: [[asset-formats]] (BMF/BSL/SKL/ANI), [[decomp-reference]].
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
id: decomp-reference
|
||||
title: "Decomp Reference — resource types, ClassIDs, offsets, addresses, env gates"
|
||||
status: established
|
||||
source_sections: "CLAUDE.md §10c; game/reconstructed/CLASSMAP.md; reference/decomp/all/part_*.c"
|
||||
related_topics: [subsystems, combat-damage, reconstruction-gotchas, build-and-run, gauges-hud]
|
||||
key_terms: [ClassID, resource-type, subsystem-roster, BTL4OPT, factory]
|
||||
open_questions:
|
||||
- "0xBCE weapon family fully mapped? (GaussRifle : Emitter, FireWeapon is a no-op in this build)"
|
||||
---
|
||||
|
||||
# Decomp Reference
|
||||
|
||||
The quantitative hub for the reconstruction: resource-type enum, ClassID map, mech struct
|
||||
offsets, key `FUN_` addresses, and env gates. Cite a section here rather than re-deriving.
|
||||
Everything is `[T1]` (decompiled + byte-verified) unless tagged otherwise. The living
|
||||
source-of-truth is `reference/decomp/all/part_*.c`; the class map is
|
||||
`game/reconstructed/CLASSMAP.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Resource lookup
|
||||
|
||||
`ResourceFile::FindResourceDescription(name, type, index=-1)` (`FUN_00406ff8` = find-by-type-and-name;
|
||||
`FUN_00407064` = `SearchList(resourceID, type)`). Lookup is **by NAME or by ID**. `Mech::ResolveAnimationClip(prefix,suffix)` builds a name and calls it.
|
||||
|
||||
⚠ A clip_id from `ResolveAnimationClip` is a **DIRECT resource ID** → `FindResourceDescription(clip_id)`,
|
||||
NOT `SearchList(clip_id, 16)` (which treats the arg as a LIST → walks garbage → AV). [T1]
|
||||
|
||||
### Resource type enum
|
||||
| Type | Value | Holds |
|
||||
|---|---|---|
|
||||
| SkeletonStream | — | `.SKL` skeletons |
|
||||
| DamageZoneStream | **0x14** | damage-zone records (Mech ctor reads count + array) |
|
||||
| ModelList | **18** | model/mech names (`bhk1`, `madcat`, …) |
|
||||
| AnimationResourceType | **16 (0x10)** | animation clips (lowercase: `blhrrl`=904, `blhrrr`=905, `blhwwli`=910, `blhrrli`=916) |
|
||||
| damage-zone segment list | 0x14 | per-zone segment list |
|
||||
| critical-subsystem segment | 0x1e | crit subsystem segments |
|
||||
|
||||
Animation clip names in `BTL4.RES` are **lowercase**. [T1]
|
||||
|
||||
---
|
||||
|
||||
## 2. ClassID map (subsystem factory)
|
||||
|
||||
Base 3000 = **0xBB8**. The factory switches on the resource ClassID; the `case <Name>ClassID`
|
||||
LABELS are **systematically mislabeled** — trust the `// FUN_004xxxxx` ctor-address comment
|
||||
reconciled via `CLASSMAP.md`, not the case label. [T1]
|
||||
|
||||
| ClassID | Real class | ctor @ | Notes |
|
||||
|---|---|---|---|
|
||||
| 0xBB9 | **Mech** | @004a2d48 (`Mech::Make`) | sizeof 0x854 (binary); reconstructed 0x638 |
|
||||
| 0xBBD | **Condenser** | @4ae568 | valve; `case`="?" |
|
||||
| 0xBBE | **AggregateHeatSink** (heat-sink BANK) | @4ae8d0 | GUID 0x50e590, sizeof 0x1E4; `case`=SensorClassID |
|
||||
| 0xBC0 | **Reservoir** | @4af408 | `case`=Condenser |
|
||||
| 0xBC1 | **Generator** | @4b… | power bus |
|
||||
| 0xBC2 | **PoweredSubsystem** | @004b0f74 | sizeof 0x31C |
|
||||
| 0xBC3 | **Sensor** | — | `case`=MyomersClassID |
|
||||
| 0xBC4 | **Gyroscope** | @004b3778 | DEFERRED (NaN integrator; reverted to stub) |
|
||||
| 0xBC5 | **Torso** | @004b6b0c | sizeof 0x280; `case`=SinkSource |
|
||||
| 0xBC6 | **Myomers** | @4b8fec | `case`=Actuator; INERT un-stub |
|
||||
| 0xBC8 | **Emitter** | @004b1d18 | sizeof 0x478; energy weapon |
|
||||
| 0xBCB | **AmmoBin** | — | `case`=JumpJet; sizeof 0x22C |
|
||||
| 0xBCD | **ProjectileWeapon** | @4bc3fc | sizeof 0x448 (`case`≠ this — see VDATA.h) |
|
||||
| 0xBCE | **GaussRifle** | @4bdcb4 | : Emitter; FireWeapon is a **no-op** in this build |
|
||||
| 0xBD0 | **MissileLauncher** | @4bcff0 | sizeof 0x44C |
|
||||
| 0xBD3 | **SubsystemMessageManager** | — | DEFERRED (WAVE 8; the valve/message control hub @mech+0x190) |
|
||||
| 0xBD4 | **PPC** (: Emitter) | — | same FireWeapon as Emitter; `factory calls it GaussRifle` |
|
||||
| 0xBD6 | **HUD** | — | alloc 0x2a4; `case`=MechDisplay-ish |
|
||||
| 0xBD8 | **Searchlight** | — | `case`=LegSubsystem |
|
||||
| 0xBDC | **MechTech** | — | alloc 0x104 |
|
||||
| 0xBDE | **ThermalSight** | — | `case`=MechDisplay |
|
||||
|
||||
Identify a class at runtime with `sub->GetClassID()` (== `sub+4`). [T1]
|
||||
|
||||
### Class hierarchy (the two branches that share only MechSubsystem)
|
||||
- **Heat leaf:** `PoweredSubsystem : HeatSink : HeatableSubsystem : MechSubsystem` (Emitter/PPC/Sensor/Myomers/weapons chain here). [T1]
|
||||
- **Watcher branch:** `Torso/Gyroscope/Searchlight/ThermalSight/HUD : PowerWatcher : HeatWatcher : MechSubsystem`; `AmmoBin : HeatWatcher`. Uses a 0xC connection + 0x54 alarm (NOT the 4/8-byte heat-leaf types). [T1]
|
||||
|
||||
---
|
||||
|
||||
## 3. Mech struct offsets (`Mech*`, binary layout)
|
||||
|
||||
Reconstructed access MUST use named members/accessors — these raw offsets are the BINARY's,
|
||||
valid for reading the decomp, NOT for our compiled layout (see [[reconstruction-gotchas]]). [T1]
|
||||
|
||||
| Offset | Field | Notes |
|
||||
|---|---|---|
|
||||
| +0x11c / +0x120 | `damageZoneCount` / `damageZones[]` | inherited Entity; Mech ctor populates the array |
|
||||
| +0x124 / +0x128 | `subsystemCount` / `subsystemArray[]` | the [[subsystem-roster]] (NOT the segment table) |
|
||||
| +0x190 | `messageManager` | the 0xBD3 SubsystemMessageManager (damage guard / valve+message route source) |
|
||||
| +0x260 / +0x26c | `localOrigin` = { Point3D linearPosition; Quaternion angularPosition } | ORIGIN.h:15; position@+0x100 in some subsystem views |
|
||||
| +0x300 | segment table | skeleton `EntitySegment`s (muzzle sites, joints) |
|
||||
| +0x37c | target world `Point3D` | aim source |
|
||||
| +0x388 | target `Entity*` | HasActiveTarget() gate |
|
||||
| +0x38c | targeted sub-zone (int) | -1 = whole |
|
||||
| +0x42c | `shadowJointNode` (Joint*) | ShadowJointName @model+0xB4 |
|
||||
| +0x438 | torso subsystem cache | HUD/mapper read it |
|
||||
| +0x5b4 | HUD subsystem cache | (factory case 0xBD6 writes param_1[0x16d]) |
|
||||
| +0x650 | `deathAnimationLatched` / crashed flag | |
|
||||
| +0x7cc | `damageableSubsystems` chain | the condenser chain (GUID 0x50e4fc) RecomputeCondenserValves iterates |
|
||||
|
||||
`mech+0x100` (a subsystem-view of localOrigin.linearPosition): `.x@+0x100, .z@+0x108`. [T1]
|
||||
|
||||
---
|
||||
|
||||
## 4. Damage delivery
|
||||
|
||||
- `Entity::TakeDamageMessage(id, size, inflictingEntityID, zone, Damage&)` → `target->Dispatch(&msg)`.
|
||||
- Base `Entity::TakeDamageMessageHandler` **IGNORES zone==-1** — send a VALID zone index (the Mech cylinder-lookup override for unaimed hits is not reconstructed). [T1]
|
||||
- `class Damage { damageType(enum Collision/Ballistic/Explosive/Laser/Energy), damageAmount, damageForce, surfaceNormal, impactPoint, burstCount }`. [T1]
|
||||
- Weapon effect id: **"explode" = 13** (`Explosion::Make`). [T2]
|
||||
- `DestroyEntityMessage(id,size)` removes an entity — but a killed mech STAYS (a WRECK); death = a STATE transition (`SetGraphicState(DestroyedGraphicState)`), NOT removal. Issuing removal-on-death is the P5 teardown bug (do not). [T2]
|
||||
|
||||
---
|
||||
|
||||
## 5. Weapon fire-rate constants (recovered)
|
||||
|
||||
From the weapon `.SUB` records + the charge-curve `.data` constants (PE-parsed as x87 float10). [T1]
|
||||
- `DischargeTime` = beam-on time. ER-medium laser (BLH) = **0.2 s**.
|
||||
- `RechargeRate` = recharge time in **seconds exactly** (the two ln5 factors cancel): ER-S 1.0 / ER-M 2.0 / ER-L 4.0 / PPC 5.0.
|
||||
- One BLH ER-M cycle = 0.2 + 2.0 = **2.2 s**; ~12 lasers staggered → aggregate ≈ 5/s.
|
||||
- `WeaponRange` 500 (ER laser), `DamageAmount` 3.5, `PipColor` 1.0 0.0 0.0 (RED).
|
||||
- Charge constants: `_DAT_004bb3c4`=1.0, `_DAT_004bb3b8`=1e-4, `_DAT_004bb3b4`=0.5; RatedVoltage (GENRATOR.SUB)=1e4; fire threshold `seekVoltage[rec]=0.8*RatedVoltage`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Env-var gates (runtime; default OFF unless noted)
|
||||
|
||||
The authentic stack is DEFAULT-ON (`BTEnvOn`, mechrecon.hpp): `BT_GAIT_CUTOVER`, `BT_GAIT_SM`,
|
||||
`BT_COLLISION`, `BT_REAL_CONTROLS` default ON — set `=0` to fall back. ⚠ Gates check
|
||||
`getenv(name) != NULL`, so `BT_X=""` (empty) still ENABLES; use `Remove-Item Env:\BT_X`.
|
||||
|
||||
| Var | Effect |
|
||||
|---|---|
|
||||
| `BT_FORCE_THROTTLE` | auto-walk forward (no key) |
|
||||
| `BT_SPAWN_ENEMY` | spawn a target mech 120u ahead along the spawn facing |
|
||||
| `BT_FORCE_FIRE` | auto-fire on cooldown |
|
||||
| `BT_ASSERT_TO_DEBUGGER` | route CRT asserts to the debugger, not a modal box |
|
||||
| `BT_HEAPCHECK` | whole-heap validation on every alloc/free (O(n²) at mission load — SLOW) |
|
||||
| `BT_PROBE_BGF=<name\|ALL>` | boot-time BGF loader probe, exits after |
|
||||
| `BT_LOG=<file>` | per-instance log file (in content/) |
|
||||
| `BT_GAUGE_ATTR_LOG` | `[attr] <binding> OK/NULL` per config binding |
|
||||
| `BT_GAUGE_SKIP_LOG` | `[gskip] <primitive>` per unregistered gauge widget the parse skips |
|
||||
| `BT_VALVE_LOG` | condenser valve flow distribution |
|
||||
| `BT_SECTOR_LOG` | SectorDisplay Make/Execute |
|
||||
| `BT_NET_TRACE` | `[net-tx]/[net-rx]/[net-upd]` MP tracing |
|
||||
| `BT_DEV_GAUGES` | render the 6 pod MFD surfaces in a separate dev window |
|
||||
|
||||
Full render/locomotion gates (BT_RAMP, BT_MATPRI, BT_CULL, BT_SHADOW_*, BT_LODSEL, BT_ADDLOD,
|
||||
BT_PUNCH, …) are catalogued in [[rendering]].
|
||||
|
||||
---
|
||||
|
||||
## 7. Tools
|
||||
|
||||
- `tools/disas2.py <VA> [len]` — capstone disassembly of BTL4OPT.EXE at a VA (recovers x87 math
|
||||
Ghidra drops; folds known call targets + float constants). THE tool for any `FUN_` the
|
||||
assert-anchored exporter didn't capture (e.g. `@0x4ae464` MoveValve, `@0x4ca07c` Execute).
|
||||
- `tools/disas2.py`-style PE reads: `scratchpad/rdva.py` (4-byte VA read), `rdtbyte.py` (80-bit float10).
|
||||
- `reference/ghidra_scripts/ExportBTSource.java` — the headless assert-anchored decompiler.
|
||||
- `reference/ghidra_scripts/DecompVSS.java` — headless address-list decompiler (any skipped fn).
|
||||
- `tools/btconsole.py` — the MP console emulator. `tools/mapscan.py`/`resscan.py` — content scanners.
|
||||
|
||||
---
|
||||
|
||||
## Key Relationships
|
||||
- Feeds: [[subsystems]] (factory + ClassIDs), [[combat-damage]] (damage delivery), [[gauges-hud]] (attribute binding).
|
||||
- Verified against: [[reconstruction-method]] (the decomp loop), [[reconstruction-gotchas]] (why raw offsets fail).
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
id: gauges-hud
|
||||
title: "Cockpit Gauges / MFD HUD system"
|
||||
status: established
|
||||
source_sections: "docs/GAUGE_COMPOSITE.md (full map); CLAUDE.md §8"
|
||||
related_topics: [reconstruction-gotchas, decomp-reference, subsystems, pod-hardware]
|
||||
key_terms: [gauge, methodDescription, attribute-pointer, GaugeRenderer, MFD, PCC]
|
||||
open_questions:
|
||||
- "Valve/message CONTROL routes need the 0xBD3 SubsystemMessageManager (WAVE 8)"
|
||||
- "Status-message queue (StatusMessagePool) is a NULL stub -> MessageBoard is empty"
|
||||
---
|
||||
|
||||
# Cockpit Gauges / MFD HUD
|
||||
|
||||
The pod's cockpit instruments: the secondary MFD (radar/heat/comm), the 5 mono MFDs, and the
|
||||
engineering screens. Full map + per-widget history in **`docs/GAUGE_COMPOSITE.md`**. **The gauge
|
||||
system is COMPLETE** at the registration+binding level: all 50 config attribute bindings resolve
|
||||
(0 NULL) and every config gauge primitive is registered + built (0 parse-skips). [T2]
|
||||
|
||||
## Architecture (three layers)
|
||||
1. **The config** `content/GAUGE/l4gauge.cfg` — a text file the engine `GaugeInterpreter` parses
|
||||
(`BuildConfigurationFile → Initialize → GetProcedureBody → ParsePrimitive`). Each mech's gauge
|
||||
tree is built from the label `GetGameModel()+"Init"` (e.g. `bhk1Init`), which invokes shared
|
||||
blocks (`MechInit`, `Secondary1`) that `configure` the ports and call gauge primitives. [T1]
|
||||
2. **Widgets** — each `keyword(...)` in the config resolves to a `MethodDescription` in
|
||||
`BTL4MethodDescription[]` (btl4grnd.cpp). An UNREGISTERED keyword is **parse-skipped** (never
|
||||
built). Base primitives (`numeric`/`digitalClock`/`rankAndScore`/`vertBar`-base/`segmentArc`)
|
||||
are ENGINE (L4GAUGE.cpp); BT-specific ones (`vertBar`/`map`/`pilotList`/`GeneratorCluster`/
|
||||
`sectorDisplay`/`prepEngr`/`messageBoard`/`vehicleSubSystems`/the ColorMapper family) are
|
||||
reconstructed + registered. [T2]
|
||||
3. **Data binding** — gauges bind to game state by NAME via the engine [[attribute-pointer]]
|
||||
system: the config's `Subsystem/Attribute` (e.g. `HeatSink/CurrentTemperature`) resolves
|
||||
through `ParseAttribute → FindSubsystem (stricmp GetName()) → GetAttributePointer`. A class
|
||||
PUBLISHES an attribute via a `<Name>AttributeID` enum + `static AttributePointers[]`
|
||||
(`ATTRIBUTE_ENTRY`) + `GetAttributeIndex()` chained to its parent. ⚠ DENSE-TABLE HAZARD (see
|
||||
[[reconstruction-gotchas]] §11). [T2]
|
||||
|
||||
## Reconstructing a widget — the recipe
|
||||
`MethodDescription Class::methodDescription = { "keyword", Class::Make, { ParameterDescription
|
||||
rows } };` + a line in `BTL4MethodDescription[]` before `&BTL4ChainToPrevious`. The static
|
||||
`Make(int port, Vector2DOf<int> pos, Entity*, GaugeRenderer*)` reads `methodDescription.parameterList[]`,
|
||||
allocs (`operator new(binSize)` or plain `new`), placement-news the ctor. Then ctor/dtor/
|
||||
TestInstance/BecameActive/Execute. **Gotchas that bite EVERY widget:**
|
||||
- Container-Execute must override (§10 gotchas) — else `Gauge::Execute` aborts.
|
||||
- `/FORCE` trap — a prose-only slot AVs on first call.
|
||||
- Databinding trap — never raw-read owner offsets; use a bridge (`BTGetSubsystemAuxScreen`, …).
|
||||
- ReconStream no-op — use `DEBUG_STREAM` for logs, not `DebugStream`.
|
||||
- Lazy build — wait for the gauge window before concluding "not built" (`BT_GAUGE_SKIP_LOG`). [T2]
|
||||
|
||||
## The completed widgets (this project's gauge wave)
|
||||
- **Attributes published:** HeatSink table (Degradation/Failure/NormalizedPressure/CoolantMassLeakRate/
|
||||
ValveSetting/…), PoweredSubsystem (InputVoltage), MechWeapon (OutputVoltage), Mech (LinearSpeed,
|
||||
radar Position/Quaternion), Sensor (RadarPercent), **AggregateHeatSink (AmbientTemperature=300 —
|
||||
the LAST NULL)**. [T2]
|
||||
- **Widgets reconstructed + registered:** ColorMapper family (cmHeat/cmCrit/cmArmor/multiArmor),
|
||||
headingPointer, vertBar (VertTwoPartBar), segmentArcRatio, oneOfSeveralPixInt, map (radar),
|
||||
PlayerStatus, vehicleSubSystems (the engineering cluster panels), LeakGauge, vertNormalSlider,
|
||||
**pilotList** (Comm KILLS/DEATHS), **GeneratorCluster**, **SectorDisplay** (radar SECTOR X/Z
|
||||
read-out — live), **PrepEngrScreen** (12 engineering-screen label overlays), **MessageBoard**
|
||||
(comm ticker — deferred-empty). [T2]
|
||||
- **Condenser valve gauge:** ValveSetting→coolantFlowScale reads the authentic **1/N**
|
||||
(`RecomputeCondenserValves`, FUN_0049f788, was a no-op stub). [T2]
|
||||
|
||||
## Dev composite (off-pod)
|
||||
`BT_DEV_GAUGES` renders the 6 pod [[MFD]] surfaces in a separate 960×384 window (bit-plane masks
|
||||
over one shared `SVGA16` pixelBuffer; `SVGA16::DrawDevSurface`). On the POD they come from
|
||||
`SETENV.BAT`/`L4GAUGE` on the real multi-adapter hardware (`FindBestAdapterIndices`/`BuildWindows`,
|
||||
intact). The `overlay` port (SectorDisplay lives there) shares the `sec` physical surface via a
|
||||
different bit-plane (0x00C0). [T2]
|
||||
|
||||
## Authentically-static (do NOT "fix")
|
||||
`currentTemperature ~77` (huge thermalMass ~1.39e6 → a 3.5-heat shot rounds to zero);
|
||||
Degradation/Failure temps are fixed markers; AmbientTemperature 300; CoolantMassLeakRate 0 on a
|
||||
pristine mech (damage-gated); cmArmor/cmCrit all-green (undamaged solo player — BT is PvP-only);
|
||||
RANK 1 solo; MessageBoard empty (no status messages exist in bring-up). The Heat MFD is
|
||||
authentically NEAR-STATIC, not a live heat-accumulation display. [T2]
|
||||
|
||||
## Remaining = DATA FEEDS, not widgets (deferred systems)
|
||||
The valve/message CONTROL routes need the **0xBD3 SubsystemMessageManager** (WAVE 8); the
|
||||
status-message queue needs **StatusMessagePool** (a NULL stub); `SeekVoltageGraph`'s 4 Seek*
|
||||
attrs are a cluster-child (not config-called). See [[open-questions]]. [T2]
|
||||
|
||||
## Key Relationships
|
||||
- Full history: `docs/GAUGE_COMPOSITE.md`.
|
||||
- Uses: [[attribute-pointer]] + [[reconstruction-gotchas]]; reads [[subsystems]] state.
|
||||
- Renders on: [[pod-hardware]] MFD surfaces.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: open-questions
|
||||
title: "Open Questions — deferred systems, unknowns, get-from-Nick"
|
||||
status: living
|
||||
source_sections: "CLAUDE.md §9; docs/HARD_PROBLEMS.md; per-subsystem deferral notes"
|
||||
related_topics: [source-completeness, subsystems, multiplayer, combat-damage, locomotion]
|
||||
---
|
||||
|
||||
# Open Questions
|
||||
|
||||
Known unknowns + deliberately-deferred systems. For each: what's known, what's missing, what
|
||||
would resolve it, status. Deferred ≠ broken — most are marked-and-guarded stand-ins with the
|
||||
authentic path scoped.
|
||||
|
||||
## From Nick (external — gating for some paths)
|
||||
- **[GATING] The BT game SOURCE CODE** — the missing implementation `.cpp` (mech, subsystems,
|
||||
mapper, HUD, app; see [[source-completeness]]). Without it, Route A (recompile original) is
|
||||
impossible; we reconstruct from the binary instead. Likely on a backup/dev drive. Status: OPEN.
|
||||
- Confirmation the PodPC image is the complete content master. (Low priority — the runtime
|
||||
`BTL4.RES` already has 8 maps + the full mech anim set.) Status: OPEN.
|
||||
- Pod specifics for Phase 8: the 7-monitor driver setup, the RIO cockpit I/O protocol, current
|
||||
Win10+wrapper pod config. Status: OPEN.
|
||||
|
||||
## Deferred subsystems / feeds (authentic path scoped, marked in code)
|
||||
- **0xBD3 SubsystemMessageManager (WAVE 8)** — the per-mech message/damage hub @mech+0x190. Gates:
|
||||
the condenser valve CONTROL route (`MoveValve` @0x4ae464 is reconstructed but dormant — no
|
||||
caller + its guard reads the messmgr); the MessageBoard source; the Myomers advanced-damage
|
||||
gate; gauge control-mode cycling. What resolves it: reconstruct 0xBD3 + wire the message routes.
|
||||
- **StatusMessagePool (NULL stub, btstubs.cpp:62)** — the per-player status-message queue.
|
||||
BTPlayer+0x1dc is never populated → MessageBoard is empty (authentic for bring-up). What
|
||||
resolves it: wire the pool + decode `AddStatusMessage @0042e580` + the `Player__StatusMessage`
|
||||
record ({messageId@+0xc, nameEntity@+0x10}).
|
||||
- **Gyroscope (0xBC4)** — layout + joint-I/O reconstructed, but the ctor field-init + the two
|
||||
integrators (IntegrateEyeJoint @004b2ec0 / IntegrateBody @004b30ec) are incomplete → writes NaN
|
||||
to the root joint. Reverted to a stub. A full subsystem-sim reconstruction (bigger than Torso).
|
||||
- **MechControlsMapper look/eyepoint commit** — reconstructed but its offsets collide with declared
|
||||
members; arbitrate before enabling (no port consumer yet). The fire-trigger-through-mapper is
|
||||
still the `gBTWeaponTrigger` bring-up.
|
||||
- **Myomers authentic coupling** — the structural un-stub is INERT (mover feed + heat-gen no-op).
|
||||
Real coupling needs the 0xBD3 advanced-damage gate + `MoverAttach` routing into the LIVE
|
||||
JointedMover (must be reconciled with the gait cutover first).
|
||||
- **SeekVoltageGraph** — 4 Seek* attrs unpublished (a cluster-child, not config-called; non-blocking).
|
||||
|
||||
## Locomotion / combat polish (non-gating)
|
||||
- Authentic per-mech TURN-RATE constant (currently a bring-up constant rate).
|
||||
- Body-callback gimp handlers (states 16-19, targets 0x70b2/0x7161 undecoded → fall back to stand);
|
||||
airborne callbacks (`FUN_004a6344`/`FUN_004a7970`).
|
||||
- Wall-block-vs-climb tuning; collision DAMAGE application (computed, not applied in bring-up).
|
||||
- Death: reconstruct `DeathShutdown` (RP `VTV::DeathShutdown` analog) + collapse anim + destroyed
|
||||
skin. The wreck-stays behavior we ship is faithful; do NOT issue DestroyEntityMessage on death.
|
||||
|
||||
## Multiplayer (Phase 7 / P6)
|
||||
- Cross-pod COMBAT (target a replicant + route damage to the owning master).
|
||||
- Replicant GAIT animation (replicants don't animate joints yet — derive from replicated velocity).
|
||||
- The pod-LAN config (real IPs, bare-IP pilot entries). The WinSock2 TCP stack (L4NET.CPP) is
|
||||
reconstructed + smoke-tested on one box (two instances share a world, movement replicates).
|
||||
|
||||
## Rendering follow-ups (non-blocking)
|
||||
- Replacement-LOD selection for NON-additive multi-LOD models (needs the board's hot-spot/
|
||||
reference-point semantics; leads: `s_dplobject.lod_ranges[16]/lod_hot_spot`, 0x2047/0x2048).
|
||||
- Day/night MATERIAL path priority (BMF/IMG) — infrastructure done, gated `BT_MATPRI` (over-applies
|
||||
to shared terrain mats); needs the terrain-material model understood.
|
||||
- RGBA4444 alpha (TREE.BSL cutout) decoded but not alpha-tested outside punch batches; VTX/TGA paths.
|
||||
|
||||
## Content build sub-project (low priority)
|
||||
- Lab/other-build maps (`des`/`burnt`/`frstrm`) are source-only (`.map` in CONTENT/BT/MAPS/); would
|
||||
need compiling into a RES via the DOS `btl4tool.exe`. The 8 RES maps cover testing.
|
||||
|
||||
## Key Relationships
|
||||
- Feeds from: every subsystem/render topic (their deferral notes collect here).
|
||||
- Gating master: [[source-completeness]] (the missing BT source).
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
id: reconstruction-gotchas
|
||||
title: "Reconstruction Gotchas — the systemic bug classes (check these FIRST)"
|
||||
status: established
|
||||
source_sections: "CLAUDE.md §5a, §10c; docs/HARD_PROBLEMS.md; docs/RESOURCE_AUDIT.md; gauge-wave notes"
|
||||
related_topics: [reconstruction-method, decomp-reference, subsystems, combat-damage, gauges-hud]
|
||||
key_terms: [shadow-field, databinding-trap, Wword-trap, FORCE-trap, dtor-epilogue, bridge, attribute-pointer]
|
||||
open_questions:
|
||||
- "Which reconstructed classes still carry un-audited raw-offset reads?"
|
||||
---
|
||||
|
||||
# Reconstruction Gotchas
|
||||
|
||||
The reconstruction is a **layout + linkage** problem as much as a logic problem. Our compiled
|
||||
classes are NOT byte-identical to the 1995 binary, and the BT link uses `/FORCE`, so a whole
|
||||
family of bugs is **silent** — garbage that happens to be non-fatal, or a runtime AV with no
|
||||
link error. When a reconstructed class misbehaves, walk this checklist FIRST; the answer is
|
||||
usually here, not in the logic.
|
||||
|
||||
> **The core rule (RULE: no stand-ins):** the full game logic IS in the pseudocode — a "gap"
|
||||
> is a reconstruction stub not yet filled, never a hole in the original. Never write
|
||||
> placeholder logic for an apparent gap; read the decomp. (User: "there are no gaps, just
|
||||
> work to be done.") Bring-up scaffolding (env-var paths, explosion-for-beam) is clearly
|
||||
> marked and meant to be REPLACED, never to substitute for reading the decomp. [T2]
|
||||
|
||||
---
|
||||
|
||||
## 1. Shadow field — re-declaring an engine-base field (THE most common)
|
||||
|
||||
**Symptom:** a field reads `0xCDCDCDCD` (fresh-heap fill) even though the ctor "sets" it; or an
|
||||
object over-sizes past its factory alloc. **Cause:** the reconstruction re-declared a field the
|
||||
engine base already owns, at the *binary's* offset. Two failures: (a) the copy **shadows** the
|
||||
base — the engine ctor writes the base field, the reconstruction reads its own uninitialised
|
||||
copy; (b) it lands at a **different offset** than the binary assumed.
|
||||
|
||||
**Fix:** delete the re-declaration; use the inherited member/accessor. Examples: `Mech`
|
||||
`damageZoneCount`/`damageZones` (shadowed `Entity`'s → zones never built); `Mech__DamageZone`
|
||||
`structureLevel`→engine `damageLevel`; the whole `HeatableSubsystem` de-shadow
|
||||
(`statusFlags`→`simulationFlags`, `destroyed`→`simulationState`, `statusBits`→`ForceUpdate()`).
|
||||
[T2]
|
||||
|
||||
## 2. Wword(N) — a global scratch bank, NOT this+N
|
||||
|
||||
`mechrecon.hpp:192` defines `Wword(int i)` as `static BTVal bank[0x400]; return bank[i&0x3ff]`.
|
||||
Any `Wword(N)` used for OBJECT access reads/writes a shared global, not `this+i*4`. e.g.
|
||||
`(Mech*)Wword(3)` for a zone's owner → garbage; use `GetOwningSimulation()`. [T2]
|
||||
|
||||
## 3. Databinding trap — raw offsets read garbage
|
||||
|
||||
Our compiled layout != the 1995 binary, so `*(T*)(obj+0xNN)` reads garbage for ANY object we
|
||||
compile. This is WHY shadow fields fail and why raw subsystem reads (e.g. a gauge reading
|
||||
`owner+0x438`) return junk. **Fix:** use compiled named members/accessors; for a cross-TU raw
|
||||
op, use a **bridge** (§8). A `+0x128`-style owner offset in subsystem code is the
|
||||
[[subsystem-roster]] (`subsystemArray`), NOT the segment table — check every `GetSegment(int)`
|
||||
in a reconstructed subsystem ctor. [T2]
|
||||
|
||||
## 4. Resource-struct layout mismatch (sibling of the shadow bug)
|
||||
|
||||
**Symptom:** RESOURCE fields read garbage (silently — a `heatSinkIndex` reading `10.0f`).
|
||||
**Cause:** `*__SubsystemResource` structs overlay pre-built 256-byte records loaded VERBATIM at
|
||||
fixed offsets, so OUR struct must match the binary byte-for-byte. Breaks two ways: (a) wrong
|
||||
inheritance base (the resource must mirror the CLASS hierarchy — `HeatableSubsystem`'s resource
|
||||
inherits `MechSubsystem__SubsystemResource` 0xE4, not `Subsystem::SubsystemResource` 0x30); (b)
|
||||
under-sized fields (a 12-byte record field typed as a 4-byte `ResourceID`). **Diagnose:** log
|
||||
compiled offsets `(char*)&res->field - (char*)res` vs the binary's; dump raw record bytes as
|
||||
int+float. **Lock:** `static_assert(offsetof(...)==0xNN)` + `static_assert(sizeof(...)==0xNN)`.
|
||||
The 33-agent RESOURCE_AUDIT fixed 8 such bugs (docs/RESOURCE_AUDIT.md). [T2]
|
||||
|
||||
## 5. Alias / phantom / interior fields (object layout)
|
||||
|
||||
- **Alias field:** a subclass member re-declaring an inherited slot the ctor reuses under a new
|
||||
name (Condenser `refrigerationOutput`==inherited `massScale@0x160`; Emitter
|
||||
`outputVoltage`==`rechargeLevel@0x320`). → delete, use the inherited name.
|
||||
- **Alarm-interior field:** a value the binary reads at `alarm+0x14` modeled as a separate
|
||||
member (HeatSink `heatState@0x184` == `heatAlarm.GetLevel()`). → route to the accessor.
|
||||
- **Phantom field:** a member at an offset PAST the object (Generator `shortFlag@0x25C` is
|
||||
really `*(owner+0x190)+0x25c` the msg-manager). → remove; read the real source.
|
||||
`GaugeAlarm54` = 0x54 (the real `AlarmIndicator`; STATUS level at +0x14, so
|
||||
`subsystem+0x184 == heatAlarm+0x14 == GetLevel()`); `SubsystemConnection` = 0xC. [T1]
|
||||
|
||||
## 6. /FORCE trap — unresolved symbol → runtime AV, not a link error
|
||||
|
||||
`/FORCE` turns an unresolved external (or a prose-only vtable slot) into a **runtime AV near
|
||||
`__ImageBase`**, NOT a link error. **When a /FORCE build crashes with a garbage call target
|
||||
near the image base, grep the link log for "unresolved external" — the "successful" build is
|
||||
lying.** Corollary: a bridge fn / a `.data` fn-ptr callback MUST have a real (stub) definition.
|
||||
A `SetVideoPathPriority` defined in an anonymous namespace → internal linkage → unresolved in
|
||||
another TU → stubbed by /FORCE → AV in `LoadMissionImplementation`. [T2]
|
||||
|
||||
## 7. Dtor-epilogue rule — do not reconstruct compiler glue
|
||||
|
||||
In a decompiled DESTRUCTOR, the trailing member-dtor calls (`FUN_xxx(this+N, 2)`), the base-dtor
|
||||
call (`FUN_xxx(this, 0)`), and the `(flags&1) && operator delete(this)` tail are COMPILER GLUE.
|
||||
Reconstruct only the body ABOVE them; C++ re-emits member+base destruction at the closing brace.
|
||||
An explicit base-dtor call runs the whole `~JointedMover → ~Mover → ~Entity` chain **TWICE** =
|
||||
the P5 double-free (re-`delete[]`s `collisionLists`, re-runs `DeletePlugs` over the freed segment
|
||||
table). ONE bug = BOTH the death-row crash AND the app-exit crash. [T2]
|
||||
|
||||
## 8. Bridges — the databinding-safe escape hatch
|
||||
|
||||
When TU A needs a raw-offset-safe op but its local RECON stubs collide with the real class
|
||||
headers, put the op in a **bridge**: a free function in a complete-type TU, `extern`-declared in
|
||||
A. Examples: `BTResolveWeaponMuzzle` (mech4.cpp — a complete-Mech TU with the segment API),
|
||||
`BTRecomputeCondenserValves` (heatfamily_reslice.cpp — sees Condenser), `BTResolveMessageBoard`
|
||||
(btplayer.cpp — complete BTPlayer), `BTGetSubsystemAuxScreen` (powersub.cpp — casts through the
|
||||
real PoweredSubsystem). Keep the alloc SIZE + special-cache when swapping a factory case. [T2]
|
||||
|
||||
## 9. Message-handler chaining + entity validity
|
||||
|
||||
- A reconstructed class's `MessageHandlers` set must be built **chained to the parent's**
|
||||
(`Receiver::MessageHandlerSet(Entity::GetMessageHandlers())`). An empty default-ctor set has
|
||||
no parent chain → `Receiver::Receive` finds no handler → every inherited message (TakeDamage!)
|
||||
is **silently dropped**. [T2]
|
||||
- `Entity::Dispatch` delivers synchronously only for a VALID master; an invalid entity `Post`s a
|
||||
deferred event that never fires. A manually-spawned entity (no CheckLoad handshake) must call
|
||||
`SetValidFlag()` itself — else EVERY message defers forever (the replicant / spawned-dummy /
|
||||
MessageBoard-source class of bug). [T2]
|
||||
|
||||
## 10. Container-Execute must override (gauges)
|
||||
|
||||
The 2007 engine `Gauge::Execute` base is `Fail("not overridden")` → `abort()` (GAUGE.cpp:598);
|
||||
`GuardedExecute`'s SEH **cannot catch abort()**. So a container/parent gauge MUST override
|
||||
`Execute` (even as a no-op) AND override `BecameActive` with a **non-inactivating** body (the
|
||||
default `GaugeBase::BecameActive` inactivates). A `GraphicGaugeBackground`-derived widget
|
||||
(PrepEngrScreen/BackgroundBitmap) has NO Execute virtual → the hazard doesn't apply; there the
|
||||
overridden slot is `BecameActive`. [T2]
|
||||
|
||||
## 11. Dense-table hazard (attribute publishing)
|
||||
|
||||
`AttributeIndexSet::Build` leaves gap slots uninitialized and `Find` strcmps EVERY slot → a
|
||||
published attribute table MUST be a **dense prefix** from the parent's `NextAttributeID`; a gap
|
||||
AVs. Fill gaps with a shared read-only pad member. Same for a class's `<Name>AttributeID` enum.
|
||||
[T2]
|
||||
|
||||
## 12. Verification gotchas (don't fool yourself)
|
||||
|
||||
- **Lazy gauge build:** `GaugeRenderer::BuildConfigurationFile` runs LAZILY. A too-early process
|
||||
kill shows `[gskip]=0` / "not built" even though the widget is fine — **wait for the gauge
|
||||
window** before concluding. (Cost a long detour this session.) [T2]
|
||||
- **ReconStream is a no-op:** `btl4gau3.cpp`'s `DebugStream` is the `ReconStream` whose
|
||||
`operator<<` is `{ return *this; }` — it DISCARDS everything. Use the engine `DEBUG_STREAM`
|
||||
(what heat.cpp uses) for a log that reaches the BT_LOG file. [T2]
|
||||
- **Head-on repro hides intermittent bugs:** a straight ram gives 1 clean result; the bug shows
|
||||
on GLANCING/sliding/rough-terrain contact. Reproduce with an angled/terrain-crossing approach.
|
||||
[T2]
|
||||
- **`static_assert` not runtime `Check`:** a runtime `Check(sizeof<=alloc)` in a factory bridge
|
||||
does NOT fail the build (it's a runtime assert → heap overflow at construction). Use a
|
||||
compile-time `static_assert` sizeof lock. [T2]
|
||||
- **Engine-class new member:** a NEW member on a 2007 engine class (d3d_OBJECT, DPLRenderer) MUST
|
||||
be initialized in EVERY ctor init-list (debug heap fills 0xCDCDCDCD → an uninit flag reads
|
||||
TRUE); and any device state a special draw path sets must be save/restored exactly. Deleting
|
||||
stale `.obj`s fixes layout-mismatch corruption when a base class grows. [T2]
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic recipe (the standard loop)
|
||||
1. Read the RAW decomp `reference/decomp/all/part_*.c` for the `FUN_xxxx`.
|
||||
2. Map `FUN_`/`DAT_`/`this+0xNN` to engine symbols via BT headers + WinTesla MUNGA source +
|
||||
`CLASSMAP.md` + RP's parallel code.
|
||||
3. Write the REAL reconstruction; `static_assert`-lock the layout.
|
||||
4. Build; run env-gated; read `btl4.log`; cdb on any crash (0xCDCDCDCD=uninit, 0xFEEEFEEE=freed).
|
||||
5. For exhaustive multi-function analysis: a read-only Workflow (understand), then implement hands-on.
|
||||
|
||||
## Key Relationships
|
||||
- Applies to: every topic that reconstructs a class ([[subsystems]], [[combat-damage]], [[gauges-hud]], [[locomotion]]).
|
||||
- Uses: [[decomp-reference]] (offsets/ClassIDs), [[reconstruction-method]] (the loop).
|
||||
Reference in New Issue
Block a user