OverlapParams

Overview

OverlapParams는 월드 내에서 파트 영역을 탐색할 때 필요한 조건들을 관리하는 설정 객체입니다.

WorldRoot에서 제공하는 영역 탐색 함수들은 이 객체를 참조하여, FilterDescendantsInstances와 FilterType을 통해 특정 객체를 포함하거나 제외하고, CollisionGroup 설정에 따라 충돌 그룹 기준의 탐색을 수행합니다.

또한 이 데이터 타입은 새 객체를 생성하지 않고도 설정 값을 변경할 수 있어, 하나의 OverlapParams를 반복적으로 재사용할 수 있습니다.

Constructors

new

새로운 OverlapParams 인스턴스를 생성됩니다. 생성 시에는 초기 설정값이 포함되지 않으며, 이후에 필요한 속성들을 개별적으로 지정하여 사용해야 합니다.

Code Samples

local Params = OverlapParams.new()

Properties

BruteForceAllSlow

boolean

해당 옵션을 활성화하면 파트의 충돌 설정을 무시한 채 월드에 존재하는 모든 파트를 직접 검사하게 됩니다. 이 방식은 연산 비용이 매우 높아 성능 저하를 초래할 수 있으므로, 테스트 용도를 제외한 실제 환경에서는 사용을 권장하지 않습니다.

Code Samples

local Params = OverlapParams.new()
Params.BruteForceAllSlow = true

CollisionGroup

string

탐색 연산이 어떤 충돌 그룹 규칙을 기준으로 동작할지를 정의합니다. 지정된 충돌 그룹과 상호 충돌이 허용되지 않은 파트들은 탐색 대상에서 자동으로 제외됩니다. 별도의 설정이 없을 경우, 기본 충돌 그룹이 사용되어 탐색이 처리됩니다.

Code Samples

local Params = OverlapParams.new()
Params.CollisionGroup = "MyCollisionGroup"

FilterDescendantsInstances

array

이 배열은 탐색 수행 시 포함하거나 제외할 기준이 되는 객체들을 지정합니다. 배열에 등록된 각 객체의 모든 자식 요소들이 함께 고려되며, FilterType 설정에 따라 탐색 대상에 포함되거나 무시됩니다.

Code Samples

local Params = OverlapParams.new()
Params.FilterDescendantsInstances = { Workspace.Part1, Workspace.Part2 }

FilterType

Enum.RaycastFilterType

FilterDescendantsInstances에 포함된 객체들을 탐색 대상에 포함할지 또는 제외할지를 지정합니다. 선택된 RaycastFilterType 열거형 값에 따라, 해당 배열이 탐색 검사 후보를 제한하는 기준으로 적용됩니다.

Code Samples

local Params = OverlapParams.new()
Params.FilterType = Enum.RaycastFilterType.Exclude

MaxParts

number

영역 탐색 시 반환 가능한 파트의 수를 제한하는 데 사용됩니다.

값이 0으로 설정된 경우에는 개수 제한 없이 모든 결과가 반환됩니다.

Code Samples

local Params = OverlapParams.new()
Params.MaxParts = 50

RespectCanCollide

boolean

해당 옵션을 활성화하면 영역 탐색 과정에서 파트의 CanQuery 속성보다 CanCollide 속성을 우선 기준으로 검사 여부를 판단하며, 이를 통해 충돌 가능성을 중심으로 한 탐색 결과를 얻을 수 있습니다.

Code Samples

local Params = OverlapParams.new()
Params.RespectCanCollide = false

Methods

AddToFilter

지정된 인스턴스들을 FilterDescendantsInstances 목록에 추가합니다.

필터 배열을 직접 수정하는 방식보다 간단하고 효율적이며, 탐색 필터 구성을 보다 안전하고 일관되게 관리할 수 있습니다. 또한 이 메서드는 필터 설정을 단계적으로 누적할 때 적합합니다.

Parameters

array InValue	탐색 필터에 추가할 인스턴스 또는 인스턴스 배열입니다.

Return

OverlapParams	필터가 갱신된 OverlapParams 객체를 반환합니다.

Code Samples

local Params = OverlapParams.new()
Params:AddToFilter(Workspace.Part1)
Params:AddToFilter({ Workspace.Part2, Workspace.Part3 })

See also

WorldRoot