b3dSetVehicleInput

Sets vehicle control inputs for throttle/brake, steering, and handbrake. Takes vehicleHandle (vehicle created with b3dCreateVehicle), forward (-1 to 1 where negative=brake, 0=coast, positive=throttle/accelerate), right (-1 to 1 where negative=steer left, 0=straight, positive=steer right), handBrake (0 to 1 where 0=off, 1=full handbrake). Returns nothing. Updates Jolt WheeledVehicle input state, affects vehicle acceleration/braking/steering in next physics step. Call this every frame to control vehicle based on player input.

This function controls vehicle. Input parameters: vehicleHandle (vehicle handle from b3dCreateVehicle, must be valid finalized vehicle), forward (throttle/brake input in range -1 to 1, positive values 0 to 1 = throttle/accelerate, engine torque applied to driven wheels, 0 = coast, no throttle or brake, vehicle slows naturally from friction, negative values -1 to 0 = brake, brake torque applied to wheels with braking configured, magnitude determines braking force), right (steering input in range -1 to 1, negative values -1 to 0 = steer left, wheels turn left up to max steering angle, positive values 0 to 1 = steer right, wheels turn right up to max steering angle, 0 = straight, no steering angle, magnitude determines how much wheels turn), handBrake (handbrake/parking brake input in range 0 to 1, 0 = handbrake off, no additional braking, 1 = full handbrake, maximum handbrake torque applied to wheels configured with handbrake, intermediate values partially engage handbrake, useful for drift control).

Forward input behavior: positive forward (0.0 to 1.0) applies engine torque (forward = 0.5 applies 50% of max engine torque configured with b3dSetVehicleEngine, forward = 1.0 applies 100% of max engine torque for full acceleration, torque limited by current RPM and engine torque curve), negative forward (-1.0 to 0.0) applies brake torque (forward = -0.5 applies 50% of max brake torque configured with b3dSetVehicleWheelBraking, forward = -1.0 applies 100% of max brake torque for full braking, brake torque slows wheel rotation), zero forward (0.0) applies no torque (vehicle coasts, natural deceleration from rolling resistance and air drag, no active acceleration or braking).

Right input behavior: steering angle interpolated based on right input (right = 0 produces 0 degree steering angle, wheels straight, right = 1.0 produces max steering angle configured with b3dSetVehicleWheelSteering, wheels turned right, right = -1.0 produces negative max steering angle, wheels turned left), steering affects only wheels configured for steering (typically front wheels, rear wheels typically not steered unless 4-wheel steering), Ackermann steering automatically applied by Jolt (inside wheel turns sharper than outside wheel for realistic cornering).

HandBrake input behavior: handbrake torque applied to wheels configured with handbrake (b3dSetVehicleWheelBraking sets handBrakeTorque per wheel, typically rear wheels only for drift capability), handBrake = 1.0 applies full handBrakeTorque (locks rear wheels for maximum drift/skid), handBrake = 0.5 applies partial handbrake (controlled drift, maintains some traction), useful for arcade racing (sharp turns, drift mechanics) and parking (hold vehicle on slope).

Use cases: (1) Player vehicle control (map keyboard/gamepad input to forward/right/handBrake each frame), (2) AI vehicle control (calculate forward/right from pathfinding, navigate track/road), (3) Arcade racing (exaggerated inputs for responsive handling, use handBrake for drifting), (4) Simulation racing (realistic input mapping, smooth acceleration/braking), (5) Automated driving (script forward/right for cutscenes/demos). Common patterns: keyboard control (forward = BBR_GetKey(KEY_UP) - BBR_GetKey(KEY_DOWN), right = BBR_GetKey(KEY_RIGHT) - BBR_GetKey(KEY_LEFT), handBrake = BBR_GetKey(KEY_SPACE)), gamepad control (forward = gamepad trigger, right = gamepad stick X-axis, handBrake = gamepad button).

Input smoothing: raw input can be jittery (keyboard gives instant 0 or 1, no intermediate values), smooth input for more realistic feel (lerp current input toward target input, currentForward = currentForward * 0.9 + targetForward * 0.1), smoothing creates acceleration ramp-up/down (mimics real vehicle inertia, prevents instant speed changes). Input clamping: function does not validate input ranges (values outside -1 to 1 accepted but may cause unexpected behavior), clamp inputs before calling (forward = max(-1, min(1, rawForward)), right = max(-1, min(1, rawRight)), handBrake = max(0, min(1, rawHandBrake))).

Steering and speed: steering effectiveness depends on vehicle speed (high speed = less responsive steering, mimics real tire slip at high speed, low speed = more responsive steering, easier to turn tight corners), Jolt physics naturally simulates this (tire friction model accounts for speed), no special handling needed. Throttle and RPM: throttle input (forward > 0) only produces acceleration if engine RPM within operating range (RPM < minRPM or RPM > maxRPM produces no torque, configured with b3dSetVehicleEngine), transmission/differential ratios affect how throttle translates to wheel torque (higher differential ratio = more torque but lower top speed).

Brake and throttle conflict: if forward < 0 and handBrake > 0 (both brake and handbrake applied, both brake torques applied simultaneously, maximum braking force), if forward > 0 and forward < 0 not possible (forward single axis controls either throttle or brake, not both simultaneously, mimics real vehicles with separate throttle and brake pedals). Coast behavior: forward = 0, right = anything, handBrake = 0 (vehicle coasts, natural slowdown from friction, no active braking or acceleration, useful for momentum-based gameplay).

Reverse driving: negative throttle (forward < 0) applies brakes when moving forward (slows vehicle until stopped, does not reverse), reverse requires separate handling (some vehicle systems allow reverse at 0 speed, Jolt may require explicit reverse gear, check vehicle physics behavior for reverse implementation). Handbrake drifting: handBrake = 1.0 while turning (locks rear wheels, causes rear to slide out, creates drift), combine with forward > 0 (maintain speed during drift, power to front wheels keeps vehicle moving), useful for arcade racing drift mechanics.

Typical usage pattern: every frame read player input (keyboard, gamepad, AI decision), map input to -1 to 1 ranges (forward, right, handBrake), call b3dSetVehicleInput with mapped values (update vehicle control state), vehicle physics automatically responds (acceleration, steering, braking applied in next physics step). Performance: O(1) operation (sets Jolt WheeledVehicle input state, no complex calculation), input applied during physics step (integrated into vehicle simulation, minimal overhead), call once per frame (update control state, vehicle physics handles rest).

Validation: silently returns if vehicleHandle invalid (vehicle not found in g_vehicleHandles), no input clamping (values outside typical ranges accepted, ensure inputs in valid ranges for expected behavior), vehicle must be finalized (b3dFinalizeVehicle called after wheel/engine/transmission configuration). Related: b3dCreateVehicle creates vehicle (call before controlling), b3dSetVehicleEngine sets max torque (determines how much acceleration forward input produces), b3dSetVehicleWheelBraking sets brake torque (determines how much braking forward < 0 produces), b3dSetVehicleWheelSteering sets max steering angle (determines how much turning right input produces), b3dFinalizeVehicle activates vehicle (must call before b3dSetVehicleInput works), b3dGetVehicleSpeed reads current speed (for speedometer UI), b3dGetVehicleRPM reads current RPM (for tachometer UI).

Input remapping examples: inverted steering (right = -gamepad.stickX for inverted controls), combined throttle/brake axis (if singleAxis > 0 then forward = singleAxis else forward = singleAxis for triggers combined), digital to analog (keyboard binary input smoothed to analog range, creates ramp-up feel), sensitivity adjustment (right = gamepad.stickX * sensitivity for adjustable steering sensitivity).