b3dDisablePhysicsBody

Temporarily disables physics body simulation without destroying it. Takes entityHandle (entity handle with physics body from b3dCreatePhysicsBody). Returns nothing. Deactivates Jolt physics body, removing it from active simulation while preserving body data for later re-enable.

Physics disable: body removed from active simulation (no collision detection, no gravity/forces applied, no position/rotation updates from physics), body data preserved (mass, friction, restitution, shape all retained, ready for quick re-enable), performance improvement (inactive bodies skip physics step, similar cost savings to destruction but faster to re-enable). Use when physics temporarily not needed (cutscenes, paused gameplay, distant objects).

Disabled vs destroyed: b3dDisablePhysicsBody keeps body data (faster to re-enable with b3dEnablePhysicsBody, preserves all physics properties), b3dDestroyPhysicsBody removes body completely (requires b3dCreatePhysicsBody to re-enable, all properties must be reconfigured, frees more memory). Disabled vs sleeping: Jolt auto-sleeps inactive bodies (bodies at rest automatically sleep to save CPU, wake on interaction), b3dDisablePhysicsBody manually forces inactive (regardless of motion state, more aggressive optimization).

Use cases: (1) Paused gameplay (disable all physics during pause, re-enable on unpause), (2) Cutscenes (disable physics for scripted animation, re-enable for gameplay), (3) LOD (disable physics for distant objects, re-enable when close), (4) Conditional physics (disable when object picked up, re-enable when dropped). Common patterns: pause (b3dDisablePhysicsBody for all dynamic entities), cutscene (disable player physics, manually animate, re-enable after), LOD (if distance > 100 then disable, if distance < 90 then enable).

Performance: similar to destruction (inactive bodies skip physics simulation, ~0.1-0.5ms saved per 100 bodies), slightly higher memory than destruction (body data remains in Jolt, not freed), much faster to re-enable (no allocation/setup overhead). Validation: silently returns if entityHandle invalid, silently returns if entity has no physics body, safe to call on already-disabled body (no-op).

Related: b3dEnablePhysicsBody re-enables disabled body (inverse operation), b3dDestroyPhysicsBody permanently destroys body (alternative, frees more memory but slower to recreate), b3dCreatePhysicsBody creates physics body initially.