Today we’re officially releasing two new APIs for the Roblox Engine:
You may know these as swept volume queries, thick raycasts, continuous collision detection, or various other names across the industry. We call them Shapecasts.
Shapecasts are closely related to raycasts – Raycasts push a point along a line, while shapecasts push a 3D shape and find the first hit point.
Use cases
Some examples of when you might find these useful:
-
Character controllers: Some Lua-based controllers cast lots of rays around the character to find suitable ground plane. We can be smarter about inferring the ground plane with shapecasts and collision groups.
-
Fast-moving projectiles: Raycasts are fine for small projectiles like bullets, but the movement of larger missiles with volume can’t be accurately modeled with rays.
-
Area of Effect: Devs have to cast hundreds of rays to cause splash damage, or settle with potential gaps from lower-fidelity approximations. Shapecasts can give more accurate volumetric checks.
-
Touch interaction: Finding the part under your finger on a touchscreen tends to be more accurate with a spherecast than a raycast.
API
Documentation for Blockcast
Documentation for Spherecast
WorldRoot:Blockcast(
cf: CFrame,
size: Vector3,
direction: Vector3,
params: RaycastParams?
): RaycastResult?
WorldRoot:Spherecast(
pos: Vector3,
radius: number,
direction: Vector3,
params: RaycastParams?
): RaycastResult?
-
RaycastResult.Positionrepresents the intersection between the hit part and the swept shape. -
RaycastResult.Normalrepresents the normal vector of the surface at the hit point. -
RaycastResult.Distancerepresents how far the shape had to travel. The “final” position of the swept shape can be found asdirection.Unit * result.Distance
Performance
Performance is close to a raycast for a 0,0,0 size shapecast, with some exceptions caused by differences in how we traverse 3D space. This is because a 0,0,0 size shapecast is roughly equivalent to a raycast.
From there, performance degrades according to the size of the shape and the length of the cast.
Limitations
Firstly, shapecasts do not return hits with parts that they already collide with.
Secondly, for performance reasons, we impose limitations on size and length:
- Maximum ray length: 1024 studs
- Maximum shape size: 512 studs
Passing a shape that’s too big or a ray that’s too long will give you an error message with the current length limitations. We plan to raise both of these numbers over time as we improve the performance of the shapecast internals.
Finally, shapecasts do not use a margin yet – In other words, casting a shape against a part that is infinitesimally close will not register as a hit. We will be adding tolerances to fix this case.
We’re excited for developers to get their hands on these! Some of you have noticed that shapecasts have been silently enabled on production for a few weeks while we’ve fixed corner cases and collected feature requests and bug reports.
Feel free to share your thoughts here or as a dedicated thread - We’re always happy to fix any issues you find or look into new requests.
Thanks,
The Physics Team
though is the