Drift-free steering roll: SensorFusion.gravityRollRadians() (#314)

[petegordon]

Summary

Adds SensorFusion.gravityRollRadians() — roll derived from the accelerometer-anchored gravity vector instead of Euler-Z of the integrated orientation. This is the fix for the in-game symptom where a Steam Controller's steering "fuses to one side" and drifts (reported after playing RIDE TOGETHER / VERSUS with two Steam Controllers).

Why

• Extracting roll as Euler-Z of the full orientation mixes in YAW, and yaw is the one axis a 6-axis IMU can never anchor (no magnetometer) — so it drifts without bound and the roll wanders to one side.
• Reading roll straight from the gravity vector depends only on which way is currently down (measured directly by the accel), so it can't drift, is naturally bounded (no ±180° wrap), and never touches the gyro — making it immune to gyro bias/sign errors too.

The half-built feature this completes

The game (input-manager.js, #314) already has a 'gravity' roll mode that calls fusion.gravityRollRadians() — but that method never existed in controller-core, so the game silently fell back to the drift-prone Euler-Z path. Both modes were effectively the drifting one. This lands the missing method so the game's default actually works.

Changes

• gravity-roll.js: pure rollFromGravity(gx, gy) = atan2(gx, -gy), THREE-free (mirrors yaw-return.js so the dependency-free core test job stays green).
• SensorFusion.gravityRollRadians() delegates to it over _gravityVec.
• Sign matches the -EulerZ convention the game already steers by → drop-in, no steering inversion; it only removes the drift.

Tests (144 core pass)

gravity-roll.test.js locks the gameplay-critical invariants with plain-quaternion math (no three):

• pure roll φ → -φ (matches -EulerZ);
• yaw-immunity — roll identical at every heading, including 5 full turns of accumulated yaw drift;
• pitch does not leak into roll;
• left/right sign symmetry.

Rollout

After merge → release core-v0.4.1 → re-sync the game (PR petegordon/Tandemonium#361) → in-game feel test.

🤖 Generated with Claude Code

[github-actions]

🔎 PR #109 preview — torn down

This PR is closed; its web preview and desktop prerelease have been removed.