b3dAddVehicleWheel

Adds a wheel to a vehicle with position, size, and suspension properties. Takes vehicleHandle (vehicle created with b3dCreateVehicle), posX/posY/posZ (wheel attachment position in local entity coordinates, relative to vehicle center), radius (wheel radius in units determining wheel size and ground contact), width (wheel width in units for visual representation and collision), suspensionMinLength/suspensionMaxLength (per-wheel suspension travel limits overriding vehicle defaults), suspensionFrequency (per-wheel spring frequency in Hz overriding vehicle default), suspensionDamping (per-wheel damping ratio 0-1 overriding vehicle default). Returns wheel index (0-based integer incremented for each wheel added, use with b3dSetVehicleWheelSteering/b3dSetVehicleWheelBraking/etc). Adds wheel to Jolt WheeledVehicle, sets up suspension raycast, and prepares wheel for physics simulation.

This function adds wheels to vehicle. Wheel parameters: vehicleHandle (vehicle handle from b3dCreateVehicle, must be valid vehicle), posX/posY/posZ (wheel position in local entity coordinates, X = left/right, Y = up/down, Z = forward/back, relative to entity pivot, typical car has wheels at corners), radius (wheel radius in units, determines wheel circumference and ground contact point, typical car 0.3-0.5 units, larger wheels = higher ride height and faster top speed for same RPM), width (wheel width in units, affects tire contact patch and friction calculation, typical car 0.2-0.3 units, wider = more grip), suspensionMinLength/suspensionMaxLength (per-wheel suspension travel, overrides vehicle defaults from b3dCreateVehicle, allows different suspension per wheel for asymmetric vehicles or tuning), suspensionFrequency (per-wheel spring frequency in Hz, overrides vehicle default, allows stiffer front suspension for better steering response), suspensionDamping (per-wheel damping ratio 0-1, overrides vehicle default, allows different damping per wheel).

Wheel positioning: posX/posY/posZ in local entity space (if entity pivot at center, posX = -1 is left side, posX = +1 is right side), typical car layout (front-left posX=-0.9 posZ=+1.5, front-right posX=+0.9 posZ=+1.5, rear-left posX=-0.9 posZ=-1.5, rear-right posX=+0.9 posZ=-1.5), posY typically 0 (wheels at same height as entity pivot, suspension extends downward), adjust posX/posZ to match visual mesh wheel positions. Wheel index: first wheel added = index 0, second wheel = index 1, etc (incremental 0-based indexing), wheel index used with b3dSetVehicleWheelSteering(vehicle, wheelIndex, maxAngle), b3dSetVehicleWheelBraking(vehicle, wheelIndex, brakeTorque, handBrakeTorque), b3dSetVehicleWheelFriction(vehicle, wheelIndex, lateral, longitudinal), b3dIsVehicleWheelInContact(vehicle, wheelIndex).

Suspension per wheel: suspensionMinLength/suspensionMaxLength override vehicle defaults (allows independent suspension tuning per wheel), suspensionFrequency/suspensionDamping override vehicle defaults (different stiffness/damping per wheel), use cases (stiffer front suspension for better steering response, softer rear suspension for comfort, asymmetric suspension for uneven weight distribution). Typical workflow: add all wheels with same suspension (use vehicle defaults from b3dCreateVehicle), or add wheels with custom suspension (tune each wheel independently for advanced handling).

Wheel size: radius affects (1) ground clearance (larger radius = vehicle sits higher), (2) top speed (larger radius = faster speed for same RPM via larger circumference), (3) acceleration (smaller radius = better acceleration via mechanical advantage), width affects (1) tire contact patch (wider = more friction surface area), (2) lateral grip (wider = better cornering), (3) rolling resistance (wider = more resistance, slower acceleration). Typical sizes: small car (radius 0.3, width 0.2), sedan (radius 0.35, width 0.25), SUV (radius 0.45, width 0.3), truck (radius 0.5, width 0.35), racing car (radius 0.35, width 0.3-0.4 for grip).

Use cases: (1) Standard 4-wheel car (add 4 wheels at corners, all same size and suspension), (2) 6-wheel truck (add 6 wheels, 2 front + 4 rear in dual-axle configuration), (3) Motorcycle (add 2 wheels, front and rear on centerline), (4) Monster truck (large radius for high clearance, stiff suspension), (5) Formula car (wide wheels for grip, stiff suspension for handling). Common patterns: symmetric 4-wheel (FL, FR, RL, RR at ±X, ±Z), dual rear axle (6 wheels with 2 rear axles for heavy trucks), tricycle (2 rear wheels, 1 front wheel on centerline).

Coordinate system: posX/posY/posZ in local entity coordinates (Y-up system, same as entity transform), wheel position relative to entity pivot (if pivot at center, posX = -1 is 1 unit left), suspension extends downward from wheel position (raycast from posY toward ground). Wheel physics: each wheel performs raycast each frame (checks for ground contact below wheel), suspension compresses/extends based on raycast hit distance (interpolates between suspensionMinLength and suspensionMaxLength), tire friction applied at contact point (lateral and longitudinal friction for steering/acceleration), wheel rotation calculated from vehicle speed (visual wheel spin synced with physics).

Suspension tuning: per-wheel suspension allows advanced tuning (front wheels stiffer than rear for oversteer reduction, left wheels different from right for oval racing), typical patterns (front suspFreq = 2.5, rear suspFreq = 2.0 for balanced handling, all wheels suspFreq = 2.0 for simple setup), damping (front suspDamp = 0.7, rear suspDamp = 0.6 for controlled response). Suspension travel: suspensionMaxLength - suspensionMinLength = wheel travel (short travel for low-profile sports car, long travel for off-road), suspensionMinLength determines compressed ride height (wheel position when fully compressed), suspensionMaxLength determines extended ride height (wheel position when fully extended).

Wheel visual: BambooBasic vehicle system does not automatically create wheel visuals (wheels are physics-only raycasts), create separate wheel entities (wheelMesh = b3dCreateCylinder, position/rotate wheelMesh to match wheel physics position each frame), or use animated vehicle mesh with wheels (mesh includes wheel geometry, sync mesh animation with physics wheel rotation). Typical approach: create 4 wheel entities, position them at wheel physics positions, rotate them based on vehicle speed and steering angle.

Performance: O(1) operation for wheel addition (adds wheel to Jolt WheeledVehicle wheel array), each wheel adds raycast per frame (Jolt performs suspension raycast to find ground), typical 4-wheel vehicle minimal overhead (Jolt optimized for vehicles). Memory: wheel data stored in Jolt WheeledVehicle (position, radius, width, suspension settings), wheel index auto-incremented (starts at 0 for first wheel).

Validation: returns -1 if vehicleHandle invalid (vehicle not found in g_vehicleHandles), adds wheel with specified parameters (no validation on position/size, ensure values reasonable), must call b3dFinalizeVehicle after adding all wheels (activates vehicle physics). Related: b3dCreateVehicle creates vehicle body (call before adding wheels), b3dSetVehicleWheelSteering configures wheel steering (use wheel index returned by this function), b3dSetVehicleWheelBraking configures wheel braking (use wheel index), b3dSetVehicleWheelFriction configures tire friction (use wheel index), b3dFinalizeVehicle activates vehicle (call after adding all wheels and configuration).

Typical values: posX (±0.8 to ±1.2 for car width, 0 for motorcycle), posY (0 typical if pivot at wheel height, adjust if pivot elsewhere), posZ (±1.0 to ±2.0 for car length, larger for longer vehicles), radius (0.3-0.5 for cars, 0.6+ for trucks/monster trucks), width (0.2-0.4 for cars, 0.3-0.5 for trucks), suspensionMinLength (0.2-0.4 for cars, match or override vehicle default), suspensionMaxLength (0.4-0.7 for cars, match or override vehicle default), suspensionFrequency (1.5-3.0 Hz, match or override vehicle default), suspensionDamping (0.5-0.7, match or override vehicle default).