> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/vfxrecipe.md).

# VFXRecipe

VFXRecipe : `Instance`

## Overview

VFXRecipe는 시각 효과(VFX)를 씬에 배치하고 재생·제어할 수 있는 클래스입니다.

하나의 VFXRecipe는 BaseLayer, DetailLayer, ExtraLayer 세 가지 레이어를 가지며, 각 레이어에 VFXSource를 등록해 복합 이펙트를 구성합니다. 재생 횟수(LoopCount)와 무한 반복(InfiniteLoop) 설정으로 재생 방식을 제어하며, AutoActivate가 true이면 Workspace에 배치되는 순간 자동으로 재생이 시작됩니다.

`Play()` / `Stop()` 메서드로 재생을 수동 제어할 수 있고, 재생이 끝나면 `Finished` 이벤트가 발생합니다.

## Properties

### AutoActivate

`boolean`

VFXRecipe가 씬에 활성화될 때 이펙트를 자동으로 재생할지 여부를 지정하는 속성입니다.

`true`이면 인스턴스가 초기화되는 시점에 `Play()`를 명시적으로 호출하지 않아도 이펙트가 즉시 재생됩니다. `false`이면 스크립트에서 직접 `Play()`를 호출해야 재생이 시작됩니다. 기본값은 `true`입니다.

#### Code Samples

### BaseLayer

`Array`

이펙트의 기본 시각 요소를 구성하는 VFXSource 배열을 나타내는 속성입니다.

DetailLayer, ExtraLayer와 함께 VFXRecipe의 세 가지 레이어 중 하나로, 주요 파티클 효과를 담당합니다. 배열의 각 항목은 이름(Name)을 가지며, 에디터에서 레이어 구성을 편집할 수 있습니다.

#### Code Samples

### DetailLayer

`Array`

이펙트의 세부 시각 요소를 구성하는 VFXSource 배열을 나타내는 속성입니다.

BaseLayer 위에 추가되는 보조 파티클 효과를 담당합니다. 배열의 각 항목은 이름(Name)을 가지며, BaseLayer·ExtraLayer와 함께 재생됩니다.

#### Code Samples

### ExtraLayer

`Array`

이펙트의 부가 시각 요소를 구성하는 VFXSource 배열을 나타내는 속성입니다.

BaseLayer·DetailLayer에 더해 추가적인 파티클 효과를 담당합니다. 배열의 각 항목은 이름(Name)을 가지며, 세 레이어는 모두 동일한 생명주기 파라미터(LoopDuration, LoopCount)를 공유하여 동기화된 상태로 재생됩니다.

#### Code Samples

### InfiniteLoop

`boolean`

이펙트를 무한 반복 재생할지 여부를 지정하는 속성입니다.

`true`이면 `Stop()`을 호출하거나 인스턴스가 파괴될 때까지 이펙트가 계속 반복됩니다. `false`이면 LoopCount에 지정된 횟수만큼 재생한 후 자동으로 멈추며 `Finished` 이벤트가 발생합니다. 기본값은 `false`입니다.

InfiniteLoop가 `true`인 동안에는 LoopCount 설정이 무시됩니다.

#### Code Samples

### LoopCount

`number`

이펙트를 재생할 총 횟수를 지정하는 속성입니다.

InfiniteLoop가 `false`일 때만 유효하며, `Play()` 호출 후 이 값만큼 이펙트가 반복 재생된 뒤 자동으로 멈춥니다. 기본값은 `1`입니다.

#### Code Samples

### LoopDuration

`number`

이펙트의 1회 재생 시간(초)을 나타내는 읽기 전용 속성입니다.

세 레이어(BaseLayer, DetailLayer, ExtraLayer)에 등록된 모든 VFXSource의 Duration·Delay 파라미터를 분석하여 자동으로 계산되며, 직접 수정할 수 없습니다. 전체 재생 시간은 `LoopDuration × LoopCount`로 결정됩니다.

#### Code Samples

## Methods

### GetParam

지정한 VFXSource의 파라미터 값을 가져옵니다.

BaseLayer, DetailLayer, ExtraLayer 전체에서 SourceName과 일치하는 VFXSource를 찾아 ParamName으로 지정된 파라미터의 현재 값을 반환합니다. Position·Rotation은 VFXSource 자체에 저장된 값을 반환하고, 그 외 파라미터는 실제로 재생 중인 NiagaraComponent에서 값을 읽어옵니다. Source나 파라미터를 찾지 못하면 경고 로그를 출력하고 `nil`을 반환합니다.

#### Parameters

| `string` SourceName | 값을 가져올 VFXSource의 이름입니다. |
| ------------------- | ------------------------ |
| `string` ParamName  | 가져올 파라미터의 이름입니다.         |

#### Return

| `Value` | 조회한 파라미터의 값입니다. 파라미터 타입에 따라 number, boolean, Vector2, Vector3, ColorSequence, NumberSequence 등이 반환됩니다. |
| ------- | ------------------------------------------------------------------------------------------------------ |

#### Code Samples

### GetParamAt

레이어와 인덱스로 지정한 VFXSource의 파라미터 값을 가져옵니다.

LayerName·Index로 특정 레이어의 VFXSource를 지정한다는 점을 제외하면 `GetParam()`과 동작이 동일합니다. LayerName이 `Base`, `Detail`, `Extra` 중 하나가 아니거나 Index가 해당 레이어의 범위를 벗어나면 경고 로그를 출력하고 `nil`을 반환합니다.

#### Parameters

| `string` LayerName | 값을 조회할 레이어의 이름입니다. `Base`, `Detail`, `Extra` 중 하나를 지정합니다(대소문자 구분 없음). |
| ------------------ | --------------------------------------------------------------------- |
| `number` Index     | 해당 레이어에서 값을 가져올 VFXSource의 인덱스입니다(0부터 시작).                            |
| `string` ParamName | 가져올 파라미터의 이름입니다.                                                      |

#### Return

| `Value` | 조회한 파라미터의 값입니다. 파라미터 타입에 따라 number, boolean, Vector2, Vector3, ColorSequence, NumberSequence 등이 반환됩니다. |
| ------- | ------------------------------------------------------------------------------------------------------ |

#### Code Samples

### IsPlaying

현재 이펙트가 재생 중인지 여부를 반환합니다.

`Play()`가 호출된 이후 `Stop()`이 호출되거나 재생이 완료될 때까지 `true`를 반환합니다.

#### Parameters

#### Return

| `boolean` | 이펙트가 현재 재생 중이면 `true`, 멈춰 있으면 `false`를 반환합니다. |
| --------- | --------------------------------------------- |

#### Code Samples

### Play

이펙트 재생을 시작합니다.

서버에서 호출하면 모든 클라이언트에 멀티캐스트로 전파됩니다. 이미 재생 중인 상태에서 호출하면 처음부터 다시 시작됩니다. InfiniteLoop가 `false`이면 LoopCount만큼 재생한 뒤 자동으로 멈추고 `Finished` 이벤트가 발생합니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

### SetParam

지정한 VFXSource의 파라미터 값을 설정합니다.

BaseLayer, DetailLayer, ExtraLayer 전체에서 SourceName과 일치하는 VFXSource를 찾아 ParamName으로 지정된 파라미터에 Value를 적용합니다. SourceName을 빈 문자열로 전달하면 세 레이어의 모든 VFXSource에 동일한 값이 일괄 적용됩니다. `LoopCount`처럼 VFXRecipe 프로퍼티로 노출된 값이나, 리소스·내부 재생 로직에 의해 값이 고정되는 파라미터는 설정할 수 없습니다. 서버에서 호출하면 모든 클라이언트에 멀티캐스트로 전파됩니다.

#### Parameters

| `string` SourceName | 값을 설정할 VFXSource의 이름입니다. 빈 문자열을 전달하면 모든 VFXSource에 일괄 적용됩니다.                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `string` ParamName  | 설정할 파라미터의 이름입니다.                                                                                          |
| `Value` Value       | 파라미터에 설정할 값입니다. 파라미터 타입에 맞는 number, boolean, Vector2, Vector3, ColorSequence, NumberSequence 등을 전달해야 합니다. |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

### SetParamAt

레이어와 인덱스로 지정한 VFXSource의 파라미터 값을 설정합니다.

LayerName·Index로 특정 레이어의 VFXSource를 지정한다는 점을 제외하면 `SetParam()`과 동작이 동일합니다. LayerName이 `Base`, `Detail`, `Extra` 중 하나가 아니거나 Index가 해당 레이어의 범위를 벗어나면 경고 로그를 출력하고 아무 동작도 하지 않습니다.

#### Parameters

| `string` LayerName | 값을 설정할 레이어의 이름입니다. `Base`, `Detail`, `Extra` 중 하나를 지정합니다(대소문자 구분 없음).                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `number` Index     | 해당 레이어에서 값을 설정할 VFXSource의 인덱스입니다(0부터 시작).                                                                |
| `string` ParamName | 설정할 파라미터의 이름입니다.                                                                                          |
| `Value` Value      | 파라미터에 설정할 값입니다. 파라미터 타입에 맞는 number, boolean, Vector2, Vector3, ColorSequence, NumberSequence 등을 전달해야 합니다. |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

### Stop

이펙트 재생을 즉시 중단합니다.

서버에서 호출하면 모든 클라이언트에 멀티캐스트로 전파됩니다. 이미 멈춰 있는 상태에서 호출해도 오류가 발생하지 않습니다. `Stop()` 호출로 인한 중단 시에는 `Finished` 이벤트가 발생하지 않습니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

## Events

### Finished

이펙트 재생이 정상적으로 완료되었을 때 발생하는 이벤트입니다.

InfiniteLoop가 `false`인 상태에서 LoopCount만큼 재생이 끝나면 발생합니다. `Stop()`으로 강제 중단한 경우에는 발생하지 않습니다.

#### Parameters

#### Code Samples