Motorcycle Module

Turns a standard VehicleController into a motorcycle with lean dynamics and active balance control. Steering sets a target lean angle and a PID controller applies the roll torque to hold it; the lean produces a grip-limited cornering force. This is an active "point-and-lean" model - it does not simulate gyroscopic precession, trail/rake, or true counter-steering.

Setup Requirements

• Vehicle must have exactly 2 wheels (front and rear)
• Wheels configured in order: [0] = front, [1] = rear
• No differentials needed - transmission outputs directly to rear wheel
• Use narrow wheel colliders for accurate lean behavior
• Vehicle root scale must be [1,1,1]

Key Features

Physics-Based Lean Control Lean is implemented through a PID controller that applies torque to the rigidbody for realistic balance. The PID controller prevents frustrating tip-overs while maintaining authentic motorcycle physics.

Grip-Limited Cornering Lean produces a lateral cornering force capped at the tire's grip (μ). The maximum lean angle is also capped at atan(μ) at runtime, so cornering is surface-dependent - shallow lean on ice, deep lean on tarmac - and the bike runs wide / washes out at the limit instead of being on rails. Disable gripLimitedCamberThrust for the legacy arcade feel.

Slip Compensation Prevents highsiding during slides by automatically leaning into the slide direction based on rear wheel lateral slip.

Speed-Dependent Behavior Both maximum lean angle and lean transition rate vary with speed.

PID Controller Tuning

The lean control requires tuning for each vehicle. All three gains are multiplied by leanPIDCoefficient which acts as a master stability control:

Property	Description
Gain Proportional	Primary response to lean angle error (default: 5). Too low (0-2): Slow lean, may fall. Optimal (2-6): Responsive and stable. Too high (6+): Twitchy, unrealistic
Gain Integral	Eliminates steady-state error to reach target lean (default: 4). Too low (0-3): Doesn't fully reach target. Optimal (3-8): Accurate targeting. Too high (8+): Aggressive, instability
Gain Derivative	Dampens oscillations during lean transitions (default: 1). Too low (0-0.5): May oscillate. Optimal (0.5-2): Smooth transitions. Too high (2+): Sluggish
Lean PID Coefficient	Global multiplier for all gains (default: 22). 10-30: Light assistance, realistic. 40-60: Balanced. 70-100: Strong assistance, arcade-like
Max Lean Torque	Limits PID authority to prevent unrealistic recovery (default: 4000 Nm). Light bikes (150kg): 3000-5000 Nm, Medium (250kg): 4000-8000 Nm, Heavy (400kg+): 8000-12000 Nm
Integral Limit Fraction	Caps integral windup at this fraction of Max Lean Torque (default: 0.3). Lower removes rubber-band lag on quick lean reversals

Main Settings

Property	Description
Grip Limited Camber Thrust	When on (default), lean cornering force is tan(lean) capped at tire μ and lean is capped at atan(μ), so cornering saturates realistically. Off = legacy arcade sin(lean) on-rails injection
Max Lean Angle	AnimationCurve defining maximum lean angle (degrees) by speed (m/s). Default: 43 deg low speed easing to 40 deg. Runtime-capped by atan(μ) when grip-limited. Street bikes: 35-45 deg, Sport bikes: 45-55 deg, Racing bikes: 55-65 deg
Self Right Strength	Optional torque that picks the bike back up after it falls past the balance threshold. 0 (default) = stays down (realistic), higher = arcade recovery
Lean Angle Max Delta	AnimationCurve defining how quickly lean can change (degrees/second) by speed (m/s). Default: 220 deg/s at 0 m/s, 100 deg/s at 90 m/s
Lean Angle Slip Coefficient	Additional lean based on rear wheel lateral slip (default: -30). Negative values lean into slides to prevent highsiding. -40 to -20: Strong, -30: Balanced, -15 to 0: Minimal
Slip Compensation Steering Threshold	Minimum steering input before slip compensation activates (default: 0.05). Prevents drift corrections during straight-line riding
Slip Compensation Dead Zone	Minimum slip value before compensation applies (default: 0.03). Filters numerical noise from the friction system
Use Hit Normal As Up	Calculate lean relative to ground surface instead of world up. Enable for banked tracks, loops, or sloped terrain

Animation

Property	Description
Handlebars Transform	Automatically rotates to match front wheel steering angle. Assign the handlebar/fork GameObject with proper pivot point
Swingarm Transform	Automatically rotates to track rear wheel position for suspension animation. Assign the swingarm GameObject with pivot at rotation axis

State Properties

Property	Description
isGrounded	Both wheels touching ground
FrontWheelGrounded	Front wheel contact status
RearWheelGrounded	Rear wheel contact status
IsWheelie	Only rear wheel grounded (front lifted)
IsStoppie	Only front wheel grounded (rear lifted)

Use these properties to trigger effects, adjust controls, or implement stunt systems.