Skip to main content

scene_queries_shape_casting

Shape-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 and filter arguments in the ray-casting section.

There is only one shape-casting method: QueryPipeline::cast_shapeRapierContext::cast_shapeWorld.castShape. This method has similar arguments as QueryPipeline::cast_rayRapierContext::cast_rayWorld.castRay 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):

<load path='/2d/rust/examples/rs_scene_queries2.rs' marker='Shapecast' />
 
<load path='/2d/bevy/examples/scene_queries2.rs' marker='Shapecast' />
 
<load path='/2d/javascript/src/snippets/scene_queries.ts' marker='Shapecast' />

The result of the shape-casting includes the handle of the first collider being hit, as well as detailed information about the geometry of the hit:

  • hit.toi: indicates the time of impact between the shape and the collider hit. This means that after travelling a distance of shape_vel * hit.toishapeVel * 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.
  • hit.witness1: 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.witness2: indicates the contact point when the cast shape and the collider are touching, expressed in the local-space of the cast shape.
  • hit.normal1: indicates the normal at the contact point hit.witness1, expressed in the local-space of the collider hit by the shape.
  • hit.normal2: indicates the normal at the contact point hit.witness2, expressed in the local-space of the cast shape.