Your First Docking Connection

Build a physically attracted Fixed connection from two bodies and two Sockets.

The smallest setup contains two different bodies and a male/female pair with the same type. Inside their search range, the male approaches the female and creates a connection after settling precisely.

Complete example#

// Dynamic object that will be attracted.
var tool = jolt_box_create_dynamic(-1, 0, 1, 0.3, 0.3, 0.3, { mass: 2 });

// Static or Kinematic holder.
var holder = jolt_box_create_static(0, 0, 1, 0.4, 0.4, 0.4);

tool_socket = jolt_socket(tool, "male", "tool_mount", {
    position: { x: 0.3, y: 0, z: 0 },
    attraction: true,
    attraction_force: 150,
    attraction_torque: 30,
    connection_type: "fixed",
    collision: false
});

holder_socket = jolt_socket(holder, "female", "tool_mount", {
    position: { x: -0.4, y: 0, z: 0 }
});

Reading the example#

• The first jolt_socket argument is the parent JoltBody. The Socket follows its translation and rotation automatically.
• male and female are polarities. Automatic matching only considers opposite polarities.
• tool_mount is the compatibility type. Different types never become candidates.
• position is an offset in body-origin local space, not a world coordinate.
• Set connection_type, attraction, collision, and break limits on the male Socket recipe.

Update and state#

jolt_update(); // Also updates Sockets during fixed steps.

if (tool_socket.is_connected()) {
    var connection = tool_socket.connection;
}

tool_socket.disconnect(); // Programmatic disconnect.

If capture does not happen#

• Verify that physics is running and both bodies and Sockets are valid.
• Check matching types, opposite polarities, enabled state, and cooldown.
• Enable JOLT_DEBUG_SOCKETS and inspect the local offset and colored axes.
• search_distance controls discovery; position_tolerance is not the attraction range.
• The male body must be Dynamic for attraction. The female may be Dynamic, Kinematic, or Static.