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