b3dCreateVehicle

Creates a wheeled vehicle physics body with suspension system attached to an entity. Takes entityHandle (entity to attach vehicle to), mass (vehicle mass in kg affecting acceleration/handling), suspensionMinLength/suspensionMaxLength (suspension travel limits determining ride height range), suspensionFrequency (suspension spring frequency in Hz controlling stiffness), suspensionDamping (suspension damping ratio 0-1 for bounce control), visualBottomOffset (vertical offset between visual mesh bottom and physics body bottom in units). Returns vehicle handle (positive integer for use with b3dSetVehicleInput/b3dAddVehicleWheel/etc, 0 on failure). Creates Jolt WheeledVehicle physics body, sets up suspension system, and prepares vehicle for wheel attachment.

This function initializes a wheeled vehicle. Vehicle parameters: entityHandle (3D entity created with b3dLoadMesh/b3dCreateBox/etc, vehicle visual representation, physics attached to this entity's transform), mass (total vehicle mass in kilograms including chassis and wheels, affects acceleration/braking/handling, typical car 1000-2000 kg, typical truck 3000-5000 kg, heavier vehicles accelerate slower but have more momentum), suspensionMinLength (minimum suspension length in units when fully compressed, determines lowest ride height, typically 0.3-0.5 for cars, suspension cannot compress below this), suspensionMaxLength (maximum suspension length in units when fully extended, determines highest ride height, typically 0.5-0.7 for cars, suspension cannot extend beyond this, suspensionTravel = suspensionMaxLength - suspensionMinLength), suspensionFrequency (suspension spring frequency in Hz, controls how quickly suspension oscillates, typical range 1-3 Hz, higher = stiffer suspension, lower = softer/bouncier suspension, affects ride comfort and handling), suspensionDamping (suspension damping ratio 0-1, controls how quickly oscillation settles, 0 = no damping/bouncy, 1 = critically damped/quick settle, 0.5-0.7 typical for responsive handling), visualBottomOffset (vertical offset in units between visual mesh bottom and physics body bottom, positive = physics body lower than mesh, negative = physics body higher than mesh, used to align wheels with ground when mesh pivot not at bottom).

Suspension physics: suspension acts as spring/damper system (Hooke's law F = -kx with damping), suspensionFrequency converts to spring stiffness (k = (2π * frequency)^2 * mass), suspensionDamping applies velocity-dependent force (damping opposes compression/extension velocity), suspension length interpolates between min and max based on ground contact and load. Frequency vs stiffness: low frequency (1 Hz) = soft suspension (comfortable ride, more body roll, slower response), medium frequency (2 Hz) = balanced suspension (typical cars, good compromise), high frequency (3+ Hz) = stiff suspension (sporty handling, less body roll, harsh ride over bumps). Damping ratio: underdamped (< 0.5) = oscillates multiple times before settling (bouncy ride), critically damped (1.0) = returns to rest quickly without oscillation (ideal for some applications), overdamped (> 1.0) = slow return to rest (sluggish response), typical vehicle damping 0.5-0.7 balances comfort and control.

Vehicle workflow: (1) Create entity for vehicle visual (mesh = b3dLoadMesh("car.glb"), or primitive like b3dCreateBox), (2) Create vehicle body (vehicle = b3dCreateVehicle(mesh, mass, suspMin, suspMax, suspFreq, suspDamp, visualOffset)), (3) Add wheels (wheel1 = b3dAddVehicleWheel(vehicle, x, y, z, radius, width, ...), repeat for each wheel), (4) Configure engine (b3dSetVehicleEngine(vehicle, maxTorque, minRPM, maxRPM)), (5) Configure transmission (b3dSetVehicleTransmission(vehicle, clutchStrength)), (6) Configure differentials (b3dAddVehicleDifferential(vehicle, leftWheel, rightWheel, ratio)), (7) Configure wheel properties (b3dSetVehicleWheelSteering/b3dSetVehicleWheelBraking/b3dSetVehicleWheelFriction per wheel), (8) Finalize vehicle (b3dFinalizeVehicle(vehicle) to activate physics), (9) Control vehicle (b3dSetVehicleInput(vehicle, forward, right, handBrake) each frame).

Use cases: (1) Arcade racing (simple car controls with responsive handling), (2) Simulation racing (realistic vehicle physics with proper suspension/tire simulation), (3) Vehicle combat (tanks, buggies with weapons and physics), (4) Open world driving (cars, trucks, motorcycles in exploration games), (5) Physics puzzles (vehicle-based challenges requiring precise control). Common patterns: basic car (vehicle = b3dCreateVehicle(mesh, 1500, 0.3, 0.5, 2.0, 0.6, 0.0), add 4 wheels, set steering on front wheels), heavy truck (mass = 5000, suspFreq = 1.5 for soft suspension, suspDamping = 0.7), sports car (mass = 1000, suspFreq = 3.0 for stiff suspension, suspDamping = 0.5), off-road vehicle (suspTravel = 0.5 units for large suspension range, suspFreq = 1.5 for soft).

Visual bottom offset: used to align physics with visual mesh when mesh pivot not at bottom (if mesh pivot at center and mesh height = 2 units, visualBottomOffset = 1.0 moves physics down 1 unit so physics bottom aligns with mesh bottom), positive offset lowers physics body (vehicle sits lower to ground), negative offset raises physics body (vehicle sits higher, may cause wheels to float above mesh), set to 0 if mesh pivot already at bottom. Typical usage: create mesh in modeler with pivot at bottom (visualBottomOffset = 0), or create mesh with pivot at center (visualBottomOffset = meshHeight / 2).

Mass distribution: total mass includes chassis and all wheels (wheel mass typically 5-10% of total for cars), heavier mass = slower acceleration but more momentum (harder to stop/turn), lighter mass = faster acceleration but less stability (easier to flip). Suspension tuning: stiff suspension (high frequency, low damping) = responsive handling, less body roll, harsh ride (racing cars), soft suspension (low frequency, high damping) = comfortable ride, more body roll, slow response (luxury cars), adjust per gameplay feel (arcade racing = stiffer, realistic simulation = softer). Suspension travel: short travel (0.2 units) = low-profile sports car, limited bump absorption (smooth tracks), long travel (0.5+ units) = off-road vehicle, absorbs large bumps (rough terrain), suspensionMaxLength - suspensionMinLength = total travel.

Entity attachment: vehicle physics attaches to entityHandle transform (vehicle position/rotation sync with entity, moving entity moves vehicle physics), entity visual mesh rendered at entity position (physics and visual always aligned), entity can be mesh or primitive (any renderable 3D object works). Coordinate system: suspensionMinLength/suspensionMaxLength in Y-up BambooBasic coordinates (Y-axis vertical, suspension compresses/extends vertically), visualBottomOffset in Y-axis units (positive = down, negative = up), wheel positions (added with b3dAddVehicleWheel) in local entity coordinates.

Performance: O(1) operation for vehicle creation (allocates Jolt WheeledVehicle, sets up suspension settings), vehicle physics simulation O(n) where n = number of wheels (each wheel raycast per frame for ground contact), typical 4-wheel vehicle minimal overhead (Jolt optimized for vehicles). Memory: vehicle handle stored in global map (g_vehicleHandles maps handle to Jolt VehicleConstraint*), vehicle body added to physics world (participates in collision/simulation), vehicle persists until destroyed.

Validation: returns 0 if g_physicsSystem not initialized (must call b3dInitPhysics first), returns 0 if entityHandle invalid (entity not found in g_entityMap), creates vehicle with default settings (caller must add wheels and configure engine/transmission before use). Related: b3dAddVehicleWheel adds wheels to vehicle (required for vehicle to function), b3dSetVehicleEngine configures engine torque/RPM (required for vehicle to accelerate), b3dSetVehicleTransmission sets clutch strength (affects power transfer), b3dFinalizeVehicle activates vehicle physics (required after adding wheels/configuration), b3dSetVehicleInput controls vehicle (forward/right/brake inputs), b3dCreateTrackedVehicleChassis creates tracked vehicle alternative (tanks with treads instead of wheels).

Typical values: mass (small car 800-1200 kg, sedan 1200-1800 kg, SUV 2000-3000 kg, truck 3000-6000 kg), suspensionMinLength (0.2-0.4 units for cars, shorter for low sports cars, longer for trucks), suspensionMaxLength (0.4-0.7 units for cars, creates 0.2-0.3 travel, up to 1.0+ for off-road), suspensionFrequency (1.0-1.5 Hz soft/comfort, 2.0-2.5 Hz balanced, 3.0+ Hz stiff/sport), suspensionDamping (0.5-0.7 typical, 0.3-0.5 for bouncy, 0.7-0.9 for controlled), visualBottomOffset (0.0 if mesh pivot at bottom, meshHeight/2 if pivot at center, adjust as needed for wheel alignment).