Multi-socket Groups

Several explicit pairs determine correct placement while the group creates only one SocketConnection and one constraint.

jolt_socket_group(pairs, options=undefined) needs at least two unique male/female pairs between the same bodies. Every required pair must pass compatibility, availability, and tolerance checks in the same fixed step.

Defining a group#

var mount = jolt_socket_group([
    { male: tool_left,  female: host_left  },
    { male: tool_right, female: host_right }
], {
    primary_pair: 0
});

// The connection appears only after both pairs align together.
if (is_struct(mount.connection)) {
    show_debug_message("Tool connected");
}

Creation rules#

• Each array entry is {male, female}; polarities are required and endpoints cannot repeat.
• Every male belongs to body A and every female to body B in the same managed world.
• An endpoint cannot already belong to another group or connection. At least one body must be Dynamic.
• A temporarily incompatible or disabled pair keeps the group valid but prevents activation and capture.

Primary pair#

primary_pair is the only option and defaults to index 0. Its male owns connection_type, attraction, collision, constraint parameters, and break limits. Its female supplies the final anchor/frame. Other pairs are placement conditions.

Group alignment#

• Without attraction, all pairs must pass their own stricter endpoint position and rotation tolerances.
• With attraction, all pairs must also pass the primary male precise lock and relative-speed limits.
• The controller averages position, rotation, and velocity errors, then applies force and torque once.
• attraction_force and attraction_torque are total group caps and are never multiplied by Socket count.

Observable state#

Current limits#

• There are no 2-of-3 rules, optional pairs, automatic pair discovery, or multiple result constraints.
• Collinear points do not determine twist if Socket frames and rotation tolerances ignore orientation.
• Inconsistent pair layouts, obstacles, or insufficient force can prevent capture; the system never teleports geometry.

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.