Sensors

Attach a non-solid box sensor to a moving body and read contact events.

Verified against the project sources on 19 September 2026.

Syntax#

jolt_asset_get_sensor(asset, sensor_ref);
jolt_asset_create_sensor(asset, sensor_ref, owner_body, [options]);

Factories return undefined on failure; inspect jolt_get_error() immediately. Authoring lookups return independent validated record copies. A reference is a canonical UUID or an exact, case-sensitive Key. Body owners must be live managed bodies in the current world.

A Sensor Box has id, key, optional name, position, rotation and full size[3]. Creation returns a standard JoltBody: kinematic, sensor:true, allow_sleeping:false. A static, kinematic or dynamic collision body may own it; another sensor cannot. Each call creates an independent instance.

World frame = current Body origin transform × authored local transform. The center of mass is not the authoring origin. Positions use metres and rotations use normalized XYZW quaternions. Refresh snapshots as the body moves.

Example#

// Create: asset contains a Sensor Box with Key "cargo".
cargo_sensor = jolt_asset_create_sensor(asset, "cargo", body_vehicle);
// Step: read after the controller has called jolt_update().
if (!is_undefined(cargo_sensor)) {
    var events = cargo_sensor.get_collisions();
    for (var i = 0; i < array_length(events); ++i) {
        var e = events[i];
        if (e.other_body == body_vehicle) continue;
        if (e.type == JOLT_COLLISION_ENTER) show_debug_message("Enter");
    }
}

Synchronization and lifetime#

jolt_update() synchronizes sensors before and after each fixed substep; managed owner position/rotation setters also synchronize immediately. Raw jolt_step() does not run these hooks. Do not change the attached sensor's motion, sensor flag, velocity or world transform yourself. sensor.destroy() removes one sensor; owner.destroy() removes its sensors; jolt_stop() cleans all.

Contacts retain ENTER/STAY/EXIT semantics and can arrive per subshape pair. This is discrete detection, so a fast complete pass can be missed. Owner contacts are not automatically excluded. Use layer collision rules or filter events. deactivate() sleeps a body; set_sensor(false) turns it solid. Neither is a sensor enable switch.

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.