Physics Lock

Freeze a standalone rigid body at its current pose. Its handle, shape and references remain intact. It behaves as Static and remains a collision/raycast obstacle. Unlock restores the original motion type from rest; old velocities and accumulated forces are discarded. This is not sleeping.

Example#

body.set_physics_locked(true);
var locked = body.is_physics_locked();
body.set_physics_locked(false);

Usage and limits#

Valid force/impulse calls while locked have no motion effect and are not saved for later. Changing pose, velocity, motion type or Sensor state is rejected until unlocked. Read is_physics_locked() to distinguish temporary lock from ordinary Static. Setters return false on error; inspect jolt_get_error_message() immediately.

Sensors, Soft Bodies, held bodies and participants in constraints, vehicles, physical controls, character attachments, conveyors, scales or active penetration are rejected. Ordinary contact does not prevent locking.

Optional grabber.set_unlock_physics_locked(true) defaults off. It unlocks only after a successful eligible grab; originally Static/Kinematic objects do not become Dynamic. Release does not re-lock. This state is runtime-only, not Blender JSON.

API reference#

Public function and method signatures. Call methods on the returned instance; parameters with defaults are optional.

Related guides#

• Migrating existing code›

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.