b3dFinalizeVehicle

Finalizes vehicle configuration and activates vehicle physics simulation. Takes vehicleHandle (vehicle created with b3dCreateVehicle, must have wheels added with b3dAddVehicleWheel, engine configured with b3dSetVehicleEngine, and optionally transmission/differentials/brakes configured). Returns nothing. Commits vehicle configuration to Jolt physics system and begins physics simulation. Must be called after all vehicle configuration complete and before using b3dSetVehicleInput or other runtime vehicle functions.

This function activates vehicle. Vehicle finalization: after b3dCreateVehicle called (vehicle body created with suspension settings), after b3dAddVehicleWheel called for all wheels (minimum 1 wheel required, typically 2-4 wheels for cars, 2 wheels for motorcycles, 6+ wheels for trucks), after b3dSetVehicleEngine called (engine torque and RPM range configured), optionally after b3dSetVehicleTransmission called (clutch strength set, defaults used if not called), optionally after b3dAddVehicleDifferential called (differentials link left/right wheels, optional but recommended for realistic handling), optionally after b3dSetVehicleWheelSteering/Braking/Friction called per wheel (wheel-specific configuration, defaults used if not called), call b3dFinalizeVehicle to commit configuration and activate physics.

Finalization process: validates vehicle configuration (ensures wheels added, engine configured, minimum requirements met), builds Jolt WheeledVehicleConstraint (creates constraint between vehicle body and wheels, sets up suspension raycasts, configures torque transfer), adds vehicle to physics world (vehicle participates in collision detection and physics simulation), enables vehicle input (b3dSetVehicleInput now functional, vehicle responds to throttle/brake/steering). Before finalization: vehicle exists but physics inactive (configuration functions work, vehicle does not move or respond to input, wheels not simulated). After finalization: vehicle physics active (vehicle responds to b3dSetVehicleInput, wheels raycast for ground contact, suspension compresses/extends, engine torque accelerates vehicle).

Workflow: (1) b3dCreateVehicle creates vehicle body, (2) b3dAddVehicleWheel adds all wheels (at least 1 required), (3) b3dSetVehicleEngine configures engine (required for acceleration), (4) b3dSetVehicleTransmission sets transmission (optional, defaults used otherwise), (5) b3dAddVehicleDifferential adds differentials (optional but recommended), (6) b3dSetVehicleWheel* configures per-wheel properties (optional, defaults used otherwise), (7) b3dFinalizeVehicle activates vehicle (required before control), (8) b3dSetVehicleInput controls vehicle (now functional after finalization).

Use cases: (1) Complete vehicle setup (finalize after all configuration to activate physics), (2) Standard car (create vehicle, add 4 wheels, set engine, add front/rear differentials, configure steering/braking, finalize), (3) Motorcycle (create vehicle, add 2 wheels, set engine, configure steering on front wheel, finalize), (4) Tank (create tracked vehicle with b3dCreateTrackedVehicleChassis, add wheels/tracks, finalize), (5) Custom vehicle (any wheel configuration, finalize when ready). Common pattern: setup all configuration (vehicle, wheels, engine, transmission, differentials, per-wheel settings), call b3dFinalizeVehicle once at end (activate all configuration at once).

Finalization requirements: at least 1 wheel added (vehicle with 0 wheels invalid, b3dFinalizeVehicle may fail or crash), engine configured (b3dSetVehicleEngine called, otherwise vehicle may not accelerate), wheels positioned reasonably (wheel positions should match visual mesh, suspension should reach ground). Optional configurations: transmission (defaults to clutch strength 0.5 if b3dSetVehicleTransmission not called), differentials (vehicle works without differentials but handling less realistic, left/right wheels independent), wheel steering/braking/friction (defaults to no steering, default brake torque, default friction if not configured), anti-roll bars (optional stability feature, not required).

Post-finalization: vehicle cannot be reconfigured (wheels cannot be added/removed after finalization, engine/transmission settings fixed, must destroy and recreate vehicle to change configuration), vehicle responds to input (b3dSetVehicleInput now controls throttle/brake/steering), vehicle participates in physics (collides with environment, affected by gravity, suspension active). Typical usage: finalize once during initialization (vehicle setup complete, activate physics), control vehicle with b3dSetVehicleInput (every frame after finalization), read vehicle state with b3dGetVehicleSpeed/RPM (for UI/logic after finalization).

Error handling: silently returns if vehicleHandle invalid (vehicle not found in g_vehicleHandles), may fail if vehicle has 0 wheels (undefined behavior, ensure wheels added), may fail if engine not configured (vehicle exists but doesn't accelerate, call b3dSetVehicleEngine before finalizing). Performance: O(1) operation (builds Jolt constraint, adds to physics world, one-time cost), vehicle physics simulation O(n) per frame where n = number of wheels (each wheel raycast for suspension, minimal overhead for typical 4-wheel vehicle).

Validation: check vehicleHandle valid before calling (handle returned by b3dCreateVehicle), ensure wheels added (at least 1, typically 2-4), ensure engine configured (b3dSetVehicleEngine called with reasonable torque/RPM values). Related: b3dCreateVehicle creates vehicle body (call first), b3dAddVehicleWheel adds wheels (call before finalizing, at least 1 wheel required), b3dSetVehicleEngine configures engine (call before finalizing for acceleration), b3dSetVehicleTransmission sets transmission (optional, call before finalizing), b3dAddVehicleDifferential adds differentials (optional, call before finalizing), b3dSetVehicleWheel* configures per-wheel properties (optional, call before finalizing), b3dSetVehicleInput controls vehicle (call after finalizing, every frame).

Common mistakes: forgetting to call b3dFinalizeVehicle (vehicle created but doesn't respond to input, physics inactive), calling b3dSetVehicleInput before b3dFinalizeVehicle (input ignored, vehicle not activated yet), calling b3dFinalizeVehicle with 0 wheels (undefined behavior, may crash or fail silently), trying to add wheels after b3dFinalizeVehicle (not supported, configuration locked after finalization). Debug tips: if vehicle doesn't move (check b3dFinalizeVehicle called, check engine configured, check wheels added), if vehicle falls through ground (check suspension raycast hitting ground, check wheel positions reasonable), if vehicle doesn't steer (check steering configured with b3dSetVehicleWheelSteering, check b3dFinalizeVehicle called).