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.

The slot map (LoadLocomotionClips) — and why the enum is not it

Recovered from the clip loader. animationClips[slot] semantics, which do NOT match the name-table enum, plus what each measured constant is taken from. Suffixes are the 3-char codes the loader appends to the model's animation prefix:

slot	clip	meaning	measures
5	swr	stand → walk R	standSpeed = final-keyframe stride
6 / 7	wwr / wwl	the forward walk CYCLE	walkStrideLength = (s6+s7)/(d6+d7)
8 / 9	wsr / wsl	walk → stand
10 / 11	wrr / wrl	walk → run	reverseSpeedMax from slot 10
12 / 13	rrr / rrl	the run CYCLE	reverseStrideLength = (s12+s13)/(d12+d13)
14 / 15	rwr / rwl	run → walk
16 / 17	sbr / sbl	stand → back (reverse entry)	gimpSpeedMax from slot 16
18 / 19	bbr / bbl	the reverse CYCLE	gimpStrideLength = −(s+s)/(d+d)
20 / 21	bsr / bsl	back → stand (reverse exit)
22 / 23	wgl / wgr	walk → limp	gimpLeft/RightSpeedMax
24 / 25	ggr / ggl	the limp CYCLE	gimpLeft/RightStrideLength
26 / 27	gsl / gsr	limp → stand
0x20	bmp	bump / crash stagger	—

Three things fall out of this table that are easy to get wrong:

The gimp*-named members are the REVERSE figures, not the limp ones. The names are historical. gimpSpeedMax / gimpStrideLength are measured from sbr and bbr/bbl — the reverse gait. The actual limp has its own gimpLeft* / gimpRight* pair. This is the same trap as the states-16–19 misreading recorded above, from the same bad naming.

gimpStrideLength is negated at the point of measurement — that is where the negative sign the transition machines fold comes from, not from the authored data being odd.

The limp clips are OPTIONAL. The loader probes for wgl; if the model lacks it, hasGimpClips stays 0 and slots 22–27 are never filled. So a limping mech on a model without limp clips must fall through to the normal machine — which is, conveniently, exactly what the deferred gimp branch will have to check.

Corrected after the fact

animationClips was first sized [AnimationCount] (0x1d) from the enum. That is wrong — slot 0x20 is the bump clip, so the array is [AnimationSlotCount] (0x21) and Set*Animation's Verify bounds against that. Sizing a real array off a name table that stops earlier is the sort of thing that reads fine and corrupts the object next door; caught by reading the loader, not by the compiler.

Still to source

Filling the array needs Mech::ResolveAnimationClip (@004a7f50) and Mech::MeasureClipStride (@004a8054) plus LoadLocomotionClips (@004a80d4) and LoadLocomotionClipsExt (@004a86c8, the 4-char-code variant). Note the manifest attributes all four to mech2.cpp while BT411 files them under mech3 — the manifest's attribution comes from the binary's own file tagging, so they belong here.