OverlapParams do not improve spacial query APIs' performance

[Hexcede]

Reproduction Steps

1. Create a lot of parts in the workspace (I used 1000 for my tests, which is enough to clearly demonstrate the effect).
2. Test how long spacial query APIs take with MaxParts set to 1, with whitelist, or blacklist, etc.

I have excluded WorldRoot:GetPartsInPart() from my tests, I’ve only tested WorldRoot:GetPartBoundsInRadius() and WorldRoot:GetPartBoundsInBox(), with more testing on the former which shows better performance.

My tests result in 150μs per query if all parts share their CFrame. (Random part distribution results in about 1.5x slower queries for some reason)

Expected Behavior

If MaxParts is set to 1, the performance should be benefited due to early-out. (My tests actually indicate that setting MaxParts results in about 3-4μs slower queries on average)
If a whitelist is used, additional parts not included in the whitelist should not hurt performance, as there should be a limited search space.
If a blacklist is used, a bigger blacklist should result in better performance as well, as there is less search space.

---

As for why this is impactful, I’m currently working with an open sourced project (it’s an RTS game with a lot of complex energy transfer stuff), and we expect to have thousands of parts involved in queries at any given time, and based on our performance testing, despite spacial queries’ speed in most cases, we think the impact will be high enough to effect gameplay negatively.

Actual Behavior

Measuring the time taken by queries with different OverlapParams indicates that MaxParts, whitelists, and blacklists have negligible (<0.1%) impacts on performance, which indicates that results are probably getting filtered after (rather than search space getting filtered which would be very beneficial to performance)

Workaround

Generating a WorldModel (note: has to be in the DataModel or queries return empty tables) with only the desired parts in the search space is a partial workaround, but queries still can’t benefit from early out with low MaxParts, and this has it’s own costs and impacts on the architecture of our game.

Issue Area: Engine
Issue Type: Performance
Impact: Moderate
Frequency: Constantly
Date First Experienced: 2022-08-02 00:08:00 (-04:00)
Date Last Experienced: 2022-08-02 00:08:00 (-04:00)

[kleptonaut]

Your observations are correct and unfortunately this is the expected behavior for now. These params currently do not improve performance, they are merely there for convenience. (I do expect that using them would be faster than manually checking the results against your own whitelist table of parts in Lua however.)

We don’t have a way to utilize whitelists as a pre-filter with our current spatial structure. You’ll find the same performance results with RaycastParams and on our legacy spatial query APIs.

That being said we are aware of these needs and have been actively looking into ways for developers to better define different spatial structures and perform queries on only select sets of Parts.

[kleptonaut]

One thing I can say that may help is make sure to use Assemblies efficiently. Try to have your units or other sets of moving parts welded together and with no more than one Part anchored. And try to avoid having unanchored assemblies that are the size of your entire map. This should allow the spatial data structure to work more efficiently.

More info here: Understanding Assemblies
Especially try the “Are Assemblies Shown” toggle mentioned in that article. This will give you an idea on how things are broken down.

If at any point in your development your spatial queries begin to bottleneck the performance of your game, please feel free to share another report with the specific details of your case and repros. Thanks!