Utility Scripts · Sockets
Socket / Docking System
Invisible local frames that find a compatible partner, align it physically, and create one managed connection between real JoltBody instances.
A Socket is not a rigid body, collider, or separate native physics object. It is a GML description of a position and orientation relative to its parent body. Every fixed step, the system builds its world transform, selects a compatible pair, and creates a Fixed, Hinge, Point, or SwingTwist constraint from the male Socket recipe.
How the system works#
- Each Socket belongs to one live managed JoltBody and stores a local-space position and quaternion rotation.
- Male is the moving, controlling side. Female is the host and target frame. Both must use the same compatibility type.
- Without attraction, a connection is created when the normal position and rotation tolerances pass.
- With attraction, bounded force and torque act on a Dynamic male. Capture waits for precise alignment and low relative speed.
- The connection owns one real constraint. Disconnect, cooldown, pair collision, break limits, and cleanup use one lifecycle path.
The four objects#
| Object | Responsibility |
|---|---|
| JoltSocket | Logical frame and connection rules; it has no shape, mass, or collision layer. |
| JoltBody | The physical body that moves, collides, and receives forces. |
| JoltSocketConnection | Managed owner of one Fixed, Hinge, Point, or SwingTwist constraint. |
| JoltSocketGroup | Several required pairs that define placement while still producing one constraint. |
Suggested learning path#
- Start with Quick Start and one male/female pair.
- Choose a connection type and decide whether the connected bodies should collide with each other.
- Enable attraction after verifying the local position and orientation with debug drawing.
- Add groups and break limits only after the basic pair behaves correctly.