Entity / User Data

Associates a JoltBody with arbitrary GML data or a GameMaker instance.

user_data is stored only by the high-level GML wrapper. Native Jolt user data contains the safe generational body handle, not your struct or instance ID.

Arbitrary data#

body.set_user_data({kind:"Door", id:17, locked:false});
var data = body.get_user_data();

Any GML value can be stored, including a struct, instance, string, array, or undefined. set_user_data() returns true. The value is not serialized, copied into C++, or automatically freed independently of ordinary GML references.

Binding a GameMaker instance#

body.bind_instance(instance, use_as_user_data=true)
body.unbind_instance()
body.sync()

Fields written by sync#

instance.x
instance.y
instance.z
instance.jolt_rotation_x
instance.jolt_rotation_y
instance.jolt_rotation_z
instance.jolt_rotation_w

Entity values in queries#

• World contacts expose user_data_a and user_data_b.
• Per-body contacts expose entity and other_entity.
• Raycast hits expose entity.
• If a raw handle cannot be resolved to a live managed JoltBody, the related entity value is undefined.
• Changing user_data changes future mapped events and query results; Native collision state is unaffected.

Example#

var crate = jolt_box_create_dynamic_for_instance(id, 1, 1, 1, {mass:2});

// Step event after jolt_update()
crate.sync();

var hit = jolt_raycast(0, 0, 2, 10, 0, 2);
if (hit.hit && !is_undefined(hit.entity)) {
    show_debug_message("Hit entity " + string(hit.entity));
}

jolt_box_create_dynamic_for_instance(instance, width, depth, height, options) creates a Dynamic Box at instance.x/y/z and binds it. If the instance has no z variable, z defaults to 0.

Lifetime and safety#

bind_instance() rejects a destroyed or invalid instance. sync() fails when no live owner is bound. Destroying a body clears its collision data but a user-held stale JoltBody may still keep ordinary GML values reachable until your own references are released.