Motorcycle Module

Transforms a standard VehicleController into a realistic motorcycle with counter-steering, lean dynamics, and active balance control.

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.

Counter-Steering Simulates realistic counter-steering behavior at higher speeds where brief opposite steering initiates lean.

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, simulating gyroscopic effects and weight transfer.

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: 4). 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: 5). 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: 50). 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: 7000 Nm). Light bikes (150kg): 3000-5000 Nm, Medium (250kg): 5000-8000 Nm, Heavy (400kg+): 8000-12000 Nm

Main Settings

Property	Description
Max Lean Angle	AnimationCurve defining maximum lean angle (degrees) by speed (m/s). Default: 33 degrees. Street bikes: 35-45 deg, Sport bikes: 45-55 deg, Racing bikes: 55-65 deg
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.