Utility Scripts · Sockets
Attraction and Alignment
A bounded physical controller moves a Dynamic male toward the female and captures only after it has settled.
Attraction is opt-in. When false, connect-on-alignment behavior remains. When true, it uses world position error, shortest-path quaternion error, and relative motion at the actual Socket points.
Attraction settings#
| Field | Default | Meaning |
|---|---|---|
| attraction | false | Enables physical attraction on the male endpoint. |
| attraction_force | 100 | Total force cap applied at the male center of mass. |
| attraction_torque | 20 | Total orientation torque cap. |
| attraction_stiffness | 100 | Position response before the force cap. |
| attraction_damping | 20 | Damping ratio control; the default is at least critically damped. |
| attraction_rotation_stiffness | 20 | Rotation response. |
| attraction_rotation_damping | 5 | Angular damping ratio control; at least critical by default. |
Precise lock conditions#
| Field | Default | Check |
|---|---|---|
| lock_position_tolerance | 0.0005 | Maximum Socket-point separation. |
| lock_rotation_tolerance | 0.1° | Maximum Socket-frame orientation error. |
| lock_linear_speed | 0.01 | Maximum relative point speed. |
| lock_angular_speed | 0.02 rad/s | Maximum relative body angular speed. |
Capture uses the stricter of the normal endpoint tolerance and male lock tolerance. This prevents any connection type from preserving a visible creation-time alignment error.
Controller behavior#
- Linear damping is derived from mass and stiffness as critical damping, using a stable implicit discrete form.
- Rotation is solved independently along the true principal inertia axes and transformed back to world space.
- Gravity feed-forward reduces sag but still shares the attraction_force budget.
- Neither stiffness nor caps scale with mass, so heavy bodies respond more slowly under the same settings.
- A moving host is supported because point velocity includes its linear and angular motion.
Tuning order#
- Choose attraction_force and attraction_torque for the expected mass and geometry first.
- If the object barely moves, inspect obstacles, collision, and caps before loosening lock tolerances.
- Higher stiffness reacts faster; higher damping brakes more. Values below the default ratio do not lower damping below critical.
- Use a regular fixed timestep and reasonable collision substeps.