Extraction and Cleanup
Use forces for extraction; remove the Tip to explicitly end its lifetime.
An active relationship owns a physics constraint and suppression of its specific collision pair. Termination releases both. Disabling admission, extraction and removal are three different operations.
| Intent | Operation | Result |
|---|---|---|
| Temporarily stop accepting new hits | tip.set_enabled(false) | Active penetration remains; re-enabling allows new hits. |
| Physically pull out the tool | Force / motion opposite the axis | Overcome backward_force, clear the whole collider and allow rearm. |
| Remove the tip from the tool | tip.remove() | Ends all its relationships; the body remains alive. |
| Destroy the tool or target | body.destroy() | Ends related relationships and invalidates the corresponding wrappers. |
| Stop the whole world | jolt_stop() | Cleans up the subsystem and registries and clears the event queue. |
Rearming after extraction#
Negative Tip depth alone is insufficient. A wide or tilted penetrator may still overlap the target geometrically. After full clearance and the required rearm_separation, the same Tip becomes ready for another hit. The next relationship receives a new identity; do not treat the old rel as current.
Collision suppression has ownership#
The system does not disable the penetrator's collisions with the whole world. It owns a lease for a specific pair and releases only its share at termination. Multiple relationships on one pair therefore must not restore collisions prematurely when one connection ends. Your own layer/group rules still apply.
Safe cleanup for one tool#
if (is_struct(tip) && tip.is_valid()) {
tip.remove();
}
if (is_struct(penetrator) && penetrator.is_valid()) {
penetrator.destroy();
}The Tip remains valid during normal extraction. Do not remove and recreate it every frame; that would unnecessarily disrupt lifecycle, identities and events.