Difference between revisions of "API:Class/Workspace/FindPartsInRegion3WithWhiteList"

 
(No difference)

Latest revision as of 17:07, 6 October 2017

FindPartsInRegion3WithWhiteList

Function of Workspace icon.pngWorkspace
array<BasePart> FindPartsInRegion3WithWhiteList (
    Region3 region,
    array<Instance> whitelistDescendantsTable,
    int maxParts = 20
)
Parameters:
  1. region
  2. whitelistDescendantsTable
  3. maxParts
    • Type: int
    • Defaults to: 20

Returns: array<BasePart>
Description: The FindPartsInRegion3WithWhiteList function is used to check if specific parts are inside a specific area of the Workspace. This function takes several parameters. The first parameter is the Region3 to check. The second parameter is a table of instances. Only parts that are in this table will be returned by the function. The last parameter is the maximum number of parts to return. This function returns a table that includes all of the parts that were found.


Checking if a part overlaps a Region3 is not a simple process. It actually is time consuming and complicated. Instead, FindPartsInRegion3InWhiteList is designed to check if parts are roughly in the same area. When this function is called, it figures out which voxels contain the Region3. It then figures out which parts might be in those voxels. It does this by comparing the axis-aligned bounding box (sometimes called the AABB) of the part with the voxels. The axis-aligned bounding box can be seen in Roblox Studio when a part is selected.

Inkedobvious overlapAABB arrow.jpg

This means that the area that is inspected by the function may be larger than the Region3. For this reason it is recommended to make sure that the Region3 is on the voxel grid. The best way to do this is by setting the coordinates of the Region3 to multiples of 4 (since voxels are 4 x 4 x 4 studs).

This method is a fairly quick and easy way to see if parts are in a general area. If a game needs to know if parts are exactly in an area, then GetTouchingParts should be used. There is a higher cost to using GetTouchingParts since a part is needed in the Workspace and the function takes more time to run.

Visual Example 1

When checking the Region3 described by the volume of the red part, FindPartsInRegion3WithWhiteList will discover the long skinny part as in the Region3. Notice that even though the part itself does not overlap with the red area, the axis-aligned bounding box of the part does.

Obvious overlapAABB.png

Visual Example 2

In this example, while the axis-aligned bounding boxes might not actually overlap each other, they do occupy the same voxels. This means that the part will be returned from the function.

Nonobvious.png

Example

Click the link to go to a working place that runs this code sample. It is not copy locked so anyone may open it.

-- Set up Region3 and return only the red parts
parts = workspace:FindPartsInRegion3WithWhiteList(Region3.new(Vector3.new(-100,-20,-100),Vector3.new(100,20,100)), {workspace.Reds}, 1000) 
-- loop through the parts array and print the name of each part
for partIndex, part in pairs(parts) do 
	print(part.Name) 
end