Files
BT411/reference/glossary.yaml
T
arcattackandClaude Opus 4.8 1cd57ade85 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>
2026-07-07 22:06:53 -05:00

344 lines
20 KiB
YAML

# BattleTech Pod-Port — Glossary
# Terms, acronyms, class/format names used across the reverse-engineering + reconstruction.
# Each entry: definition, kind (concept|format|class|tool|file), where it's discussed, related terms.
# Evidence tiers (see CLAUDE.md): T0 engine/header truth · T1 decompiled+verified ·
# T2 reconstructed+runtime-verified · T3 best-effort/guarded · T4 unconfirmed hypothesis.
# ---------------------------------------------------------------------------
# Platform / engine
# ---------------------------------------------------------------------------
MUNGA:
kind: concept
definition: The proprietary VWE game engine shared by BattleTech (BT) and Red Planet (RP). Renderer, mover/animation, math, scene graph. Lives in engine/MUNGA/.
related_terms: [MUNGA_L4, L4, BT, RP, WinTesla]
related_topics: [project-overview, wintesla-port]
MUNGA_L4:
kind: concept
definition: The hardware-abstraction layer (HAL) for MUNGA — video-out, input, timing, file I/O, audio. "L4" is the HAL brick. On the port it targets Win32/Direct3D9. Lives in engine/MUNGA_L4/.
related_terms: [MUNGA, L4, L4D3D, DPL]
related_topics: [wintesla-port, rendering]
L4:
kind: concept
definition: Shorthand for the MUNGA_L4 HAL. Prefixes its files (L4VIDEO, L4NET, L4CTRL, L4GAUGE, L4RIO, L4SERIAL, ...).
related_terms: [MUNGA_L4, RIO]
BT:
kind: concept
definition: BattleTech — the primary port target. VWE arcade pod game, Tesla platform release 4.10 (~1995-96). Game logic = CODE/BT (mostly MISSING as source; reconstructed from the binary).
related_terms: [RP, MUNGA, BTL4OPT, source-completeness]
related_topics: [project-overview, source-completeness]
RP:
kind: concept
definition: Red Planet — the sibling VWE pod game sharing the MUNGA engine. Its game source (VTV/VTVMPPR/WEAPSYS) SURVIVES in the WinTesla archive and is the live reference for BT's parallel systems (VTV≈mech, WEAPSYS≈weapons).
related_terms: [BT, WinTesla, MUNGA]
related_topics: [wintesla-port, source-completeness]
Tesla-platform:
kind: concept
definition: VWE's arcade pod hardware/software platform. Original BT ran 32-bit DOS under a DPMI32 extender (Borland C++ 5 + TASM32) on Novell DOS pods with a Division IG image-generator board.
related_terms: [IG-board, DPL, pod]
related_topics: [pod-hardware, project-overview]
pod:
kind: concept
definition: The physical arcade cockpit. 2 video cards -> 7 monitors (main 3D 800x600, radar 640x480, five mono MFDs as one 1280x480 span). Cockpit I/O ("RIO") over serial. Now runs Windows 10 + a Voodoo/Glide wrapper.
related_terms: [RIO, MFD, IG-board]
related_topics: [pod-hardware]
RIO:
kind: concept
definition: The pod cockpit I/O — joystick X/Y, throttle, pedals, buttons over serial COM (L4RIO, L4SERIAL). Remapped to keyboard/gamepad on a dev box.
related_terms: [pod, L4, MechControlsMapper]
related_topics: [pod-hardware, locomotion]
IG-board:
kind: concept
definition: Division "IG" image-generator board (dual EISA) — the original 3D renderer, driven by the closed-source libDPL.lib + VREND microcode. The port REPLACES it with a dpl_* -> Direct3D9 shim (done in WinTesla as L4D3D).
related_terms: [DPL, L4D3D, WinTesla]
related_topics: [rendering, wintesla-port]
DPL:
kind: concept
definition: libDPL / dpl_* — the closed Division rendering API MUNGA called for 3D (dpl_*) and 2D (dpl2d_*). Shipped binary-only. Replaced by L4D3D in WinTesla; a few unported dpl_* effects (weapon beams) are re-implemented in the port.
related_terms: [IG-board, L4D3D, libDPL]
related_topics: [rendering]
L4D3D:
kind: file
definition: MUNGA_L4/L4D3D.cpp — the WinTesla renderer that replaced the IG board / libDPL with Direct3D9. THE hardest infrastructure, already done in the WinTesla archive.
related_terms: [DPL, WinTesla, rendering]
related_topics: [wintesla-port, rendering]
WinTesla:
kind: concept
definition: The Windows port of the MUNGA engine found in the "Elsewhen RP411" archive (VS2005). Renderer bypass (L4D3D), audio (OpenAL+libsndfile), L4 HAL, and full Red Planet game logic all work. BT's game layer is ABSENT (must be reconstructed). The bt411 repo builds on this engine.
related_terms: [MUNGA, RP, L4D3D, source-completeness]
related_topics: [wintesla-port, source-completeness, build-and-run]
# ---------------------------------------------------------------------------
# Binary / decompilation
# ---------------------------------------------------------------------------
BTL4OPT:
kind: file
definition: BTL4OPT.EXE — the real BT game binary (1.24 MB, uncompressed PE32, Phar Lap TNT). Unwrapped from btrel410.exe (a PKZIP self-extractor). The decompile ORACLE — retains class names, Class::Method strings, and source-file paths in asserts. In content/.
related_terms: [decomp, btrel410, oracle, BTL4.RES]
related_topics: [source-completeness, decomp-reference, reconstruction-method]
decomp:
kind: concept
definition: The raw Ghidra pseudo-C recovered from BTL4OPT.EXE, in reference/decomp/all/part_*.c. The source-of-truth every reconstruction is verified against ("there are no gaps, just work to be done").
related_terms: [BTL4OPT, oracle, reconstruction-method]
related_topics: [reconstruction-method, decomp-reference]
oracle:
kind: concept
definition: Using the original binary (BTL4OPT.EXE) as a behavioral reference — running it under cdb, or reading its decompiled logic — to verify a reconstruction is behavior-equivalent.
related_terms: [decomp, BTL4OPT, cdb]
related_topics: [reconstruction-method]
BTL4.RES:
kind: file
definition: The compiled BT resource archive (3.23 MB). Holds maps (8 loadable), animation clips (lowercase names, blhrrl=904), models, materials, skeletons, damage-zone/subsystem records. Resolved by name or ID via FindResourceDescription. In content/.
related_terms: [BTL4OPT, EGG, resource-type]
related_topics: [content-archives, decomp-reference]
cdb:
kind: tool
definition: The x86 Windows debugger (Debuggers/x86/cdb.exe). Used to trace faulting stacks. Debug CRT marks fresh heap 0xCDCDCDCD (uninitialised) and freed 0xFEEEFEEE — invaluable for "was this ever constructed?".
related_terms: [BT_HEAPCHECK, decomp]
related_topics: [build-and-run, reconstruction-method]
# ---------------------------------------------------------------------------
# Asset formats
# ---------------------------------------------------------------------------
BGF:
kind: format
definition: DIV-BIZ2 little-endian nested-TLV geometry. OBJECT->LOD->PATCH(geogroup)->PMESH; interleaved float32 verts; QUAD faces (must triangulate); materials by library:material name; damage/articulation name-driven via SV_SPECIAL dz_* tokens.
related_terms: [DIV-BIZ2, PMESH, CONN, PCONN, LOD, SV_SPECIAL, material-ramp]
related_topics: [bgf-format, asset-formats]
DIV-BIZ2:
kind: format
definition: The Division nested Tag-Length-Value container magic used by BGF (geometry) and BMF (materials). Chunk tags catalogued in dsys/PFBIZTAG.H (0x2046=LOD_DISTANCE, 0x2037=SV_SPECIAL, 0x2047/0x2048 reference/transition).
related_terms: [BGF, BMF, PFBIZTAG]
related_topics: [bgf-format, asset-formats]
BMF:
kind: format
definition: DIV-BIZ2 (FILETYPE=1) material+texture LIBRARY (no pixels). Material -> DIFFUSE color + MATERIAL_TEXTURE -> texture -> TEXTURE_MAP image basename. Tag 0x18 BITSLICE selects a BSL sub-image; 0x28 ramp ref; 0x26 emissive.
related_terms: [BGF, BSL, material-ramp, VMF]
related_topics: [asset-formats, rendering]
BSL:
kind: format
definition: DIV-BSL2 BIT-SLICED texture container. w*h 32-bit texel words hold SIX independent 4-bit GRAYSCALE sub-images (nibble pair-swapped, byte 0 pad) OR RGB444/RGBA4444 (sliceType 7/8). The BMF 0x18 BITSLICE tag picks the slice. Decoding it wrong = the "rainbow/graffiti mech" bug.
related_terms: [BMF, VTX, TGA, material-ramp]
related_topics: [asset-formats, rendering]
SKL:
kind: format
definition: INI joint skeleton. [joint] parent=, Type=(hingex/y/z|ball|balltranslate), Object=part.bgf, dzone=, tranx/y/z, pitch/yaw/roll. Build a DCS tree; neutral pose ~ translations.
related_terms: [ANI, DCS, joint, MOD]
related_topics: [asset-formats, locomotion]
ANI:
kind: format
definition: INI keyframe animation. [HEADER] framecount/framerate(30)/skeletonfile; [frameN] joint->rx ry rz radians; [RootTranslation] per-keyframe x y z where .z = forward root SPEED (units/s). Walk speed is animation-driven, not physics.
related_terms: [SKL, RootTranslation, locomotion]
related_topics: [asset-formats, locomotion]
MOD:
kind: format
definition: INI mech/object definition — skeleton, skins, collision, gauges, physics, animations, class. The .MOD physics (MoverMass/drag) governed thrust VEHICLES + collisions, NOT walk gait.
related_terms: [SKL, ANI, SLD, DZM]
related_topics: [asset-formats]
SLD:
kind: format
definition: Collision solids. Terrain is modeled AS BoxedSolid collision volumes (Block/YCyl/Cone/Ramp/Wedge). The ground model + object collision both query these via the engine BoundingBoxTree. BT solids ship ZERO tiles.
related_terms: [MoveAndCollide, BoundingBoxTree, ground-model]
related_topics: [combat-damage, locomotion]
DZM:
kind: format
definition: INI damage-zone -> material map (mech skin damage states).
related_terms: [damage-zone, DZ]
related_topics: [combat-damage]
GIM:
kind: format
definition: Vector MFD/radar line maps (+ .GAT color table). Cockpit HUD vector assets.
related_terms: [GAT, PCC, gauge]
related_topics: [gauges-hud]
PCC:
kind: format
definition: ZSoft PCX 8-bit gauge rasters — the cockpit HUD bitmap assets (fonts helv15/helv42, label strips, dials).
related_terms: [GIM, gauge, PCX]
related_topics: [gauges-hud]
VMF:
kind: format
definition: DIV-VIZ2 material SOURCE (VIDEO/MAT/.../BTFX.VMF etc.). Carries the SCROLL animation + MAP{} image binding for effects (beams, muzzle, smoke, sky). The .BMF only names the texture; the .VMF binds it + scroll speed. THE key effects asset.
related_terms: [BMF, BSL, beam]
related_topics: [rendering]
material-ramp:
kind: concept
definition: The IG board colours no-normal geometry (terrain/mesas/sky/buildings/mech) by a material's 2-endpoint RAMP (dpl_SetMaterialRamp) — texture luminance indexes a low->high gradient. Normal-bearing geometry (vehicles) is LIT instead. Applying the ramp to lit geometry = the "white blobs" bug.
related_terms: [BMF, BSL, emissive, hasNormals]
related_topics: [rendering]
# ---------------------------------------------------------------------------
# Scene / entity model
# ---------------------------------------------------------------------------
DCS:
kind: concept
definition: Dynamic Coordinate System — a transform node in the scene graph. A skeleton builds a DCS tree; each joint is a DCS.
related_terms: [SKL, joint, scene]
related_topics: [asset-formats, locomotion]
joint:
kind: class
definition: Engine Joint node (JOINT.h). GetJointType (hinge 0..2 / ball 4..5 / balltranslate 5); SetRotation(Radian|EulerAngles), SetTranslation. Resolved by name via Mech::ResolveJoint -> GetSegment(name) -> JointSubsystem::GetJoint.
related_terms: [SKL, DCS, EntitySegment, Torso]
related_topics: [locomotion]
EntitySegment:
kind: class
definition: A skeleton segment (288 bytes) in the mech's segmentTable. Maps a joint + geometry. Muzzle SITE segments (siterugunport etc.) resolve to world muzzle positions via GetSegmentToEntity x localToWorld. NOT the subsystem roster.
related_terms: [joint, subsystem-roster, GetSegment]
related_topics: [locomotion, combat-damage]
subsystem-roster:
kind: concept
definition: subsystemArray @mech+0x128 (count @0x124) — the inherited Entity table of the mech's Subsystem* instances (heat/weapons/gyro/sensor/...). A +0x128-style owner offset in subsystem code is the ROSTER, NOT the segment table (a classic bug source).
related_terms: [subsystem, factory, EntitySegment]
related_topics: [subsystems, reconstruction-gotchas]
subsystem:
kind: class
definition: A mech component (Subsystem-derived). Built by the per-class factory (Mech ctor). Ticks a per-frame Performance/Simulation. Families: heat (HeatSink/Condenser/Reservoir/AggregateHeatSink), power (Generator/PoweredSubsystem), weapons (Emitter/PPC/ProjectileWeapon/MissileLauncher/GaussRifle), Sensor/Gyroscope/Torso/Myomers/Searchlight/ThermalSight/AmmoBin/MechTech/HUD.
related_terms: [subsystem-roster, factory, ClassID, PoweredSubsystem]
related_topics: [subsystems, decomp-reference]
factory:
kind: concept
definition: The Mech-ctor per-class subsystem factory (switch on resource ClassID). The case LABELS are systematically MISLABELED — the real class is the ctor-address comment reconciled via CLASSMAP.md, not the case name. Each real class wired via a Create<Class>Subsystem bridge.
related_terms: [ClassID, subsystem, CLASSMAP]
related_topics: [subsystems, decomp-reference]
ClassID:
kind: concept
definition: RegisteredClass::ClassID — the per-subsystem-class id (base 3000=0xBB8). e.g. 0xBB9 Mech, 0xBBD Condenser, 0xBBE AggregateHeatSink(bank), 0xBC8 Emitter, 0xBD4 PPC. Read via sub->GetClassID() (sub+4). Full map in decomp-reference / CLASSMAP.md.
related_terms: [factory, subsystem, CLASSMAP]
related_topics: [subsystems, decomp-reference]
master:
kind: concept
definition: A locally-simulated entity (the pod's own mech + spawned dummies). Ticks its full drive/subsystems and EMITS network update records. Contrast replicant.
related_terms: [replicant, viewpoint-entity, multiplayer]
related_topics: [multiplayer]
replicant:
kind: concept
definition: A remote entity's local proxy (a peer pod's mech). Does NOT drive itself — it DeadReckons toward the master's replicated position. Must SetValidFlag() at creation or every message defers forever.
related_terms: [master, dead-reckon, multiplayer]
related_topics: [multiplayer]
viewpoint-entity:
kind: concept
definition: application->GetViewpointEntity() — the local pod's own mech (the cockpit view + player controls). Gate player-only logic on `this == GetViewpointEntity()` (Mech::PerformAndWatch runs for EVERY mech).
related_terms: [master, MakeViewpointEntity]
related_topics: [combat-damage, locomotion]
EGG:
kind: format
definition: The mission INI (.EGG): [mission] map= scenario= time= weather=, [pilots] roster (pilot=ip[:port] + per-pilot vehicle=/dropzone). map= resolved from BTL4.RES; a missing name null-derefs. Default test egg = DEV.EGG (map=grass, time=day).
related_terms: [BTL4.RES, mission, pilot]
related_topics: [content-archives, multiplayer]
# ---------------------------------------------------------------------------
# Reconstruction concepts (the systemic bug classes live in reconstruction-gotchas.md)
# ---------------------------------------------------------------------------
shadow-field:
kind: concept
definition: A reconstructed class re-declaring a field its engine base already owns -> shadows the base (reads uninitialised 0xCDCDCDCD) AND lands at a different offset. THE most common reconstruction bug. Fix: use the inherited member/accessor.
related_terms: [databinding-trap, Wword-trap, alias-field, phantom-field]
related_topics: [reconstruction-gotchas]
databinding-trap:
kind: concept
definition: Our compiled class layout != the 1995 binary, so a RAW offset read *(T*)(obj+0xNN) reads garbage. Use compiled named members / accessors / a bridge fn in a complete-type TU. The systemic reason raw-offset reads fail.
related_terms: [shadow-field, bridge, Wword-trap]
related_topics: [reconstruction-gotchas]
Wword-trap:
kind: concept
definition: mechrecon.hpp Wword(int i) is `static BTVal bank[0x400]; return bank[i&0x3ff]` — a GLOBAL scratch bank, NOT this+i*4. Any Wword(N) used for object access reads/writes garbage.
related_terms: [databinding-trap, shadow-field]
related_topics: [reconstruction-gotchas]
FORCE-trap:
kind: concept
definition: The BT link uses /FORCE, so an unresolved symbol (or a prose-only vtable slot) becomes 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".
related_terms: [bridge, dtor-epilogue]
related_topics: [reconstruction-gotchas, build-and-run]
dtor-epilogue:
kind: concept
definition: In a decompiled DESTRUCTOR the trailing member-dtor calls, 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. An explicit base-dtor call runs the chain TWICE (the P5 double-free).
related_terms: [FORCE-trap, P5]
related_topics: [reconstruction-gotchas, combat-damage]
bridge:
kind: concept
definition: A free function in a complete-type TU that does a raw-offset-safe operation the caller's TU can't (its local stubs collide). e.g. BTResolveWeaponMuzzle (mech4.cpp), BTRecomputeCondenserValves, BTResolveMessageBoard. The databinding-safe escape hatch.
related_terms: [databinding-trap, FORCE-trap]
related_topics: [reconstruction-gotchas, subsystems]
attribute-pointer:
kind: concept
definition: The engine system binding cockpit gauges to game state by NAME. A class publishes attributes via a <Name>AttributeID enum (dense prefix from parent NextAttributeID) + static AttributePointers[] (ATTRIBUTE_ENTRY) + GetAttributeIndex() chained to parent. ParseAttribute->FindSubsystem->GetAttributePointer resolves the config binding. DENSE-TABLE HAZARD: a gap AVs.
related_terms: [gauge, methodDescription, dense-table]
related_topics: [gauges-hud, reconstruction-gotchas]
methodDescription:
kind: concept
definition: A gauge widget's registration record: { "keyword", Class::Make, {ParameterDescription rows} }. Added to BTL4MethodDescription[] (btl4grnd.cpp). An UNREGISTERED keyword is parse-SKIPPED (never built). The Make factory allocs + placement-news the widget from config params.
related_terms: [gauge, attribute-pointer, GaugeRenderer]
related_topics: [gauges-hud]
GaugeRenderer:
kind: class
definition: The engine gauge system. BuildConfigurationFile parses gauge\l4gauge.cfg via GaugeInterpreter (Initialize->GetProcedureBody->ParsePrimitive). Builds LAZILY -> a too-early process kill shows a false "not built". Composites onto the pod's SVGA16 bit-plane surfaces.
related_terms: [methodDescription, MFD, gauge, SVGA16]
related_topics: [gauges-hud]
MFD:
kind: concept
definition: Multi-Function Display — the pod's mono cockpit screens (Heat/Comm/Mfd1/Mfd2/Mfd3), bit-plane MASKS over one shared SVGA16 pixelBuffer (Heat 0x4000, Comm 0x8000, Mfd1 0x0100, Mfd2 0x0400, Mfd3 0x1000, sec = palette low byte). Eng1-3 = engineering-mode alt planes.
related_terms: [gauge, GaugeRenderer, SVGA16, pod]
related_topics: [gauges-hud, pod-hardware]
damage-zone:
kind: class
definition: Mech__DamageZone (engine DamageZone base). Armor model: damageLevel += damageAmount*damageScale[type], accumulates to 1.0 (destroyed). Built by the Mech ctor from the DamageZoneStreamResourceType (0x14) resource. Aimed hits route via Entity::TakeDamageMessage.
related_terms: [DZM, TakeDamage, DZ]
related_topics: [combat-damage]
ground-model:
kind: concept
definition: The authentic 1995 vertical-position model (FUN_004a9b5c). NO GRAVITY — an ABSOLUTE per-frame ground SNAP via the zone BoundingBoxTree (FindBoundingBoxUnder), lift = 5% of volume X-width. Walls block by FULL FRAME REJECTION; crushable props pass with a crunch.
related_terms: [SLD, BoundingBoxTree, MoveAndCollide]
related_topics: [locomotion]
RootTranslation:
kind: concept
definition: The .ANI [RootTranslation] section — per-keyframe forward root SPEED (.z, units/s). Locomotion integrates movement += dt*rootTrans.z; feet plant by construction (no separate stride constant).
related_terms: [ANI, locomotion, SequenceController]
related_topics: [locomotion]