Utility Scripts · Sockets
Lifecycle, Debugging, and Troubleshooting
Managed cleanup protects against stale body handles, while debug drawing exposes current runtime state without changing physics.
A Socket retains its world and generational body handle. Validity checks the live parent, matching handle, and current managed world rather than merely testing whether a GML struct still exists.
Safe cleanup order#
- socket.destroy() dissolves its group, then its connection, then removes the Socket.
- connection.destroy() destroys the constraint, restores pair collision, clears endpoints, and starts cooldown.
- group.destroy() disconnects its one connection and releases surviving Sockets for ordinary use.
- Destroying a parent body automatically cleans related Sockets, groups, and connections. A stale generational handle is never reused for native destruction.
- jolt_stop() clears Socket registries with the managed world resources.
Debug drawing#
Enable Socket drawing through the normal debug system and JOLT_DEBUG_SOCKETS. Every Socket draws a marker and local axes: X red, Y green, and Z blue. Marker color distinguishes disabled, free, candidate, and connected state.
| Group state | Color |
|---|---|
| Aligned pair / connected group | Green |
| Eligible in-range pair / active group | Amber |
| Group ready for capture | Cyan |
| Inactive pair or group | Red |
Point constraint debug reads both current native attachment points every frame. Its marker follows a translated or rotated assembly instead of retaining a creation-time world anchor.
Common problems#
| Symptom | Check |
|---|---|
| No candidate | Type, polarity, enabled, cooldown, search distance, same world, and different bodies. |
| Candidate never locks | Position/rotation error, relative speeds, force/torque caps, and obstacles. |
| Hinge or Point cannot move | Collider overlap; try collision:false for that pair. |
| Group remains at 1/2 | Compatibility, enabled state, and local frame of the second explicit pair. |
| Connection breaks immediately | Limit units, measured reaction load, and initial collider penetration. |
| No immediate reconnect | This is cooldown behavior; wait for the configured time. |
Pre-release checklist#
- Verify axes on a rotated parent, not only an identity transform.
- Test both the lightest and heaviest expected male with finite attraction caps.
- Test capture and post-capture motion on a moving host.
- Exercise disconnect, cooldown, reconnect, both parent destruction paths, and jolt_stop().
- Measure normal operating reactions before choosing break limits and leave suitable margin.