b3dApplyPhysicsTorque

Applies rotational impulse/torque to physics body in deg (adds angular velocity, respects inertia). Takes bodyHandle (physics body from b3dCreatePhysicsBody), tx/ty/tz (torque in degrees around X/Y/Z axes). Returns nothing. Converts degrees to radians, adds torque to body angular velocity via Jolt AddTorque, activates body automatically. Use for spinning objects, applying rotational forces, or off-center impacts.

This function applies rotational torque. Torque components: tx (torque around X-axis in degrees, positive = pitch down, negative = pitch up), ty (torque around Y-axis in degrees, positive = yaw left, negative = yaw right), tz (torque around Z-axis in degrees, positive = roll left, negative = roll right). Degrees to radians conversion: BambooBasic uses degrees for user-friendly input (360 deg = full rotation), Jolt uses radians internally (2*PI rad = full rotation), conversion factor 0.0174532925 (PI/180) applied to each component before passing to Jolt. Torque physics: torque causes angular acceleration (analogous to force causing linear acceleration), angular velocity change depends on inertia tensor (shape and mass distribution affect resistance to rotation), added to current angular velocity (incremental change, accumulates with existing spin). Inertia tensor interaction: sphere has uniform inertia (spins easily around all axes), long rod has high inertia around short axes (resists spinning end-over-end, spins easily lengthwise), complex shapes have directional inertia (easier to spin around some axes than others), Jolt calculates inertia from shape and mass distribution automatically. Use cases: (1) Off-center impacts (apply torque when projectile hits edge of object for realistic spin), (2) Motor simulation (apply continuous torque for spinning wheels, fans, gears), (3) Tumbling debris (apply random torque to falling objects for chaotic motion), (4) Gameplay mechanics (apply torque to player object for barrel rolls, flips), (5) Collision response enhancement (add spin from glancing blows). Common patterns: random tumble b3dApplyPhysicsTorque(debris, Rnd()*360-180, Rnd()*360-180, Rnd()*360-180), motor spin b3dApplyPhysicsTorque(wheel, 0, motorPower, 0) each frame, impact spin impactTorque = CrossProduct(impactPoint - centerOfMass, impactForce) then b3dApplyPhysicsTorque(body, impactTorque.x, impactTorque.y, impactTorque.z). Typical usage: apply during collision for realistic impact spin (off-center hits cause rotation), use for continuous rotational forces (motors, propellers each frame), combine with b3dApplyPhysicsImpulse for full impact response (linear + rotational). Torque vs angular velocity: b3dApplyPhysicsTorque adds to angular velocity (respects inertia tensor, realistic rotation, accumulated forces), b3dSetPhysicsBodyAngularVelocity replaces angular velocity (ignores inertia, direct control, kinematic rotation), torque better for physics-driven rotation (impacts, motors, natural spin), direct angular velocity better for scripted rotation (spinning platforms, cutscene control). Activation: Jolt AddTorque activates body automatically (wakes sleeping bodies, enables collision detection), ensures torque takes effect immediately (body responds in next physics step), no manual activation needed. Coordinate system: tx/ty/tz in BambooBasic Y-up world coordinates (rotation around world axes), converted to radians before passing to Jolt Vec3, torque in world space (not local to body rotation unless body aligned with world). Multiple torques: can apply multiple torques in same frame (all accumulated before physics step), final angular velocity = initial angular velocity + sum(torques) / inertia, allows combining rotational forces (apply gravity torque + motor torque + friction torque). Torque magnitude: small torque (1-10 deg) for gentle rotation, medium torque (10-100 deg) for noticeable spin, large torque (100-1000 deg) for fast spinning, very large torque (>1000 deg) for extreme rotation (catastrophic impacts). Continuous vs impulse: continuous torque applied each frame accumulates angular velocity (motors, propellers, friction), impulse torque applied once then decays due to angular damping (impacts, explosions, one-time forces). Performance: O(1) operation (Vec3 conversion and add via Jolt BodyInterface), activation triggers broad-phase update (cheap), safe to apply many torques per frame (Jolt handles efficiently). Static body behavior: static bodies (mass=0, infinite inertia) ignore torque (torque/inertia = 0 angular acceleration), applying torque to static body has no effect (immovable and non-rotating by definition). Angular damping: if b3dSetPhysicsBodyDamping called with angularDamping>0 spin decays over time (accumulated torque effect reduces over frames), damping 0.0 = no decay (spin increases indefinitely with continuous torque), damping 1.0 = immediate stop (heavy air resistance). Off-center impacts: realistic collision should apply torque (impactPoint offset from center of mass creates lever arm, torque = leverArm cross impactForce), Jolt handles this automatically for collisions (AddImpulse at contact point applies both linear and angular impulse), manual torque needed for scripted impacts (explosions, custom collision response). Error handling: silently returns if g_physicsSystem not initialized (b3dInitPhysics not called), silently returns if bodyHandle not found in g_bodyHandleToBodyID (invalid or freed body), no validation on torque magnitude (extreme values allowed but may cause instability). Jolt integration: calls g_physicsSystem->GetBodyInterface().AddTorque(bodyID, Vec3(txRad, tyRad, tzRad)), Jolt divides torque by inertia tensor internally to compute angular acceleration (alpha = inertia^-1 * torque), adds angular acceleration * deltaTime to current angular velocity. Units: torque in degrees (converted to radians internally), magnitude arbitrary (depends on mass distribution and desired rotation rate), larger inertia requires larger torque for same angular acceleration. Validation: no parameter validation (negative/zero torques allowed, may be intentional), no clamping (extreme torques may cause instability, user responsible for reasonable values). Related: b3dSetPhysicsBodyAngularVelocity sets angular velocity directly (alternative to torque for direct control), b3dApplyPhysicsImpulse applies linear impulse (translation instead of rotation), b3dSetPhysicsBodyDamping sets angular damping (controls torque accumulation decay), b3dCreatePhysicsBody creates physics body with shape (shape determines inertia tensor).