Introducing Shapecasts

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.Position represents the intersection between the hit part and the swept shape.
  • RaycastResult.Normal represents the normal vector of the surface at the hit point.
  • RaycastResult.Distance represents how far the shape had to travel. The “final” position of the swept shape can be found as direction.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

763 Likes
Raycast Hitbox 4.01: For all your melee needs!
ClientCast - A Client-based, Idiosyncratic Hitbox System!
About Shapecast
Chickynoid, server authoritative character replacement
[Update] Changes to Asset Privacy for Audio
Detecting water touching
Slow projectile collision
Hitbox for Fast Moving Objects
Better way to do hitboxing?
Introducing generalized shapecasts
Making hoverbike capable of traversing slopes
Shapecasts vs Spatial queries performance and reliability wise
Raycast in a 360 degree angle
Shapecast vs Raycast performance differences?
I do not completely understand raycasting projectiles
Checking if a player enters a zone
How to make a trail with parts?
Capture the point system player detection
Pantograph raising and lowering system
Need a method for big projectile hit detection
Release Notes for 637
Blockcast not consistently detecting parts and terrain
[SOLVED] How to detect if an object/character is being shined on with a spotlight
Raycast in a sphere?
Where can I find information on shape casts
Where can I find information on shape casts
Shapecast vs Raycast performance differences?
[CLOSED] Submit Your Work for Our 2023 Year in Review!
workspace:Blockcast() is acting weird
Is there a more consistent way to do collisions?
Feedback on bullet system
Make raycast detect bottom surface of terrain
Position of contact on a .Touched function?
Grabbing system with Cframe
How do i clone a part on mesh position
Shapecasts Unable To Detect Objects
Raycast Hitbox 4.01: For all your melee needs!
Run Loop When None Player Left Touching a Part
Pathfinding to avoid pathing in a player’s field of vision
2023 Year in Review: Extreme Wall Running, Rhythmic Ocean Waves, Demonic Heads, and More!

This topic was automatically opened after 11 minutes.

This is really amazing!
Now I can detect in bigger areas!

This helps cause I am making an combat game, and the detection is pretty small cause of how small the ray cast is!

49 Likes

Thank god it’s out! When will we be expecting Conecasts?

64 Likes

Quite useful new raycast methods! Amazing work! However on the topic of performance, would it be possible for us to be seeing further performance improvements for standard raycasts too? Perhaps even mark FilterDescendantsInstances property of RaycastParams to “Safe” for usage within Parallel luau as right now due to this limitation of the property being marked unsafe, i have to resort to some less favorable methods to get raycasts to bypass some specific instances.

16 Likes

So what is the performance difference between using this vs creating a explosion instance at the target point and using “explosion.Hit”? Im all down for a better way, but is this meant to be a replacement for this kind of effect, or to do it along a raycast rather then the end point?

13 Likes

This is absolutely amazing! The amount of use cases this will have is crazy :smiley:
Good job guys!

11 Likes

They also fixed the weird studio glitch were models or basically anything moved inside the studio would disappear. But this update is pretty considering Ray casting can sometimes be small for stuff like combat games

15 Likes

I mean using a simple blockcast vs using entirely a new instance with a event would have some probably insane performance differences. Think about it, for a blockcast, youre kinda just firing a big blocky ray while for explosion.Hit, youre creating a new part that roblox must set up all its properties along with then using some of its lua events.

(nvm i read it wrong its not about using a part but you get the point, youre still kinda creating more instances and events while blockcasts just do a simple big ray)

10 Likes

Long awaited!
Can’t wait to see what comes of this! :smiley:

9 Likes

What a Wonderful update here !

8 Likes

Damn, just when I make a comment about y’all forgetting this feature, you come out with it. Excited to try it out.

9 Likes

This is amazing and very useful update, i can now do even more performant hitboxes :smiley:

6 Likes

Cool, even features points! Which I can reduce inertia, and remove unnecessary pushing from single cell character (bean hitbox), to move in environment, with better performance, including 200 cells (bean hitbox).

8 Likes

Looked at this feature because I found the API listing before it got announced, I was almost scared there was no way to find what position the shape ended at! super happy it got explained though. Awesome work engineers, thank you everyone who worked on this.

8 Likes

This is INSANE, probably one of the best features you guys added this year, it will help me and other devs a LOT with stuff like hitboxes, thank you all so much for doing this!

10 Likes

That is a really nice addition !
Could there also be a method for cylinders in the future ? This could really help me for a feature for which I am using a classic line raycast, which causes some inconveniences.

11 Likes

Although I would like to see pill casting in the future, this feature is incredibly important for my experience which relies on raycasting to create melee hitboxes (we’ve also released our implementation as a resource without the internal adjustments to fit our experience specifically). Big thank you to the sim core team for always delivering.

Some information from my previous post about shapecasting and why it’s big for me:

16 Likes

Omg I’ve been waiting so long for these.
FINALLY I can make a raycast-based physics library!

Physics objects that bounce and ricochet around using various shapes and rays.
This will be sooo cool and useful for that!

4 Likes

Now this is some quite useful raycasting, I sometimes use raycasting for getting distance between the player and the mouse target’s position, etc.

That’s like half the maximum part size, My game will be over 25K square studs, and Mesh Instances (not MeshParts) can go infinity and beyond

That’s like 16x smaller than the maximum part size, though Raycasts are invisible which isn’t a issue for me :wink: though is the Radius argument the size of the shape size?

Though I’m intrested to see PartCasts, I’m willing to use parts to raycast without having to get it’s CFrame, It should be like this

WorldRoot:PartCast(
   part: BasePart,
   direction: Vector3,
   params: RaycastParams?
): RaycastResult?
4 Likes