# OverlapParams

## Overview

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

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

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

## Constructors

### new

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

#### Code Samples

```lua
local Params = OverlapParams.new()
```

## Properties

### BruteForceAllSlow

`boolean` 

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

#### Code Samples

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

### CollisionGroup

`string` 

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

#### Code Samples

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

### FilterDescendantsInstances

`array` 

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

#### Code Samples

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

### FilterType

`Enum.RaycastFilterType`

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

#### Code Samples

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

### MaxParts

`number` 

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

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

#### Code Samples

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

### RespectCanCollide

`boolean` 

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

#### Code Samples

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

## Methods

### AddToFilter

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

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

#### Parameters

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

#### Return

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

#### Code Samples

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

## See also

{% content-ref url="../classes/worldroot" %}
[worldroot](https://docs.overdare.com/korean/development/api-reference/classes/worldroot)
{% endcontent-ref %}