Collision Filtering

Controls simulation pairs, constraint pairs, and raycast query results.

The extension provides three independent filtering layers: the world collision-layer matrix, per-constraint pair suppression, and raycast layer/body filters.

Simulation pair filtering#

var player = jolt_layer_create("Player");
var trigger = jolt_layer_create("Trigger");

jolt_layer_set_collision(player, trigger, true);
jolt_layer_set_collision(trigger, trigger, false);

The 32×32 user-layer matrix is symmetric and defaults to enabled. A pair disabled here produces neither physical response nor body contact events. Sensors obey the same matrix. Static-vs-Static pairs are additionally rejected by the broad phase.

Constraint pair filtering#

var joint = jolt_hinge(body_a, body_b, anchor_x, anchor_y, anchor_z,
    axis_x, axis_y, axis_z, {collision:false});

joint.set_collision_enabled(true);
var enabled = joint.get_collision_enabled();

Constraints between two bodies have their own pair filter. High-level constraint creators default collision to true; options.collision=false disables only the connected body pair. The setting can be changed later. World constraints have no second body and report collision disabled.

Raycast filters#

jolt_raycast(x1, y1, z1, x2, y2, z2, filter)
jolt_raycast_all(x1, y1, z1, x2, y2, z2, filter)

Mask mapping#

JoltLayer handles are 1-based while the mask is zero-based: layer handle 1 uses bit 0, handle 2 uses bit 1, and so on. The high-level layer-array form builds this mask and removes duplicates. Every layer and ignored body must still be valid.

Raycast result behaviour#

• The endpoint form requires two different finite points.
• jolt_raycast() returns the closest hit or a hit=false struct.
• jolt_raycast_all() returns hits sorted by distance.
• At most one closest hit per body and at most 256 hits are returned.
• Sensors are included unless excluded by layer or ignored body.
• Mesh raycasts ignore back faces.
• A hit contains body, body_handle, entity, position, normal, fraction, distance, error_code, and error_message.

Example#

var query = {
    layers: [world_layer, trigger_layer],
    ignore: player_body
};

var hits = jolt_raycast_all(0, 0, 2, 20, 0, 2, query);

Low-Level / Advanced API#

jolt_world_raycast_filtered(world, ox, oy, oz, dx, dy, dz,
    max_distance, layer_mask=0, ignore_body=0)
jolt_world_raycast_all(world, ox, oy, oz, dx, dy, dz,
    max_distance, layer_mask=0, ignore_body=0)
jolt_world_constraint_set_collision_enabled(world, constraint, enabled)
jolt_world_constraint_get_collision_enabled(world, constraint)

Low-level raycasts use origin + direction + maximum distance rather than two endpoints.