Grip: character anchoring

Two virtual hands attach a Character to a Static or Kinematic surface.

First use#

Grip moves the character relative to hand anchors; Grabber / Carry instead holds an object in front of the character. One Character supports one Grip controller. Dynamic anchor bodies are not supported.

wall.set_grip_enabled(true);
grip = jolt_grip(player);
grip.set_camera(o_control_bbmod_camera);
grip.set_distances(0.65, 1.5, 2);
// End Step, after the camera update:
grip.update_controls();
// Clean Up:
// grip.destroy();

player must be a live JoltCharacter. The camera exposes camera.Position, camera.Target and mouse_locked. Left/right mouse buttons control the corresponding hands by default. Use acquire or update_hand for custom input; do not process automatic and manual input twice.

Distances and movement#

Hands and prospective target#

JOLT_GRIP_LEFT = 0, JOLT_GRIP_RIGHT = 1; BOTH = −1 is only accepted by operations supporting both hands. get_attached(hand) returns Boolean. get_position, get_rotation, get_world_normal and other attached values return undefined while detached. Positions are world {x,y,z}, rotations are quaternions {x,y,z,w}. Rotation +Z follows the surface normal; +X follows camera right at acquisition.

var hand = grip.get_hand(JOLT_GRIP_LEFT);
if (is_struct(hand) && hand.attached) {
    hand_model.Matrix = model_matrix_from_transform(
        hand.world_position, hand.world_rotation);
}
var target = grip.get_target();
if (!is_undefined(target)) {
    preview.Matrix = model_matrix_from_transform(target.position, target.rotation);
}

get_target(hand=JOLT_GRIP_LEFT) performs one current camera raycast, returning {position,world_normal,rotation} or undefined. can_grip only tests eligibility; it does not acquire. Read get_hand or get_target once for several values; separate getters take separate snapshots/raycasts. Toggle model visibility in your renderer.

Moving anchors and limitations#

A Static anchor must not move after acquisition. Kinematic anchors update their local position, normal and rotation and supply point velocity. Teleporting, shape/motion changes, disabling grip_enabled, destroyed bodies, collision filters or exceeding break can release a hand. Dynamic Grip, hand reaction forces, stamina and IK are not implemented.

Diagnostics and lifetime#

get_status returns both hands and reasons; get_reason(hand) explains rejection or release. Following an update_hand rejection, release the input before retrying. release() releases both hands; destroy() ends the controller. Character destruction releases it. set_debug, set_debug_xray, set_debug_limits and set_debug_labels control diagnostics; draw_debug_gui is not public API.

• Grabber / Carry›
• Creating a Character›

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.

Complete API declarations#

Declarations match the production GML sources. A value after = marks an optional argument. This is a signature inventory; the guide sections describe meaning, units and limitations. The type before a dot identifies the method owner, not a global function.