Introducing OverlapParams - New Spatial Query API

Updates Announcements
,
1

We are adding new WorldRoot (Workspace) APIs for performing spatial queries on BaseParts. It’s never been easier to figure out what Parts are within a given box, radius, or other Part!

New Spatial Queries

Here are three new functions that can be used:

Objects WorldRoot:GetPartBoundsInBox(CFrame cframe, Vector3 size, OverlapParams overlapParams)

  • Returns a table of all BaseParts whose bounding boxes overlap the given box at cframe and size. cframe is for the center of the box, and orientation is taken into account.

Objects WorldRoot:GetPartBoundsInRadius(Vector3 position, float radius, OverlapParams overlapParams)

  • Returns a table of all BaseParts whose bounding boxes overlap the given sphere at position and radius.

Objects WorldRoot:GetPartsInPart(PartInstance part, OverlapParams overlapParams)

  • Returns a table of all BaseParts who overlap the given part. The given part must be present in the same WorldModel (workspace) as the parts you want to query. CanCollide/CanTouch on the given part are not considered, just the Part’s geometry.

A key thing to note with these is the Box and Radius overlap queries will only check against Part bounding boxes (the blue box shown when you select a Part). This makes them pretty fast to use. The Part overlap query will do a full geometry collision check, so it is more accurate. Later on we may add more overlap queries with new geometry, and of varying levels of detail.

OverlapParams

What is this extra “OverlapParams” parameter? It’s a new parameter object with a set of properties used to define rules for the overlap query to follow. It works like RaycastParams, and even shares many of the same properties.

  • Objects FilterDescendantsInstances - An array of objects whose descendants will be used in filtering.
  • RaycastFilterType FilterType - RaycastFilterType.Whitelist or RaycastFilterType.Blacklist. Determines how the FilterDescendantInstances is used. Blacklist will skip the FilterDescendantInstances, and Whitelist will exclusively include them.
  • int MaxParts = 0 - The maximum amount of parts to be returned by the query. The process simply early outs once this is met. (0 is infinite)
  • string CollisionGroup = "Default" - The collision group the region check is performed on. Parts set to not collide with this group will be ignored.

Out With The Old

With these new functions, the following “Region3” based functions are all deprecated, and should not be used in new work:

  • Workspace:FindPartsInRegion3
  • Workspace:FindPartsInRegion3WithIgnoreList
  • Workspace:FindPartsInRegion3WithWhiteList
  • Workspace:IsRegion3Empty
  • Workspace:IsRegion3EmptyWithIgnoreList

Additionally, WorldRoot:GetPartsInPart can be used in place of Part:GetTouchingParts, and is a better choice most of the time. However, a few niche cases prevent us from deprecating GetTouchingParts at this time.

FAQ

599 Likes
2

Nice, people can finally get rid of this hack in their code bases now: Simple trick to make GetTouchingParts work with non-CanCollide parts

Thanks for this!

81 Likes
4

I’m very excited to use these in my code! Do you mind clarifying on the “niche use cases” that :GetTouchingParts could offer over GetPartsInPart?

15 Likes
5

Possibly will use someday. That’s great although!

5 Likes
6

All I can say is WOW! It is such perfect timing as well since I am working on a placement system, however must I ask, how much more performant is this over region3? Would it be better to use this over gettouchingparts?

19 Likes
7

This feels very similar to the raycast API, which definitely makes things easier. Unrelated, but is the CanQuery property coming soon after this?

Edit: Is there any performance difference between GetPartsInPart and GetTouchingParts?

11 Likes
8

As a developer who uses Workspace:FindPartsInRegion3(), WorldRoot:GetPartsInPart() only require the part, YAY! also, would this replace the functionality of modules like ZonePlus?

10 Likes
9

Great to see, glad this is here now! Will be using it in my current project to replace any heavy use of GetTouchingParts!

7 Likes
10

Seems so, you only need to pass a part and it will return whatever is overlapping it (inside it in some way, doesn’t need to be fully in)

6 Likes
11

Awesome, I could definitely see this being helpful for developers; especially new ones who are confused by all the methods of doing something like this.

By the way, typo :eyes:

9 Likes
12

This looks like an awesome change! What do the performance benefits look like?

7 Likes
13

Does this work like Parts, where the CFrame is the centre of the Box, or does the CFrame indicate a corner of the Box?

7 Likes
14

How does this compare performance wise to the previous Region3 methods?

17 Likes
16

The niche use cases likely include where the developer specifically wanted GetTouchingParts to return an empty table when CanCollide is off.

4 Likes
17

Center of the box, just like the CFrame property of Region3 (and rotation too this time, hopefully.).

8 Likes
18

Is this live immediately or pending? Great addition!

3 Likes
19

  • If you want to know whether a specific part is in a region, you can set a Whitelist of exactly that part in the OverlapParams, and the code will only check against that part.

  • If you want to know whether there’s any parts in a region, but don’t care how many, you can just set MaxParts = 1 on the OverlapParams and early out behavior will make the check very cheap.

22 Likes
20

You could run a

With the one part being in the whitelist?

3 Likes
22

The OverlapParams object contains a property for filtering descendants instances and specifying a filter type. You can just use the Whitelist filter type and whatever objects you’re searching for can be placed in the FilterDescendantsInstance array.

Otherwise, I don’t think a method will be created specifically for this use since it is already feasible (in my opinion), but who knows.

2 Likes
24

Just give us the contact points and normals, come on

15 Likes