Introducing Shapecasts

[subcritical]

Today we’re officially releasing two new APIs for the Roblox Engine:

• WorldRoot:Blockcast
• WorldRoot:Spherecast

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

[FroDev1002 (FroDev)]

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!

[SomeFedoraGuy (Him)]

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

[XenoDenissboss1]

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.

[Hawaiikaiboy02 (Hawaiikaiboy)]

@subcritical

Area of Effect: Devs have to cast hundreds of rays to cause splash damage, or settle with

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?

[xSwezan]

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

[Altomegaflowey844 (Silence)]

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

[XenoDenissboss1]

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)

[StyledDev]

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

[Varonex_0 (Varonex)]

What a Wonderful update here !

[HumanMop]

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

[Kave_Dev (pwnedbypro)]

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

[Native_Clouds (Clouds)]

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).

[TrippTrapp84]

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.

[HenriqueGabrielLol (Aspecty)]

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!

[homermafia1]

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.

[colbert2677 (ImagineerColbert)]

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:

Upgraded, Improved, and Faster Raycasts

Yeah, pretty much in the name. Think raycasting but you aren’t restricted to a line. Shapecasting would be really good for our use case since we have mesh deformed enemies as well as enemies that perform large scale attacks. Since we don’t have shapecasts, we need to rely on other methods: several hundred or thousand raycast points, Touched (sort of ew to rely on physics for hitboxes), information from Bones to create raycast points and so on. Our current method of slapping attachments all ove…

[C_Corpze (Corpze_TheDeadestOne)]

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!

[VSCPlays]

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

@subcritical

Maximum ray length: 1024 studs

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

@subcritical

Maximum shape size: 128 studs

That’s like 16x smaller than the maximum part size, though Raycasts are invisible which isn’t a issue for me 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?