From 44f79fcbfeb66778bba89243dad8f5541e17ddba Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Mon, 3 Aug 2026 16:01:02 -0500
Subject: [PATCH] BT410 5.3.108: gyro increment plan captured -- the feel
 wave's cornerstone, decoded and ready to transcribe

All donor evidence gathered (task #56 byte-exact integrators, the damage
fan-out, the master-perf joint-write split); the sidecar carries the full
8-step transcription plan so the increment is deterministic to resume.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 restoration/source410/BT/GYRO.NOTES.md | 67 ++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 restoration/source410/BT/GYRO.NOTES.md

diff --git a/restoration/source410/BT/GYRO.NOTES.md b/restoration/source410/BT/GYRO.NOTES.md
new file mode 100644
index 00000000..14b9f2cb
--- /dev/null
+++ b/restoration/source410/BT/GYRO.NOTES.md
@@ -0,0 +1,67 @@
+# 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).