b3dAddVehicleDifferential

Adds a differential linking two wheels with specified gear ratio. Takes vehicleHandle (vehicle created with b3dCreateVehicle), leftWheelIndex (wheel index from b3dAddVehicleWheel, typically left side wheel), rightWheelIndex (wheel index from b3dAddVehicleWheel, typically right side wheel on same axle), differentialRatio (gear ratio determining torque multiplication and top speed trade-off). Returns nothing. Creates Jolt differential connecting left and right wheels, distributes engine torque between them, and allows different wheel speeds during turns.

This function adds differential. Differential parameters: vehicleHandle (vehicle handle from b3dCreateVehicle), leftWheelIndex (0-based wheel index from b3dAddVehicleWheel, typically left wheel of axle, e.g. 0 for front-left), rightWheelIndex (0-based wheel index from b3dAddVehicleWheel, typically right wheel of same axle, e.g. 1 for front-right), differentialRatio (gear ratio for torque multiplication, higher ratio = more torque/less speed, lower ratio = less torque/more speed). Differential purpose: distributes engine torque to left and right wheels (both wheels powered together, not independently), allows differential wheel speeds (outer wheel spins faster than inner wheel in turns, prevents tire scrubbing), multiplies engine torque by differentialRatio (transmission gear ratio, affects acceleration vs top speed trade-off).

Differential ratio physics: differentialRatio is gear ratio from engine to wheels (ratio = 3.0 means engine shaft rotates 3 times for each wheel rotation), higher ratio = more torque at wheels but lower top speed (3.0-5.0 typical for low gears, better acceleration, mechanical advantage), lower ratio = less torque but higher top speed (1.5-2.5 typical for high gears, efficient cruising, less multiplication). Ratio and torque: wheel torque = engine torque * clutch strength * differential ratio (if engine produces 400 Nm and differentialRatio = 3.0, wheels receive ≈ 1200 Nm torque, higher ratio = better acceleration from standstill). Ratio and speed: top speed inversely proportional to ratio (high ratio limits top speed, engine hits maxRPM at lower vehicle speed, low ratio enables higher top speed, engine RPM spread over wider speed range).

Typical differential configurations: front-wheel drive car (1 differential linking front-left and front-right wheels, rear wheels unpowered/idle), rear-wheel drive car (1 differential linking rear-left and rear-right wheels, front wheels unpowered/idle for steering only), all-wheel drive car (2 differentials, 1 for front axle, 1 for rear axle, all 4 wheels powered), tandem axle truck (multiple differentials for multiple driven axles, heavy-duty power distribution). Front vs rear differentials: front differential (lower ratio 1.5-2.5 for fuel efficiency, front wheels both steering and drive), rear differential (higher ratio 2.5-4.0 for acceleration, rear wheels drive only, no steering).

Use cases: (1) Standard car (front differential ratio 1.5-2.5, rear differential ratio 2.5-3.5 for balanced performance), (2) Sports car (higher ratios 3.0-4.5 for quick acceleration), (3) Economy car (lower ratios 2.0-3.0 for fuel efficiency and higher top speed), (4) Truck (high ratios 4.0-6.0 for hauling power), (5) Racing car (tuned ratios 2.5-4.0 balancing acceleration and top speed for specific track). Common patterns: balanced car (front ratio 2.0, rear ratio 3.0), quick acceleration (front ratio 2.5, rear ratio 4.0), high top speed (front ratio 1.5, rear ratio 2.5).

Wheel indexing: leftWheelIndex and rightWheelIndex from b3dAddVehicleWheel return values (wheel indices 0-based, first wheel added = 0, second = 1, etc), typical 4-wheel car (wheel 0 = front-left, wheel 1 = front-right, wheel 2 = rear-left, wheel 3 = rear-right), front differential links wheels 0 and 1 (b3dAddVehicleDifferential(vehicle, 0, 1, 1.5)), rear differential links wheels 2 and 3 (b3dAddVehicleDifferential(vehicle, 2, 3, 3.0)).

Differential behavior in turns: during straight driving (both wheels spin at same speed, torque split equally), during turns (outer wheel spins faster, inner wheel spins slower, differential allows speed difference), differential ensures (both wheels powered regardless of speed difference, no tire scrubbing, realistic cornering). Without differential: left and right wheels locked together (same speed always, one wheel slides in turns, unrealistic handling, increased tire wear), single-track vehicles (motorcycles, bicycles) don't need differentials (only 1 wheel per axle, no left/right speed difference).

Multiple differentials: cars typically have 1 or 2 differentials (1 for FWD/RWD, 2 for AWD), 6-wheel trucks may have 3+ differentials (multiple driven axles, each axle has differential), call b3dAddVehicleDifferential multiple times (once per differential, different ratios per axle supported). AWD configuration example: front differential (links front-left and front-right, ratio 2.0 for efficiency), rear differential (links rear-left and rear-right, ratio 3.0 for power), center differential optional in some systems (links front and rear axles, BambooBasic may not support explicit center differential, front and rear independently driven).

Tuning acceleration: increase differentialRatio for better acceleration (more torque at wheels, quicker 0-60 time, sacrifice top speed), decrease differentialRatio for higher top speed (less torque but engine RPM spread over wider speed range, slower acceleration but higher max speed), balance front and rear ratios (front lower for steering response, rear higher for traction/acceleration).

Gear ratios in multi-speed transmission: real cars have multiple gears (1st gear high ratio ~4.0 for acceleration, 5th gear low ratio ~1.5 for cruising), BambooBasic single differentialRatio (simplified model, no gear shifting, ratio represents overall drive ratio), simulate multi-speed by scripting (change differentialRatio dynamically based on speed, lower ratio at high speed for "shifting up", not directly supported, would require vehicle recreation).

Performance: O(1) operation (adds differential to Jolt WheeledVehicle, no per-frame cost), differential physics integrated into vehicle simulation (torque distribution calculated during physics step, minimal overhead). Validation: silently returns if vehicleHandle invalid (vehicle not found in g_vehicleHandles), silently returns if leftWheelIndex or rightWheelIndex out of bounds (wheel indices must match wheels added with b3dAddVehicleWheel), no validation on differentialRatio value (negative or zero values allowed but not meaningful, use positive values for expected behavior).

Related: b3dCreateVehicle creates vehicle body (call before adding differentials), b3dAddVehicleWheel adds wheels (call before adding differentials, differential references wheel indices), b3dSetVehicleEngine sets engine torque (differential multiplies engine torque to wheels), b3dFinalizeVehicle activates vehicle (call after adding differentials), b3dSetDifferential updates existing differential (alternative function to modify differential after creation).

Typical values: front-wheel drive (front differential ratio 2.0-3.0, rear wheels no differential), rear-wheel drive (rear differential ratio 2.5-4.0, front wheels no differential), all-wheel drive (front ratio 1.8-2.5, rear ratio 2.5-3.5), truck (rear differential ratio 4.0-6.0 for hauling), racing (front ratio 2.0-3.0, rear ratio 3.0-4.5 tuned for track).