arcattackandClaude Fable 5
47aede3094
User report: the shadow broke MID-SESSION -- suddenly solid opaque black and buried on any slope. The session log pinned the trigger: pressing V. The view toggle (SetViewInside) RELOADS every segment mesh through the object loader and swaps them into the render tree -- including blh_tshd.bgf -- and the reload path never called SetIsShadow(1) (only the original tree-build call site tagged it). Untagged, the entire shadow pipeline disengages: no translucent TFACTOR state block (solid black), no depth bias (buried), wrong pass. The damage-swap reloads had the same hole. Fix: tag *tshd* filenames in LoadObjectBGF itself, next to the existing all-shadow-material detector (which misses the mech proxy -- plain black material, not shadow_mtl). Every load path -- build, damage swap, view toggle -- now yields a tagged object; the drawOps alphaTest routing reads the flag downstream. User-verified live: the shadow survives repeated V toggles, translucent and slope-correct. This also likely explains the RECURRING "shadow vanishes on inclines" reports: any V toggle silently broke it; every relaunch "fixed" it. KB (locomotion.md): loader-level tag recorded as co-dependent part 5 of the shadow arrangement; the vanish-diagnostic note now lists all three causes (reload untag / gait desync / genuine burial) with check-first guidance. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
123 lines
9.4 KiB
Markdown
123 lines
9.4 KiB
Markdown
---
|
||
id: locomotion
|
||
title: "Locomotion — gait, the ground model, collision, shadow"
|
||
status: established
|
||
source_sections: "PROGRESS_LOG.md §7, §10 (gait/ground/collision/shadow); docs/P3_LOCOMOTION.md"
|
||
related_topics: [asset-formats, decomp-reference, reconstruction-gotchas, combat-damage, rendering]
|
||
key_terms: [RootTranslation, ground-model, SequenceController, MechControlsMapper, SLD, joint]
|
||
open_questions:
|
||
- "Authentic per-mech turn-rate constant (currently bring-up constant)"
|
||
- "Body-callback gimp handlers (states 16-19); airborne callbacks"
|
||
---
|
||
|
||
# Locomotion
|
||
|
||
Walking, the gait controller, the ground/collision model, and the shadow. All DEFAULT-ON now
|
||
(`BT_GAIT_CUTOVER`, `BT_GAIT_SM`, `BT_COLLISION`, `BT_REAL_CONTROLS` — set `=0` to fall back). Full
|
||
detail: `docs/P3_LOCOMOTION.md` + `docs/PROGRESS_LOG.md §7, §10`.
|
||
|
||
## Walk speed is animation-driven (not physics)
|
||
Each `.ANI` has a `[RootTranslation]` where **`.z` = forward root SPEED** (world units/s). The
|
||
engine `AnimationInstance::Animate(dt, move_joints)` integrates `movement += Δt·rootTrans.z` and
|
||
moves the body that far → feet plant by construction (no stride constant; k=1). Idle anims have
|
||
z=0. The `.MOD` physics governed thrust VEHICLES, NOT walk gait. [T1]
|
||
|
||
## The two-channel gait (real controls)
|
||
The BT `SequenceController` (`seqctl.cpp`, from `SelectSequence@004277a8`+`Advance@0042790c`) drives
|
||
locomotion. Under `BT_REAL_CONTROLS` two channels run — **roles corrected 2026-07-09 (task #49) from
|
||
raw disasm** (both Advance fns had NO static decomp caller; found by byte-scanning for `e8` calls):
|
||
- **LEG channel = the LOCAL sim.** The master perf (the `0x4a9b5c` gap region) calls
|
||
`AdvanceLegAnimation` @0x4aa399 (airborne @0x4aa388) and stores `-dist/dt` into **localVelocity
|
||
(+0x1cc)** — the leg drives the local mech's TRAVEL and, advancing LAST (mj=1), the DISPLAYED pose.
|
||
It reads the LIVE `speedDemand` and owns trn/turn-in-place + the early-stand wind-down guard. [T1]
|
||
- **BODY channel = the replication PROJECTOR.** `IntegrateMotion` (0x4ab1c8; body advance @0x4ab312,
|
||
from `FUN_004ab430`, the projected-origin/dead-reckon updater) stores `-dist/dt` into
|
||
**projectedVelocity (+0x2a0)** — the dead-reckoning feed for update records. Its phase drift is
|
||
locally INVISIBLE in the binary. (The recon does not yet wire this store — follow-up.) [T1]
|
||
**v5 (current): display == travel BY CONSTRUCTION through the LEG** (body advances first, leg last).
|
||
History: v3 (travel=leg, display=body) foot-slipped — two channels, different consumers; v4 unified
|
||
BOTH on the body (mis-reading 0x4ab430 as the travel source) — feet planted, but whenever the two
|
||
state machines phase-split, the out-of-phase LEG pose showed through on frames the body didn't write
|
||
(Standing/wind-down) = the RECURRING "legs stutter / lose sync" report. The split mechanism [T2,
|
||
reproduced via `BT_FORCE_OSC` + `BT_FORCE_TURN` + `BT_SYNC_LOG`]: (a) SEED — the bring-up trn trigger
|
||
arms only the leg (authentic trn dispatcher still unlocated), so the walk re-entry lands 1 frame
|
||
apart; (b) AMPLIFIER — with offset clips the end-of-clip callbacks fire on different frames, so a
|
||
demand change landing between them picks DIFFERENT next states (one winds down, one keeps walking)
|
||
→ opposite-phase churn. Under v5 both effects still exist but only skew the projection channel. [T2]
|
||
The gait STATE MACHINE (`AdvanceBodyAnimation`, mech2.cpp) slews `bodyCycleSpeed` toward the demand
|
||
through walk/run caps (`LoadLocomotionClips`, mech3.cpp:326 — measures `walkStride`/`standSpeed` via
|
||
`legAnimation.SelectSequence`). Transition callbacks (`Mech::BodyClipFinished @0x4a6d8c`,
|
||
`LegClipFinished @0x4a6928` — PE-parsed jump tables) alternate walk 6↔7 / run 12↔13 + walk→run. [T2]
|
||
⚠ **Aliasing bug class (namedClip):** `namedClip[]`@0x5e0 == `animationClips[]`@0x5cc+0x14 (ONE array);
|
||
`gimpBaseClip`@0x64c == `animationClips[0x20]`; `bodyAnimationState`@0x728 == `bodyStateAlarm.level`.
|
||
Declared-separate members don't see each other's writes — alias them.
|
||
|
||
## The AUTHENTIC 1995 ground model (default-on, `BT_GROUND_REAL`)
|
||
Decoded by the 10-agent `ground-model-decode` workflow (binary `FUN_004a9b5c` = the master perf).
|
||
**NO GRAVITY anywhere** — accelerations zeroed every frame. Vertical position = an ABSOLUTE per-frame
|
||
ground SNAP:
|
||
1. ctor lifts `collisionTemplate->minY` by 5% of volume X-width (the probe height + wall-vs-floor separation).
|
||
2. per frame `MoveCollisionVolume()` re-finds the containing node in the zone's **BoundingBoxTree**
|
||
(BOXTREE.cpp — NOT a heightfield).
|
||
3. probe `q = origin + (0, lift, 0)` → `FindBoundingBoxUnder(q, &h)` (h = distance down to the highest
|
||
solid top; −1 = miss).
|
||
4. snap gate `h > 1e-4`: `origin.y -= (h − lift)` ⇒ y = surfaceY exactly. **MISS ⇒ NOTHING** (y holds,
|
||
no runaway). Up-slope bounded by the lift window (implicit step allowance); walk-offs drop instantly.
|
||
5. `GetCurrentCollisions` → `ProcessCollisionList` → `Mech::ProcessCollision` (@0x4abb40, vtbl+0x3c):
|
||
BoxedSolid resolver → StaticBounce → owner classification. Crushable icon (flags&0x8000) = damage
|
||
0.00123f sentinel = move stands; damage>0 = **FULL FRAME REJECTION** (walls block, never slide);
|
||
impactVel²>40 = crash-anim (SetLegAnimation(0x20)). [T2]
|
||
KEY: `FindSmallestNodeContainingColumn`/`FindBoundingBoxUnder` (`FUN_0040e36c`/`0040e5f0`, BOXTREE.CPP)
|
||
are ALIVE in the 2007 engine — the "heightfield" labels were wrong (caused two reverted attempts). A
|
||
master mech needs a **CollisionAssistant** (GetCurrentCollisions iterates it unchecked). BT solids
|
||
ship ZERO tiles (h never negative). [T2]
|
||
|
||
## Knockdown / crash + the desync/stutter fixes
|
||
Wall impacts iv²>40 (~6.3 u/s) bind the `bmp` stagger clip. Two documented bug fixes: (a) the
|
||
knockdown must stagger BOTH channels (`SetBodyAnimation(0x20)` + `SetLegAnimation(0x20)`) or display
|
||
+ travel split permanently (foot-slip); (b) a contact-hysteresis gate (0.4 s `gBlockCooldown`)
|
||
stops the knockdown re-firing on sustained/glancing contact. `localVelocity` is zeroed while crashed
|
||
(spec-faithful) so a knocked mech can't keep advancing. [T2]
|
||
|
||
## Controls (`BT_REAL_CONTROLS`, default-on)
|
||
`MechControlsMapper` (mechmppr.cpp @004afbe0; btl4mppr.cpp mappers) interprets input → `speedDemand`
|
||
/ `turnDemand`. ⚠ **WndProc NEVER receives WM_KEYUP** (the engine's per-frame reader `GetMessage`s
|
||
them out) → poll `GetAsyncKeyState` per frame, gated on foreground. Virtual controls: W/S sweep a
|
||
persistent throttle LEVER with a zero detent; A/D a momentary auto-centering stick. [T2]
|
||
|
||
## Shadow (default-on, `BT_SHADOW_TILT`)
|
||
BT 4.10's shadow is the `*_tshd.bgf` proxy, posed by `jointshadow` (terrain tilt — the SKL's own
|
||
contract: "apply terrain angle to pitch and roll") + `jointtshadow` (torso twist). The working 2026-07-09
|
||
arrangement (user-verified live: feet layer over it, opaque, survives inclines/declines) has FOUR
|
||
co-dependent parts — change one, re-check the others:
|
||
1. **TILT** (mech.cpp `UpdateShadowJoint`): quad up aligned to the surface normal via an orthonormal
|
||
basis fed to the ENGINE's own LinearMatrix→EulerAngles conversion — hand-derived Euler signs are
|
||
exactly how two prior tilt attempts "dug into the hillside"/vanished. ~35° cliff-guard cap.
|
||
2. **SAMPLER** (mech4.cpp): gradient from the collision probes PLUS `BTVisualGroundLift` per probe
|
||
(the quad hugs the VISIBLE terrain, whose lift varies across a slope); world→local by the TRUE yaw
|
||
from `localToWorld` (NOT the `gDriveHeading` scalar mirror — the task-#48 drift bug class).
|
||
`BT_SHADOW_LOG` traces the normals.
|
||
3. **DRAW ORDER** (`PASS_SHADOW`, l4d3d.h/L4VIDRND/L4VIDEO): shadows draw between the STATIC terrain
|
||
and the DYNAMIC opaque bodies (classic decal order), so the mech z-passes over the shadow — the
|
||
bias can never paint the shadow OVER the feet, structurally.
|
||
4. **BIAS pairing** (L4D3D.cpp): tilt on (default) → decal epsilon −0.0008; `BT_SHADOW_TILT=0`
|
||
(flat A/B fallback) → the old −0.004 it needs to survive slope burial. `BT_SHADOW_BIAS` overrides.
|
||
5. **LOADER-LEVEL TAG** (L4D3D.cpp `LoadObjectBGF`): `*tshd*` filenames get `SetIsShadow(1)` in the
|
||
LOADER, not at call sites. The V VIEW TOGGLE (`SetViewInside`) and the damage swaps RELOAD segment
|
||
meshes; an untagged reload disengages the whole pipeline — solid opaque black, no bias, buried on
|
||
any slope ("shadow broke mid-session after pressing V", user-confirmed fixed). The all-shadow-
|
||
material detector misses the mech proxy (plain black material, not shadow_mtl). [T2]
|
||
Polar maps have STUB `*_tshd` (shadow authored-off on snow). The visual-ground conform (`btvisgnd.cpp`)
|
||
stays render-only (never touches localOrigin). [T2]
|
||
⚠ **"Shadow vanishes on inclines" now has THREE confirmed/suspected causes — diagnose before fixing:**
|
||
(a) the V-toggle/reload UNTAG above (solid black + buried; broke mid-session; the likeliest cause of
|
||
the recurring reports — a relaunch always "fixed" it because the fresh build re-tagged); (b) gait
|
||
desync popping the displayed root pose past the bias margin (the first 2026-07-09 recurrence co-
|
||
resolved with gait v5, no shadow code changed — though (a) may have contributed) [T2 obs; mechanism
|
||
T4]; (c) genuine slope burial when the quad is flat/mis-tilted (the depth-bias margin is finite).
|
||
Check `[shadowobj]` tag lines and `[sync]`/`BT_SYNC_LOG` before touching bias/tilt.
|
||
|
||
## Key Relationships
|
||
- Detail: `docs/P3_LOCOMOTION.md`. Uses: [[asset-formats]] (SKL/ANI), [[decomp-reference]] (offsets).
|
||
- Feeds: [[combat-damage]] (collision→damage), [[rendering]] (shadow/visual-conform).
|