Layer Filtering

Restricts a ray to selected user layers and optionally ignores one body.

Raycast filtering is separate from the simulation collision matrix. Disabling a layer pair with jolt_layer_set_collision() does not prevent a ray from querying either layer when its mask selects that layer.

Supported filter forms#

Layers and ignored body#

var hit = jolt_raycast(0, 0, 2, 20, 0, 2, {
    layers: [world_layer, interactable_layer],
    ignore: player_body
});

Mask precedence#

When an options struct contains mask, that value is used immediately and layers is ignored. Supply only one of those fields so the intended filter remains obvious.

// mask wins; layers is not combined with it.
var filter = {
    mask: interactable_mask,
    layers: [world_layer],
    ignore: player_body
};

Raw mask mapping#

JoltLayer handles are 1-based while mask bits are zero-based. Handle 1 maps to bit 0 and handle 32 to bit 31. Layer arrays construct this union automatically.

// Select layer handles 1 and 3: bits 0 and 2.
var mask = 1 | 4;
var hit = jolt_raycast(0, 0, 2, 20, 0, 2, mask);

Mask rules#

• A raw mask must be a finite, non-negative integer from 0 through 4294967295.
• Mask 0 means every user layer, not no layers.
• An empty layer array also becomes mask 0 and therefore queries all layers.
• A non-zero mask selects the union of its set bits.

Validation and lifetime#

• Every JoltLayer must be live when the query runs.
• ignore must be undefined or one live JoltBody in the active managed world.
• Destroyed or stale resources produce an error.
• The filter does not alter contacts, collision response, events or the layer matrix.

What the filter cannot express#

• Sensor state, motion type or active/sleeping state.
• GML user_data or entity identity.
• More than one ignored body.
• Triangle, material or compound-child selection.