Skip to main content

scene_queries_filters

It is common to exclude some colliders from being considered by a scene query. For example, a ray-cast performed for a character controller will usually want to skip the character itself. Sometimes, we may even want it to ignore both the character and any collider attached to a dynamic rigid-body, and ignore all sensors. To allow this filtering, most scene queries take several optional arguments that lets you describe what needs to be excluded. In particular, the arguments:

  • flags allows you to discard whole families of colliders based on their types or their parent types (e.g. exclude all sensors and all the colliders attached to a dynamic rigid-body).
  • groups is used to apply the collision group rules for the scene query. The scene query will only consider hits with colliders with collision groups compatible with this collision group (using the bitwise test described in the collision groups section).
  • exclude_collider is the handle of one collider the query must ignore.
  • exclude_rigid_body is the handle of one rigid-body with attached colliders the query must ignore.
  • predicate is a user-defined closure to apply any filtering rule. This can be used if the other filtering options above are not flexible enough.

Here is an an example of usage of the query filters with ray-casting:

let ray = new RAPIER.Ray({ x: 1.0, y: 2.0 }, { x: 0.0, y: 1.0 });
let maxToi = 4.0;
let solid = true;

let filterFlags = QueryFilterFlags.EXCLUDE_DYNAMIC;
let filterGroups = 0x000b0001;
let filterExcludeRigidBody = player_rigid_body;
let filterPredicate = (collider: Collider) => data.get(collider.handle) == 10.0;

let hit = world.castRay(ray, maxToi, solid, filterFlags, filterGroups, null, filterExcludeRigidBody, filterPredicate);
if (hit != null) {
    // Handle the hit.
}