OverlapParams

Overview

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

WorldRoot에서 제공하는 영역 탐색 함수들은 이 객체를 참조하여, FilterDescendantsInstances와 FilterType을 통해 특정 객체를 포함하거나 제외할 수 있습니다.

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

Constructors

new

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

Parameters

Return

OverlapParams	생성된 OverlapParams입니다.

Code Samples

local Params = OverlapParams.new()

Properties

BruteForceAllSlow

boolean

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

Code Samples

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

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

TraceGroupName

string

오버랩 쿼리 결과를 이 값과 TraceGroupName 프로퍼티가 정확히 일치(대소문자 구분)하는 파트만 포함하도록 필터링합니다. 일치하지 않는 파트는 결과에서 제외됩니다. 비워두면(기본값) 그룹 필터링이 적용되지 않고 TraceGroupName과 무관하게 모든 파트를 대상으로 합니다. RespectCanCollide가 true이면 충돌 여부 기준 필터링이 우선되어 이 필터는 무시됩니다.

Code Samples

Methods

AddToFilter

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

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

Parameters

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

Return

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

Code Samples

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

Events

See also

WorldRoot