Utility Scripts · Sockets
Sockets and Configuration
The complete jolt_socket contract, local transforms, compatibility rules, and runtime state.
jolt_socket(body, polarity, type, options=undefined) returns a JoltSocket or undefined and reports a standard high-level error. Numeric values must be finite, and the creation quaternion is normalized.
Syntax#
jolt_socket(body, polarity, type, options=undefined)Core options#
| Field | Default | Meaning |
|---|---|---|
| position | {x:0,y:0,z:0} | Socket position in parent body-origin local space. |
| rotation | {x:0,y:0,z:0,w:1} | Local Socket-frame quaternion; it must have nonzero length. |
| enabled | true | Whether the Socket can participate in matching and group conditions. |
| search_distance | 0.5 | Discovery distance; a pair uses the smaller endpoint value. |
| position_tolerance | 0.01 | Maximum separation for capture without attraction. |
| rotation_tolerance | 5° | Shortest quaternion angle allowed; 180 ignores orientation. |
| cooldown | 0.25 s | How long both endpoints are blocked after disconnect. |
| connection_type | fixed | Male recipe: fixed, hinge, point, or swing_twist. |
| collision | true | Keeps or suppresses collision only for the connected body pair. |
| max_force / max_torque | undefined | Optional positive break limits; support depends on connection type. |
Local to world transform#
World position is the local position rotated by the body rotation and added to the body world position. World rotation is body quaternion multiplied by Socket local quaternion. get_transform() computes the current {position, rotation}.
var frame = socket.get_transform();
if (!is_undefined(frame)) show_debug_message(frame.position.x);Compatibility and candidate selection#
- A pair must be male + female, have exactly the same nonempty type, be enabled, free, and outside cooldown.
- Sockets must belong to different bodies in the same managed world, with at least one Dynamic body.
- Candidates are globally ordered by distance, then angular error, then stable Socket IDs.
- An endpoint is atomically reserved for one candidate. A second redundant Socket constraint is not created for the same body pair.
Public state and methods#
| Member | Use |
|---|---|
| id, body, polarity, compatibility_type | Socket identity and ownership. |
| candidate / connection / group | Current partner, shared connection, and group owner; otherwise undefined. |
| get_transform() / is_valid() | Current world frame and live parent/handle/world validation. |
| is_connected() | Returns true only for a valid Socket, valid connection, and actually valid constraint; candidate, attraction, and cooldown return false. |
| set_enabled(value) | Enables or disables matching; it does not disconnect an existing connection. |
| disconnect() | Destroys the connection, restores pair collision, and starts cooldown. |
| destroy() | Destroys its group/connection and removes the Socket. |
Current project integrations#
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.
| Symbol / owner | Signature | Operation contract |
|---|---|---|
| jolt_socket | jolt_socket(body, polarity, type, options=undefined) | Live managed Body, male/female, nonempty compatibility_type, options. JoltSocket/undefined. Local position/rotation, +Z forward; matching orientations connect. Defaults fixed, collisiontrue, enabledtrue, search.5m, tolerance.01m/5°, cooldown.25s, attractionfalse. Recipe/positive break force N and torque N·m belong to male; Point has no torque limit. |
| JoltSocket.destroy | JoltSocket.destroy() | Boolean; disconnect removes connection and starts cooldown, not the body. Destroy also removes any group and invalidates socket; repeated calls true. |
| JoltSocket.disconnect | JoltSocket.disconnect() | Boolean; disconnect removes connection and starts cooldown, not the body. Destroy also removes any group and invalidates socket; repeated calls true. |
| JoltSocket.get_transform | JoltSocket.get_transform() | World transform/undefined; is_valid Boolean owner/world; is_connected also checks live constraint, not just a stored candidate. |
| JoltSocket.is_connected | JoltSocket.is_connected() | World transform/undefined; is_valid Boolean owner/world; is_connected also checks live constraint, not just a stored candidate. |
| JoltSocket.is_valid | JoltSocket.is_valid() | World transform/undefined; is_valid Boolean owner/world; is_connected also checks live constraint, not just a stored candidate. |
| JoltSocket.set_enabled | JoltSocket.set_enabled(value) | Coerces to Boolean, clears candidate and returns valid flag. Neither creates nor automatically destroys an existing connection. |