# GYRO.CPP — reconstruction notes

**Status: ctor + streaming RECONSTRUCTED; the per-frame simulation is the
in-flight increment (plan below). Donor: BT411 gyro.cpp (1106 lines, task
#56 BYTE-EXACT [T1] on the integrators and the damage fan-out).**

## Why this TU is the feel wave's cornerstone

The gyro owns the cockpit's physical feel: the eye TRANSLATION spring (the
steady eye offset + hit bounce, written to the 'jointeye' BallTranslation
joint that `siteeyepoint` rides) and the body ROTATION spring (the hull tip).
The 5.3.99 collision block's staged "gyro crunch" feed and the damage hub's
staged hit-bounce both land here.

## The transcription plan (all donor line refs gathered 2026-08-03)

1. **Members** (carve `dynamicsState[64]`): eyePosition/eyeVelocity/eyeForce/
   eyeWork (Vector3D), bodyOrientation/bodyVelocity/bodyForce/bodyWork,
   swayAngle/swayBias/swayVelocity/swayActive, placeRot/placePos,
   workMatrix[12], externalPitchPtr (the torso-twist Scalar*), eyeJointNode/
   mechJointNode (Joint*), damageResponse[5] {trans,pitchRoll,yaw,vibration},
   vibrationDirection (fixed up axis). Clamps are ALIASES: eyeClampUpper ==
   posSpring, eyeClampLower == negSpring; body likewise on the rotation pair.
2. **GyroscopeSimulation** (@004b275c): PowerWatcher::Simulation(dt); the
   impaired pick (HeatModelOff || electrical != Ready || heat == FailureHeat)
   selects percentageOnDestruction vs Normal + swayBias as the sway target;
   slew by rotationPerSecond*dt with no-overshoot clamps, band-clamp into
   [minAnimationNoise, maxAnimationNoise]; IntegrateEyeJoint; IntegrateBody.
   The performance ENDS there — WriteEyeJoint/WriteMechJoint are called from
   the MECH master perf tail (@0x4aaf74/83), i.e. our Simulate gait seam,
   with the death/leg-anim gates.
3. **IntegrateEyeJoint** (@004b2ec0, byte-exact): both spring terms use
   springConstant; damping OVERWRITES the force accumulator (carries into
   next frame by design); position += velocity with NO dt; per-axis clamp
   min-vs-posSpring then max-vs-negSpring.
4. **IntegrateBody** (@004b30ec): same shape, three quirks — spring force
   X/Z-CROSSED (k.x*d.z, k.y*d.y, k.z*d.x); damping componentwise uncrossed;
   orientation += velocity CROSSED again (x+=v.z, z+=v.x). Clamp vs the
   rotation spring pair.
5. **WriteEyeJoint** (@004b33e0): swayAngle onto the EyeJoint node — scalar
   channel scaled for hinge types <3, vector channel scaled for 4/5, write
   only past QuantiseEps. **WriteMechJoint** (@004b34ec): 'jointeye' type-5
   ONLY: SetTranslation(eyePosition) + SetRotation(EulerAngles from
   bodyOrientation), each QuantiseEps-gated.
6. **Damage hooks**: ApplyDamageImpulse (negate dir, *exageration, +=
   eyeForce); ApplyDamageTorque (same into bodyForce, then bodyForce.y = 0,
   then whole-vector NEGATE); ApplyVerticalImpulse (x-only kick, .y mirrors
   .x). **ApplyDamageResponse** (@004b2980, byte-exact): no-op on Collision
   or zero amount; direction = damageForce or random-horizontal when ~0;
   rotate into the yaw-only torso frame (externalPitchPtr) and re-normalize;
   per-type scale amount/multiplier[type]*response[type].{4 terms}
   (Explosive alone multiplies burstCount); clamp each at 1.3 UPPER only;
   then the four kicks: impulse(dir,trans), torque(dir,pitchRoll),
   vibration along vibrationDirection, vertical(yaw term).
7. **Wiring**: the damage hub's staged gyro feed (MECH.CPP
   TakeDamageMessageHandler step 1) calls ApplyDamageResponse; the crushable
   CRUNCH branch calls Torque(n,0.4)+Impulse(up,0.2) (already-shaped site);
   Simulate's gait seam calls WriteEyeJoint+WriteMechJoint on the master
   after the gait advances (death/leg gates per the binary tail).
8. **Family bridge**: Mech::DistributeCollisionDamage already references
   Gyroscope::ClassDerivations directly — no ODR bridge needed in our tree.

## Verification plan

BT_GYRO_LOG prints the joint writes + NaN sentinel; a live arena run with
enemy fire should show [gyro-dmg] fan-outs and 'jointeye' translation motion
on the wire (the cockpit eye rides it — visible as view bounce on hits).