b3dSetVehicleEngine

Configures vehicle engine with torque output and RPM range. Takes vehicleHandle (vehicle created with b3dCreateVehicle), maxTorque (maximum engine torque in Newton-meters, determines acceleration power), minRPM (minimum engine RPM where torque output begins, typically idle RPM), maxRPM (maximum engine RPM limit where torque drops to zero, redline). Returns nothing. Sets Jolt WheeledVehicle engine parameters, affects vehicle acceleration and top speed.

This function configures engine. Engine parameters: vehicleHandle (vehicle handle from b3dCreateVehicle, must be valid vehicle), maxTorque (maximum engine torque in Newton-meters, determines how much rotational force engine applies to wheels, higher = faster acceleration, typical car 200-500 Nm, typical truck 500-1000 Nm, typical sports car 400-700 Nm), minRPM (minimum engine RPM where engine begins producing torque, typically idle RPM around 1000, engine produces no torque below this RPM, prevents stalling), maxRPM (maximum engine RPM redline, engine produces no torque above this RPM, prevents over-revving, typical car 5000-7000 RPM, typical sports car 7000-9000 RPM, typical diesel 3000-5000 RPM).

Engine torque curve: engine torque interpolates between 0 and maxTorque based on current RPM (torque = 0 at RPM < minRPM, torque ramps up from minRPM to peak somewhere in middle, torque = maxTorque at optimal RPM, torque drops to 0 at maxRPM), Jolt uses simplified torque curve (not realistic multi-point curve, but sufficient for gameplay), adjust maxTorque to tune acceleration (higher maxTorque = faster acceleration). RPM calculation: engine RPM calculated from wheel rotation speed and differential ratio (RPM = wheelAngularVelocity * differentialRatio * 60 / (2π)), current RPM affects torque output (low RPM = low torque, optimal RPM = max torque, high RPM = reduced torque), RPM displayed with b3dGetVehicleRPM for dashboard/UI.

Torque vs power: torque is rotational force in Nm (determines acceleration at current speed), power is torque * RPM (determines top speed capability), high torque = good low-end acceleration (quick starts, hill climbing), high RPM range = good high-speed power (higher top speed). Typical values: economy car (maxTorque 150-250 Nm, minRPM 1000, maxRPM 6000), sports car (maxTorque 400-700 Nm, minRPM 1500, maxRPM 8000), truck (maxTorque 500-1200 Nm, minRPM 1000, maxRPM 4000), race car (maxTorque 500-900 Nm, minRPM 2000, maxRPM 10000).

Use cases: (1) Arcade racing (high maxTorque for responsive acceleration, wide RPM range), (2) Simulation racing (realistic torque values matching real vehicle specs), (3) Truck driving (high torque for hauling, low maxRPM for diesel characteristics), (4) Formula racing (moderate torque, very high maxRPM for high-speed performance), (5) Off-road driving (high torque for climbing, moderate RPM range). Common patterns: balanced car (maxTorque 400, minRPM 1000, maxRPM 6000), quick acceleration (maxTorque 700, minRPM 1500, maxRPM 7000), heavy hauler (maxTorque 1000, minRPM 1000, maxRPM 3500).

Engine and transmission: engine torque multiplied by transmission/differential ratios (wheel torque = engine torque * transmission ratio * differential ratio), higher differential ratio = more torque at wheels but lower top speed (better acceleration, slower max speed), lower differential ratio = less torque but higher top speed (slower acceleration, faster max speed), configure differentials with b3dAddVehicleDifferential. Engine and weight: heavier vehicles need more torque for same acceleration (F = ma, torque creates acceleration force at wheels), lighter vehicles accelerate faster with same torque (better power-to-weight ratio), adjust maxTorque based on vehicle mass.

RPM limiting: engine cannot exceed maxRPM (torque drops to 0 at redline, prevents over-revving), transmission should shift before maxRPM in simulation games (shift at ~80-90% of maxRPM for optimal acceleration), arcade games can ignore shifting (automatic transmission implicit). Min RPM: engine produces no torque below minRPM (prevents unrealistic instant torque from 0 RPM), mimics real engine idle behavior (engine must rev up before producing power), set minRPM = 0 for electric vehicle simulation (instant torque from 0 RPM).

Tuning acceleration: increase maxTorque for faster acceleration (more responsive vehicle, easier to spin wheels), decrease maxTorque for slower acceleration (more realistic, requires more skill), adjust differential ratios for fine-tuning (higher ratio = better acceleration but lower top speed). Tuning top speed: increase maxRPM for higher top speed (wider power band, more high-end performance), decrease differential ratio for higher top speed (less torque multiplication, higher gear ratio), balance torque and RPM for desired performance curve.

Coordinate system: torque applied in vehicle local space (forward direction, rotation around wheel axles), RPM calculated from wheel angular velocity (rotation speed of wheels converted to engine RPM via differential ratio). Performance: O(1) operation (sets Jolt engine parameters, no per-frame cost), engine torque applied during physics step (integrated into wheel force calculation, minimal overhead).

Validation: silently returns if vehicleHandle invalid (vehicle not found in g_vehicleHandles), no validation on torque/RPM values (negative values allowed but not meaningful, ensure positive values), must call b3dFinalizeVehicle after configuration (activates vehicle physics). Related: b3dCreateVehicle creates vehicle body (call before configuring engine), b3dSetVehicleTransmission sets clutch strength (affects how engine power transfers to wheels), b3dAddVehicleDifferential sets differential ratios (multiplies engine torque to wheels), b3dGetVehicleRPM reads current engine RPM (for dashboard/UI), b3dSetVehicleInput controls throttle (forward input controls how much torque applied, 0 = no throttle, 1 = full throttle).

Electric vehicle simulation: set minRPM = 0 for instant torque from standstill (electric motors have no idle RPM), set maxRPM very high (electric motors can rev much higher than combustion engines), set maxTorque high for strong acceleration (electric vehicles have excellent low-end torque), or use torque curve simulation (manually adjust torque based on speed for realistic electric characteristics).