# Scene queries

Scene queries are geometric queries that take all the colliders of the physics world into account. These queries are available through the QueryPipeline.

## #

Ray-castingRay-casting is a geometric query that finds one or several colliders intersecting a half-line. Ray-casting is an extremely common operation that covers a wide variety of use-cases: firing bullets, character controllers, rendering (for ray-tracing), etc.

A ray is defined by its origin and its direction: it can be interpreted as a single point moving in a straight line towards the ray direction.

##### info

In addition to the ray geometric information, ray-casting method allow additional control over the behavior of the ray cast like limiting the length of the ray and ignoring some colliders. See the detailed ray-cast arguments description after the next example.

There are multiple ray-casting methods yielding more or less detailed results (see example bellow). The more results you get, the more computationally expensive the ray-cast will be.

- Example 2D
- Example 3D

Aside from the ray being cast, all these ray-casting methods take a few extra parameters for controlling the behavior of the ray-cast:

: is the maximum "time-of-impact" that can be reported by the ray-cast. The notion of "time-of-impact" refer to the fact that a ray can be seen as a point starting at`max_toi`

`ray.origin`

moving at a linear velocity equal to`ray.dir`

. Therefore,`max_toi`

limits the ray-cast to the segment:`[ray.origin, ray.origin + ray.dir * max_toi]`

.: this argument controls the behavior of the ray-cast if`solid`

`ray.origin`

is inside of a shape: if`solid`

is`true`

then the hit point will be the ray origin itself (`toi = 0.0`

) because the interior of the shape will be assumed to be filled with material. If`solid`

is`false`

then the shape will be assumed to have an empty interior and the hit point will be the first time the ray hits the shape's boundary. The following 2D example illustrates the difference between the two scenarios. The ray is in green and the resulting hit point circled in red:

: just like colliders, the ray is given a collision group. The ray-cast will only test intersections with colliders with collision groups compatible with the ray's collision group (using the bitwise test described in the collision groups section).`groups`

: if collision groups are not flexible enough, a custom closure can be given optionally. The ray-cast will only test intersection with colliders for which the`filter`

`filter`

closure returns`true`

.

## #

Shape-castingShape-casting (aka. sweep tests) is the big brother of ray-casting. The only difference with ray-cast is that instead of being a point travelling along a straight line, we have a complete shape travelling along a straight line. This is typically used for character controllers in games to determine by how much the player can move before it hits the environment.

##### info

Just like ray-casting, it is possible to control the behavior of the shape-casting like limiting the distance
travelled by the shape cast, and ignoring some colliders. See the details about the `max_toi`

, `groups`

and
`filter`

arguments in the ray-casting section.

There is only one shape-casting method: `QueryPipeline::cast_shape`

. This method has similar arguments as
`QueryPipeline::cast_ray`

except that the `Ray`

is replaced by three arguments:
the **shape** being cast, the **initial position** of the shape (this is analog to `ray.origin`

) and the **linear velocity** the
shape is travelling at (this is analog to `ray.dir`

):

- Example 2D
- Example 3D

The result of `QueryPipeline::cast_shape`

includes the handle of the first collider being hit, as well as
detailed information about the geometry of the hit:

: indicates the time of impact between the shape and the collider hit. This means that after travelling a distance of`hit.toi`

`shape_vel * hit.toi`

the collider and the cast shape are exactly touching. If`hit.toi == 0.0`

then the shape is already intersecting a collider at its initial position.: indicates the contact point when the cast shape and the collider are touching, expressed in the local-space of the collider hit by the shape.`hit.witness1`

: indicates the contact point when the cast shape and the collider are touching, expressed in the local-space of the cast shape.`hit.witness2`

: indicates the normal at the contact point`hit.normal1`

`hit.witness1`

, expressed in the local-space of the collider hit by the shape.: indicates the normal at the contact point`hit.normal2`

`hit.witness2`

, expressed in the local-space of the cast shape.

## #

Point projectionPoint projection will either project a point on the closest collider of the scene (`QueryPipeline::project_point`

),
or will enumerate every collider containing given point (`QueryPipeline::intersections_with_point`

).

- Example 2D
- Example 3D

The `solid`

, `group`

and `filter`

arguments are used to control the way point-projection works: by ignoring the shape
interiors and/or ignoring some colliders. See their description on the ray-casting section.

## #

Intersection testIntersection tests will find all the colliders with a shape intersecting a given shape. This can be useful for, e.g., selecting all the objects that intersect a given area. There are two kind of intersection tests:

- The exact intersection test
`QueryPipeline::intersections_with_shape`

searches for all the colliders with shapes intersecting the given shape. - The approximate intersection test
`QueryPipeline::colliders_with_aabb_intersecting_aabb`

searches for all the colliders with an AABB intersecting the given AABB. This does not check if the actual shapes of these colliders intersect the AABB.

##### info

See the ray-casting section for details about intersection tests between a ray and the colliders on the scene. And see the point projection section for details about the intersection test between the colliders and a point.

- Example 2D
- Example 3D

Use the `group`

and `filter`

arguments to exclude some colliders from these intersection tests.
See their description on the ray-casting section.