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

MECH2.CPP — reconstruction notes

Status: the TRANSITION MACHINE reconstructed (compile-verified 2026-08-02, BT 51/51, links clean). The four per-frame Advance* entry points and the two Gimp*ClipFinished machines are NOT yet written — see "What is deferred".

mech2.cpp is the mech's gait: which walk clip is playing, when it changes, and to what. It sits between the locomotion demand and the clip player:

Mech::Simulate                      speed/turn demand
  -> Mech::AdvanceLegAnimation      DEFERRED -- the per-frame entry point
    -> SequenceController::Advance  [[SEQCTL]] -- keyframes -> joint writes
      -> Mech::LegClipFinished      THIS FILE -- end of clip, pick the next
        -> Mech::LegTransition      THIS FILE -- bind it, spend the leftover

The two channels, and why they are near-duplicates

A mech runs two parallel clip channels over the same state machine and the same clips. The only difference is which speed the transitions consult:

	reads	why
LEG (legAnimation, legStateAlarm)	the LIVE mapper GetSpeedDemand()	responds to the stick immediately
BODY (bodyAnimation, bodyStateAlarm)	bodyTargetSpeed, a snapshot	lets a dead-reckoned or networked mech walk with no mapper of its own

That is why LegClipFinished and BodyClipFinished are near-twins rather than one shared routine — it is how the binary has it (two separate jump tables, @0x4a69aa and @0x4a6e0a). Keep them twins. Where the two tables agree, a divergence in this file is a bug, and that mutual check is worth more than the duplication costs.

Every clip is one stride

Which is why every state is handed. A walk is Right, Left, Right… and each entry to and exit from a cycle has its own handed pair so the mech always leaves a cycle on the correct foot. The MechAnimationState enum (now in MECH's header) is verbatim from the 0x3c-stride name table at .data:0050cfe8 — the table the "Unsupported mech animation" assert indexes — so the names and their order are the original's, not inferred from behaviour.

The commit test, in both machines

Every walk handler has three exits, and the two that leave the cycle test both the demand and the current cycle speed slewed by one carryover:

if (demand < standSpeed && (cycle - cycleRate * carryover) < standSpeed)
    -> walk-to-stand
if (demand > walkStrideLength && (cycle + cycleRate * carryover) > walkStrideLength)
    -> toward the run cycle
else
    -> the next stride, other foot

Requiring both means a momentary flick of the stick cannot yank the mech out of a stride it has already committed to. Dropping either half of those conjunctions would give a mech that stutters between gaits on noisy input.

Two things that read wrong and are not

gimpStrideLength is authored NEGATIVE. The cycle time computed from it comes out negative and is folded positive before being spent (binary @0x4a6c6e / @0x4a6d3d). The fold is not defensive coding — remove it and the limp plays backwards.

States 16–19 on the body channel are the REVERSE gait, not a limp, despite sharing the gimpSpeedMax / gimpCycleRate caps. While the demand stays below the cap the cycle alternates 0x12 ↔ 0x13; a forward demand exits through the back-to-stand pair. BT411 records having read these as "gimp, not decoded, fall back to standing" twice, which makes the body loop stand → reverse-entry forever — a slow reverse with a wrong-footed exit. The reading here is by structural symmetry with the leg table, where every previously-decoded body case mirrors its leg twin.

What is deferred

Six of the twelve functions the manifest attributes to this TU:

	why it is not here yet
AdvanceLegAnimation @004a5028	the per-frame entry points — the next increment
AdvanceBodyAnimation @004a5678
AdvanceBodyAnimationGimp @004a5bf8	the airborne/jump-jet flavours
AdvanceLegAnimationGimp @004a71f4
GimpBodyClipFinished @004a6344	the limp transition machines, entered from the
GimpLegClipFinished @004a7970	top of the two *ClipFinished above on gimp level 3/4

The gimp-level branch at the top of both *ClipFinished is therefore also absent: a limping mech currently runs the normal machine. That branch needs a TU-safe read of the graphic alarm level (BT411 routes it through a mechdmg.cpp bridge to avoid an AlarmIndicator ODR split) — worth reproducing carefully rather than reaching for the alarm directly.

Nothing calls any of this yet. The Advance* functions are the entry points and they are the deferred half, so no gait state is ever selected and a run behaves exactly as before. Same honest caveat as SEQCTL: this is a blocker removed, not a behaviour delivered.

Header changes

MECH.HPP gained the enum, the six method declarations, and the channel state: legStateAlarm / bodyStateAlarm (AlarmIndicator — read the state with GetLevel, the binary's mech+0x3b0 / +0x728 are mirrors of the alarm level, so no separate int is kept), legCycleSpeed, bodyCycleSpeed, forwardCycleRate, gimpCycleRate, standSpeed, gimpSpeedMax, gimpStrideLength, globalTimeScale, and animationClips[AnimationCount]. 41 ints carved from reservedState, 191 → 150.

walkStrideLength, reverseStrideLength, reverseSpeedMax and bodyTargetSpeed were already present from the Phase 5.3 locomotion work and are reused, not duplicated.

Still unsourced: animationClips[]. The array is declared but nothing fills it. The clip handles come from the mech's model resource, and resolving them is a prerequisite for the Advance* increment — SetLegAnimation would otherwise hand SelectSequence a garbage ID. SelectSequence tolerates a missing resource (empty controller, inert playback), so this fails soft rather than crashing, but it must be wired before the gait can do anything.