b3dSetPhysicsBodyDamping

Sets physics body damping (0.0=space/no resistance, 1.0=maximum drag, affects velocity decay). Takes bodyHandle (physics body from b3dCreatePhysicsBody), linearDamping (0.0=no drag like space, 1.0=maximum drag like thick fluid, affects velocity decay), angularDamping (0.0=no rotational drag, 1.0=maximum rotational drag, affects spin decay). Returns nothing. Sets Jolt MotionProperties damping values, affects velocity and angular velocity reduction each frame. Use for air resistance, water drag, or gameplay feel tuning.

This function configures velocity damping. Damping parameters: linearDamping (affects linear velocity decay, 0.0 = no resistance, velocity preserved forever like space, 1.0 = maximum resistance, velocity decays to zero quickly like thick fluid, 0.05 typical for air, 0.5-0.9 for water/oil), angularDamping (affects angular velocity decay, 0.0 = no rotational resistance, spin preserved forever, 1.0 = maximum rotational resistance, spin stops quickly, independent of linear damping). Damping physics: damping simulates air resistance and fluid drag (velocity *= (1 - damping) each frame, exponential decay over time), higher damping = faster velocity loss (objects slow down quickly after forces stop), lower damping = longer coasting (objects maintain velocity longer after push). Use cases: (1) Air resistance (linearDamping=0.01-0.05 for realistic air drag on projectiles, prevents infinite sliding), (2) Water physics (linearDamping=0.5-0.9 for underwater movement, objects slow quickly when stopping swim), (3) Space simulation (linearDamping=0.0 for frictionless void, objects drift forever), (4) Gameplay feel (tune damping for responsive controls vs floaty physics), (5) Rotational stabilization (angularDamping=0.5-0.9 to prevent excessive spinning from impacts). Common patterns: air resistance b3dSetPhysicsBodyDamping(body, 0.05, 0.05), underwater b3dSetPhysicsBodyDamping(body, 0.8, 0.7), space b3dSetPhysicsBodyDamping(body, 0.0, 0.0), responsive controls b3dSetPhysicsBodyDamping(player, 0.2, 0.3), prevent spin b3dSetPhysicsBodyDamping(crate, 0.1, 0.9). Typical usage: set after b3dCreatePhysicsBody to define material behavior, adjust dynamically for environmental changes (enter water = high damping, exit water = low damping), tune for gameplay feel (iterate damping values until movement feels right). Damping vs friction: damping opposes velocity globally (affects movement in all directions including air, independent of contacts), friction opposes velocity at contact surfaces (only when touching another body, direction-dependent), damping simulates air/fluid resistance (always active), friction simulates surface roughness (only during collisions). Linear damping effect: object with velocity (10, 0, 0) and linearDamping=0.1 loses 10% velocity per frame (frame 1: velocity=9, frame 2: velocity=8.1, frame 3: velocity=7.29), exponential decay converges to zero (never quite reaches zero but becomes negligible), higher damping = faster decay (damping=0.5 halves velocity each frame). Angular damping effect: object spinning at 360 deg/sec with angularDamping=0.2 loses 20% angular velocity per frame (frame 1: 288 deg/sec, frame 2: 230 deg/sec, frame 3: 184 deg/sec), prevents perpetual spinning from impacts (realistic objects slow rotation due to air resistance), independent of linear damping (can have high linear damping with low angular damping or vice versa). Damping range: 0.0 = no damping (velocity never decays, objects drift/spin forever like space), 0.01-0.05 = light damping (slow decay, realistic air resistance for normal gravity), 0.1-0.3 = moderate damping (noticeable decay, responsive gameplay feel), 0.5-0.9 = heavy damping (rapid decay, underwater or thick fluid), 1.0 = maximum damping (velocity decays to near-zero in one frame, extreme drag). Frame rate independence: Jolt applies damping per physics step (typically 60 Hz), damping values calibrated for 60 FPS (may need adjustment for different physics step rates), exponential decay ensures smooth deceleration regardless of framerate. Performance: O(1) operation (simple property set via Jolt MotionProperties), damping applied during physics step (minimal overhead per body, integrated into velocity update), locks body for writing (thread-safe access to MotionProperties). Body locking: uses Jolt BodyLockWrite for thread-safe modification (prevents race conditions during physics simulation), lock succeeds if body valid and not currently being modified, silently fails if lock unsuccessful (body in invalid state or deleted). MotionProperties access: dynamic bodies (mass>0) have MotionProperties (contains mass, inertia, damping, velocity), static bodies (mass=0) have no MotionProperties (damping not applicable to immovable objects), checks if motionProps valid before setting damping (prevents null pointer access). Default damping: Jolt default damping typically 0.05 for both linear and angular (light air resistance unless explicitly set), must call this function to customize damping values, damping persists until changed (does not reset each frame). Damping formula: velocity_new = velocity_old * (1 - damping)^deltaTime (exponential decay, frame rate independent), deltaTime typically 1/60 for 60 Hz physics step, damping=0.1 and deltaTime=1/60 gives velocity *= 0.9983 per frame (very gradual decay). Extreme damping: damping>1.0 causes velocity reversal (non-physical, objects accelerate backward, not recommended), damping=1.0 stops objects in one frame (useful for instant stop zones, freeze effects), negative damping adds energy (non-physical, objects accelerate forever, anti-damping). Validation: silently returns if g_physicsSystem not initialized (b3dInitPhysics not called), silently returns if bodyHandle not found in g_bodyHandleToBodyID (invalid or freed body), silently fails if BodyLockWrite unsuccessful (body being modified by another thread), silently fails if MotionProperties null (static body or invalid state). Jolt integration: acquires BodyLockWrite on bodyID (thread-safe write access), gets MotionProperties pointer (nullptr for static bodies), calls SetLinearDamping((float)linearDamping) and SetAngularDamping((float)angularDamping), releases lock when function exits (RAII pattern). Related: b3dCreatePhysicsBody creates physics body (call this after to set damping), b3dSetPhysicsBodyVelocity sets velocity (damping causes velocity to decay over time), b3dSetPhysicsBodyAngularVelocity sets angular velocity (angularDamping causes spin to decay), b3dSetPhysicsBodyFriction sets surface friction (different from damping, only at contacts).