Impact Sensor

Detect a new rigid-body impact for sounds, particles or approximate gameplay damage.

Impact Sensor is an opt-in JoltBody feature. It stores the latest relevant impact snapshot; it is not a trigger, a collision event queue or a continuous force meter.

Create and enable#

// Create event, after the central controller has called jolt_start().
last_impact_sequence = 0;
body = jolt_box_create_dynamic(0, 0, 5, 1, 1, 1, {
    mass: 2,
    impact_sensor: {min_value: 10}
});
if (is_undefined(body)) show_debug_message(jolt_get_error_message());

What counts as an impact?#

Only a new non-sensor OnContactAdded contact is considered. Closing speed at the contact must be at least 0.05 world units per second and EstimateCollisionResponse must predict a positive normal impulse. min_value filters the sum of normal contact impulses, measured in N*s.

OnContactPersisted does not overwrite the snapshot: resting and sliding on an existing contact do not keep retriggering it. If several candidates occur in one native physics step, the strongest is stored and sequence increments once. One jolt_update() may execute several steps; the retained snapshot is the latest committed impact, not necessarily the strongest over the whole update.

Result fields#

React once after physics updates#

// After the central jolt_update(); do not add a second physics update here.
if (!is_undefined(body) && body.is_valid()) {
    var impact = body.get_impact_sensor();
    if (jolt_has_error()) {
        show_debug_message(jolt_get_error_message());
    } else if (impact.hit && impact.sequence != last_impact_sequence) {
        last_impact_sequence = impact.sequence;
        show_debug_message("Impact: " + string(impact.value) + " N*s");
        // Play one sound or spawn one particle effect here.
    }
}

Reset and lifetime#

Before the first impact, hit is false, sequence is zero and numeric fields are zero. The snapshot persists until replaced or reset. Changing enabled from true to false or false to true clears it. Calling set_impact_sensor(true, threshold) while already enabled only changes the threshold; it does not clear the stored impact.

// Explicitly begin a new recording session on a validated body.
if (body.set_impact_sensor(false) && body.set_impact_sensor(true, 10)) {
    last_impact_sequence = 0;
} else show_debug_message(jolt_get_error_message());

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.