Introducing OverlapParams - New Spatial Query API

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

580 Likes
[Obsolete] Simple trick to make GetTouchingParts work with non-CanCollide parts
How Would I Make A Good Raycast Hitbox For Barrage Ability?
How do I make hitboxes?
RotatedRegion3 Help
How can I apply a force to a part similarly to the Explosion class?
How to see if player is standing on part?
How to check if parts are inside box?
How to find if a player's head is within a part?
OverlapParam Whitelist/Blacklist Not Filtering
Multiplayer Animation Radius
Rotated Region 3 Module
Region 3 simple hit detection
ZonePlus v3.2.0 | Construct dynamic zones and effectively determine players and parts within their boundaries
Any alternative to spherecast?
My script is very laggy
How to make Text Label Come from a line?
Detect if different objects are in a specific location
FindPartsInRegion3 is deprecated?
I need this coin to be destroyed when it touches any of these red zones, how would i do this?
How do you avoid loops when scripting an Area Script
Region3 only detects 20 parts at max (datastore problem)
I'm trying to make a part change its color based on the other part that it is touching. How could I do it?
Give and Remove Tools with Teams
What should I do to recognize the person in the car or motorcycle when touched?
How to constantly check for a seat within a certain radius?
Making an anti-cheat system, but want to know how to detect changes on the client
GetPartsInPart() being slow
Struggling with Region3
When To Use Reigion3 Over Raycasting?
How to create a floor button
Finding closest object of certain material?
What logic should I use to make a jail cell?
How would I make a zone based gravity system?
How do I check player amount within zone?
Do you still use Region3 in your scripting works?
If ALL Players Are Touching The Part
Region3 not working as expected, help?
How to detect if camera touches a part
Raycasting issue to replace over BasePart.Touched event
My value is going negative super fastly
ZonePlus v3.2.0 | Construct dynamic zones and effectively determine players and parts within their boundaries
How can I make it so when a player is in a certian area only that players screen gets blurred or their line of sight goes down?
Example For OverlapParams
How can I know if a player is in a room?
How to get Parts in an area of mouse.Hit?
Unable to cast Instance to Region3
Need help finding the closest part to another
Alternative to TouchEvent (Raycast)?
New Part Collision Property: CanQuery - Now Available!
Other function running after the function ended
Since when was 'Workspace:FindPartsInRegion3' deprecated?
"FindPartsInRegion3" seems to be deprecated with no replacement
ClientCast - A Client-based, Idiosyncratic Hitbox System!
My Region3 isn't detecting enemy
Touched-Ended Event Issues
How to make a safe zone
Region3 doesn't have correct position
Issue with Region3 Hitbox
Best way to damage anchored dummy
Raycast returns nil
Best way to debounce?
Enemy/NPC player detection
Raycasting a visible point of view
.Touched is not sensitive enough
AFK Zone where to earn money every x amount of time
Hitbox Detects Punching
Enabling CanTouch doesn't trigger .Touched event
Best way of checking if you're near another player?
Trouble with region3
Trouble with region3
:FindPartsInRegion3() is deprecated, what should I use?
What's the best way to make NPC field of view
How can I make an intermittent touched event?
How can I detect collisions by CFrame overlap?
Parrying not working?
ZonePlus v3.2.0 | Construct dynamic zones and effectively determine players and parts within their boundaries
I need help about NPC Hitbox
How do I make a Build a boat for tresure like welding system?
Hitbox Service, easily create Accurate Hitboxes using minimal scripting!
Region3 breaks when the same code gets copy pasted
Raycasting not hitting when it starts inside a part (or maybe another issue)
Whats a good alternative for Touched events?
Parts appear in a different place for the client?
Detect touch between anchored parts
OverlapParams.new() doesn't work or respect the parameters I've given
ZonePlus v3.2.0 | Construct dynamic zones and effectively determine players and parts within their boundaries
GetTouchingParts() issue
GetTouchingParts not working?
Touch a part to open a GUI shop
Shapecasts vs Spatial queries performance and reliability wise
Release Notes for 576
Tile Movement system can't account for obstacles
Destroy isnt working (Read Comments For updated post)
How to detect players in a region/zone?
Better way to do hitboxing?
HitboxRemaster Beta Release! (Current ver. v1.1.1)
Melee Hitboxing
What method would you use to make a large, moving hitbox?
Using a script from another game wont work?
Help with a nuke that destroys everything!
Teleporting players from a region3
How to make a swimmable part? HELP!
How should I go about making a hitbox?
Why is `.Touched` glitching out?
[Obsolete] Simple trick to make GetTouchingParts work with non-CanCollide parts
Raycast Hitbox 4.01: For all your melee needs!
Whats the best way to go about region detection?
Welding a car in a certain area
Damage event fires multiple timesw
Region3 hitbox problems
Whats the best way to go about region detection?
Script only works when applied to one part instead of muliple
Part.Touched or spatial queries
How to constantly check if a player is touching a part?
Alternative Method to .OnTouched
Types of Hitboxes
How to detect player and a part in a region
Would .Touched event cause performance issues
Detecting Whether An Object Is Within The Boundaries Of A Rotated Cube
How laggy is while true do

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!

78 Likes

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?

14 Likes

Possibly will use someday. That’s great although!

5 Likes

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

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?

12 Likes

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

11 Likes

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

5 Likes

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)

5 Likes

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

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

7 Likes

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

8 Likes

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

17 Likes

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

4 Likes

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

8 Likes

Is this live immediately or pending? Great addition!

3 Likes
  • 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.

23 Likes

You could run a

With the one part being in the whitelist?

3 Likes

(post deleted by author)

3 Likes

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