Wheelie Physics

Street Riders uses a continuous force-based wheelie system unlike scripted animation wheelies found in other mods. Every wheelie is physically simulated in real-time; the bike lifts, balances, and settles based on forces, speeds, and angles.

---

How It Works

A smooth upward force is applied to the bike's front end every frame. The force is dampened by angular velocity, preventing the bike from overshooting and oscillating. Gravity provides natural resistance, and the system continuously adjusts to maintain the target angle.

---

Pitch Control Phases

The wheelie is divided into four phases based on the current pitch angle relative to TargetPitch:

0° ──────────────────────────────────── MaxPitch
    [Full Lift] [Fade Out]  [Coast]  [Correction]
    0%─50%      50%─100%    Target   Above Max

Phase	Range	Behaviour
Full Lift	0% to 50% of TargetPitch	Full lift force applied, dampened by rise speed
Fade Out	50% to TargetPitch	Force progressively fades out with velocity damping: smooths into the target
Coast	TargetPitch to MaxPitch	No force applied: gravity settles naturally at the target
Correction	Above MaxPitch	Gentle reverse force pushes the front wheel back down to prevent flipping

---

Per-Bike Tuning

Each bike model can have its own wheelie profile using [Bike_XXX] sections. The bike must be listed in BikeOverrides in [General].

Example: Sanchez (aggressive dirt bike)

[Bike_SANCHEZ2]
LiftForce = 0.32
TargetPitch = 50.0
MaxPitch = 55.0

Example: BF400 (moderate sport/dirt)

[Bike_BF400]
LiftForce = 0.15
TargetPitch = 45.0
MaxPitch = 50.0

Only the settings you include are overridden; everything else falls back to [DefaultWheelie].

---

Tuning Guide

Issue	Fix
Bike lifts too hard	Lower LiftForce
Bike doesn't lift	Raise LiftForce
Wheelie angle too high	Lower TargetPitch
Bike flips over	Lower MaxPitch
Wheelie still bouncy	Lower LiftForce and raise TorqueOffset

---

WheelieExcludedModels

Certain two-wheeled vehicles never attempt wheelies:

WheelieExcludedModels = BMX, CRUISER, TRIBIKE, TRIBIKE2, TRIBIKE3, SCORCHER, POLICEB

Add any bike model to this comma-separated list to exclude it.

---

Natural Rider Support

When ApplyToNaturalRiders = true, the wheelie AI also applies to NPC bikers already spawned in traffic. The mod scans for nearby bikers within NaturalRiderScanRadius and gives them wheelie behaviour.

ApplyToNaturalRiders = false
NaturalRiderScanRadius = 200.0

---

Remount System

When a rider falls off their bike (from a crash or failed wheelie), the remount system kicks in:

1. Rider detects they are off the bike and not in a vehicle.
2. A cooldown (RemountTaskCooldown) prevents rapid re-triggering.
3. The rider walks to the bike if within RemountEnterDistance and RemountMaxDistance.
4. If the rider cannot reach the bike within RemountTimeout, they stop trying.
5. After RemountForceTimeout milliseconds, the rider is force-warped onto the bike (0 = disabled).

---

Police Interaction

Police can chase riders who are doing wheelies through traffic:

Setting	Default	Description
AllowPoliceArrest	false	Enable police pursuit of riders
PolicePursuitRadius	100.0	Police lock-on range (meters)
PolicePursuitMinDuration	15000	Minimum pursuit duration before giving up (ms)

---

Configuration Reference

Setting	Default	Phase
LiftForce	0.18	Core: upward force per frame
TorqueOffset	1.2	Core: lever arm (higher = more rotation)
PulseIntervalMs	0	Core: 0 = continuous, >0 = pulsed
MinSpeed	12.0	Core: minimum speed to attempt (m/s)
TargetPitch	40.0	Pitch: target angle (degrees)
MaxPitch	43.0	Pitch: emergency correction (degrees)
AttemptDurationMin	3000	Timing: minimum attempt (ms)
AttemptDurationMax	5000	Timing: maximum attempt (ms)
SustainDurationMin	5000	Timing: minimum sustain (ms)
SustainDurationMax	20000	Timing: maximum sustain (ms)
AttemptDelayMin	1000	Timing: delay between attempts (ms)
AttemptDelayMax	5000	Timing: delay between attempts (ms)
AttemptsMin	1	Timing: attempts per ride cycle
AttemptsMax	4	Timing: attempts per ride cycle
RaycastDistance	10.0	Safety: obstacle detection range (m)
MaxSteeringAngle	12.0	Safety: max steering during wheelie (°)
BrakeThreshold	0.5	Safety: brake cancels wheelie
DriveSpeed	20.0	Driving: cruise speed (m/s)
MaxEntitySpeed	25.0	Driving: hard speed cap (m/s)
DriveAbility	1.0	Driving: AI skill (0.0–1.0)
DriveAggressiveness	1.0	Driving: AI aggressiveness
DrivingFlags	802877	Driving: AI behaviour bitfield
BlockNonTempEvents	true	Ped: block interrupting events