TeslaRel410/restoration/source410/BT/MECH.NOTES.md

MECH.CPP / .HPP — reconstruction notes

Status: Mech::Make (factory) reconstructed; the Mech constructor and the entire mech subsystem are the CURRENT FRONTIER — the largest remaining milestone in the reconstruction.

What is reconstructed

• Mech::Make(MakeMessage *) = return new Mech(creation_message); — the factory the registry / MakeAndLinkViewpointEntity calls.
• The static shared data (ClassDerivations / DefaultData) — from the earlier staging.
• A staged Mech ctor that chains the real JointedMover base ctor (so the model skeleton/segments stream from BTL4.RES) and then Fails.

The spawn factory path is now validated live: BTPlayer::CreatePlayerVehicle builds the Mech::MakeMessage, Application::MakeAndLinkViewpointEntity routes it through the registry to Mech::Make -> new Mech -> the JointedMover base ctor (real engine code, streams the mech model) -> the Mech ctor Fail. Boot reaches mech.cpp:66.

Why the Mech ctor is a milestone, not a brick

Mech::Mech is @004a1674, 5690 bytes — the largest single function in the game. It walks the model's segment table and instantiates the full subsystem roster (power, heat, weapons, actuators, controls, tech, damage zones), and primes ~150 members. Reconstructing it requires three things the tree does not yet have:

1. The complete 1995 Mech member layout as named fields. MECH.HPP currently carries int reserved[331] (1324 bytes) as a placeholder. BT411's Ghidra reconstruction sidesteps the layout entirely by writing raw offset pokes (Wword(0x104), *(void**)((char*)this + 0x388), this[0x14a]) — a WinTesla-port technique that CANNOT compile into a fresh 1995 build, where BC4.52 assigns offsets from the header declarations. So the layout must be derived as real members first.
2. The subsystem class hierarchy. MechSubsystem + derived: sensor, generator (gnrator), gyro, torso, HUD, myomers, plus the weapon subsystems (mechweap, ppc, gauss, projweap, mislanch, ammobin...). Of these, only GAUSS, PPC, SENSOR survive as source in the 4.10 archive (CODE/BT/BT); GNRATOR is a partial .TCP. The rest are part of the measured "917 missing functions" and come only from BT411's decomp.
3. The segment-table walk that reads the model resource and instantiates + wires each subsystem.

BT411's mech reconstruction is ~12,255 lines across mech.cpp / mech2 / mech3 / mech4 / mechsub alone, before the subsystem TUs — this is the bulk of the remaining game.

Reconstruction plan (for the dedicated mech milestone)

1. Derive the Mech member layout. Turn reserved[331] into named members. Sources: BT411's offset comments (this[0x14a] gyroSubsystem, +0x388 target entity, etc.) give the binary offsets; the embedded member types (NameFilter, AlarmIndicator, Slot/Socket, Reticle, Filter, CString, StateIndicator) come from the surviving MUNGA headers. Cross-check total size against the binary's new Mech allocation.
2. Reconstruct MechSubsystem base + the subsystem roster, backdating BT411 mechsub.cpp + the per-subsystem TUs; fold in the surviving 4.10 GAUSS/PPC/ SENSOR source where it exists (authoritative over the decomp).
3. Reconstruct the Mech ctor against the named layout: embedded-member construction, the segment-table walk, subsystem instantiation + wiring.
4. Then the per-frame path (mech2 animation SM, mech3, mech4 locomotion/ targeting) and the damage/weapon handlers.

Until then the ctor Fails cleanly at the frontier; everything below it (engine, app, network, mission, player, factory, jointed-mover base) runs real reconstructed code.

PHASE 4 DONE + PHASE 5 FRONTIER (2026-07-20)

The Mech constructor WORKS. Live boot: new Mech -> segment walk instantiates the full subsystem roster into the base Entity subsystemArray (dispatch on the real VDATA classIDs; unknown IDs -> base MechSubsystem so no NULL slots) -> caches sensor/gyro/sinkSource/hud -> mech links as viewpoint -> SetMappingSubsystem installs the MechControlsMapper in slot 0 -> mission startup. All structural.

Phase-5 frontier (the behavioral integration): boot now crashes (real NULL deref, not a staged Fail) in Simulation::GetAttributePointer reached via Simulation::PerformAndWatch (the per-frame execute + watcher update). Root: the reconstructed subsystems reuse the base Subsystem::AttributeIndex, so they publish NONE of their real attributes (Sensor RadarPercent/SelfTest/BadVoltage, Generator OutputVoltage, Emitter ChargeLevel, HUD/Torso/Gyro readouts, ...). The watcher/gauge binding + per-frame PerformAndWatch resolve those attribute IDs and hit a bad/NULL activeAttributeIndex path.

Phase-5 work, in order:

1. Per-subsystem AttributeIndex: define each subsystem's AttributePointers[] (ATTRIBUTE_ENTRY(class, Name, member)) + a real AttributeIndex chained to the parent, and pass it to that subsystem's DefaultData (instead of the base). The surviving CODE headers (SENSOR.HPP, PPC.HPP, GAUSS.HPP) list the attribute enums; the decomp AttributePointers[] tables give the rest.
2. Watcher / capability-chain / plug wiring in the Mech ctor (controllable/ heatable/weaponRoster/damageable) so PerformAndWatch has valid targets.
3. The per-frame simulation itself: mech2 (animation SM), mech3, mech4 (locomotion/targeting) -- ~9K lines, currently all staged Fail.
4. Rendering integration (the DPL renderer bridge) + playable verification.

Everything through the Mech ctor + viewpoint link runs real reconstructed code.

PHASE-5 CRASH LOCALIZED (2026-07-20)

Trace-confirmed: the Mech ctor FULLY constructs on the real pod TEST.EGG mech -- subsystemCount=33 weaponCount=7 (BT_MECH_LOG). The crash is AFTER construction, in BTL4Application::MakeViewpointEntity's "Load the control mappings" block (btl4app.cpp ~420): it SearchLists the ControlMappingsListResourceType resource and binds each streamed mapping to a subsystem attribute -- via an AttributeWatcher -> Simulation::GetAttributePointer(attributeID). The reconstructed subsystems publish NONE of their real attributes (they reuse the base Subsystem::AttributeIndex), so the streamed attribute IDs don't resolve.

Phase-5 step 1 = per-subsystem AttributeIndex, and it's a precision task:

• BT411 has the AttributePointers[] tables (mechsub 1, heat/HeatSink 12, powersub 4, Generator, sensor 3, torso 13, weapons, ...) -- but ATTRIBUTE_ENTRY(class,Name,member) needs each member NAMED + accessible (several of ours sit in reserved dynamics pads -- Gyroscope/Torso/HUD -- and must be broken out).
• The attribute-ID enums chain Simulation::NextAttributeID -> Entity -> Mover -> ... -> subsystem, and MUST match the 4.10 binary IDs (the streamed control mappings reference them by number). Then: watcher/plug/capability-chain wiring, then the mech2/3/4 per-frame sim (~9K lines, staged), then rendering. This is the behavioral half.