> 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/manual/studio-manual/object/vfx/vfxrecipe.md).

# VFXRecipe

## 개요

VFXRecipe는 여러 VFX 소스를 레이어 구조로 조합하여 복합 이펙트를 구성하고, 스크립트로 재생을 제어할 수 있는 오브젝트입니다.

VFXPreset이 사전 정의된 이펙트를 선택하는 방식이라면, VFXRecipe는 Base·Detail·Extra 세 레이어에 VFX 소스를 직접 배치하여 이펙트를 직접 조합할 수 있습니다. 각 소스의 색상, 크기, 투명도 등의 파라미터를 스크립트로 런타임에 제어할 수 있어 다양한 연출 변화를 줄 수 있습니다.

## 사용 방법

### VFXRecipe 배치

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2FDj2cv6lpo3JCA43bQUwX%2Fimage.png?alt=media&amp;token=7db28436-e6b9-4ddf-a288-2ad287fa7395" alt=""><figcaption></figcaption></figure>

Level Browser에서 VFXRecipe를 원하는 위치에 배치합니다.

배치된 VFXRecipe를 선택하면 프로퍼티 패널에서 레이어 구성과 재생 설정을 편집할 수 있습니다.

### 레이어 구성

VFXRecipe는 Base, Detail, Extra 세 가지 레이어를 가집니다.

<table><thead><tr><th width="140">레이어</th><th>역할</th></tr></thead><tbody><tr><td>BaseLayer</td><td>이펙트의 핵심 시각 요소를 담당합니다. 반드시 하나 이상의 소스를 배치해야 합니다.</td></tr><tr><td>DetailLayer</td><td>BaseLayer 위에 세부 묘사를 추가합니다. 선택적으로 배치합니다.</td></tr><tr><td>ExtraLayer</td><td>부가적인 보조 효과를 추가합니다. 선택적으로 배치합니다.</td></tr></tbody></table>

각 레이어의 + 버튼을 클릭하면 소스를 추가할 수 있습니다. 추가된 소스 항목에서 VFX Source 필드를 클릭해 VFX 소스 에셋을 선택하고, Name 필드에 이름을 입력합니다. 이름은 스크립트에서 `GetParam` / `SetParam`으로 파라미터를 제어할 때 소스를 식별하는 데 사용됩니다.

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2FvsJH6gIOLT3ua4qmopHT%2Fimage.png?alt=media&amp;token=27b54dca-8237-49b5-8daa-d0c3e17018ba" alt=""><figcaption></figcaption></figure>

### 재생 설정

| 프로퍼티         | 설명                                                              |
| ------------ | --------------------------------------------------------------- |
| AutoActivate | `true`이면 인스턴스가 활성화될 때 자동으로 재생을 시작합니다. 기본값은 `true`입니다.           |
| InfiniteLoop | `true`이면 `Stop()`이 호출될 때까지 무한 반복 재생합니다. 기본값은 `false`입니다.        |
| LoopCount    | 재생 반복 횟수입니다. InfiniteLoop가 `false`일 때만 적용됩니다. 기본값은 `1`입니다.      |
| LoopDuration | 레이어에 등록된 소스의 파라미터를 분석해 자동으로 계산되는 1회 재생 시간(초)입니다. 직접 수정할 수 없습니다. |

## 스크립트로 제어하기

### 재생·정지

`Play()`와 `Stop()`으로 이펙트 재생을 수동 제어합니다. 서버 스크립트에서 호출하면 모든 클라이언트에 자동으로 동기화됩니다.

```lua
local vfxRecipe = script.Parent

-- 자동 재생 비활성화 후 2초 뒤 수동 재생
vfxRecipe.AutoActivate = false
wait(2)
vfxRecipe:Play()

wait(3)
vfxRecipe:Stop()
```

### 재생 완료 감지

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

```lua
local vfxRecipe = script.Parent

vfxRecipe.InfiniteLoop = false
vfxRecipe.LoopCount = 3

vfxRecipe.Finished:Connect(function()
    print("재생이 완료되었습니다.")
end)

vfxRecipe:Play()
```

### 파라미터 제어

`SetParam(SourceName, ParamName, Value)`으로 소스의 파라미터를 런타임에 변경합니다. SourceName에 빈 문자열(`""`)을 전달하면 모든 레이어의 모든 소스에 일괄 적용됩니다.

```lua
local vfxRecipe = script.Parent

-- 특정 소스의 크기 변경
vfxRecipe:SetParam("FlameSource", "Size", 2)

-- 모든 소스의 투명도 일괄 변경
vfxRecipe:SetParam("", "Transparency", 0.5)

-- ColorSequence로 색상 변경
local colorKeys = {
    ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 100, 0)),
    ColorSequenceKeypoint.new(1, Color3.fromRGB(255, 220, 0)),
}
vfxRecipe:SetParam("FlameSource", "Color", ColorSequence.new(colorKeys))
```

`GetParam(SourceName, ParamName)`으로 현재 파라미터 값을 읽습니다.

```lua
local vfxRecipe = script.Parent

local currentSize = vfxRecipe:GetParam("FlameSource", "Size")
print("현재 크기:", currentSize)
```

소스 이름 대신 레이어 이름과 인덱스로 소스를 지정하려면 `SetParamAt` / `GetParamAt`을 사용합니다. 인덱스는 0부터 시작합니다.

```lua
local vfxRecipe = script.Parent

-- Base 레이어의 첫 번째 소스 크기 변경
vfxRecipe:SetParamAt("Base", 0, "Size", 1.5)

-- Detail 레이어의 두 번째 소스 투명도 조회
local transparency = vfxRecipe:GetParamAt("Detail", 1, "Transparency")
print("투명도:", transparency)
```

### 런타임에 변경 가능한 파라미터

`SetParam`으로 런타임에 변경할 수 있는 파라미터는 소스의 SpawnType에 따라 다릅니다.

<table><thead><tr><th width="160">파라미터</th><th width="100">SpawnType</th><th>설명</th></tr></thead><tbody><tr><td>Size</td><td>공통</td><td>파티클 크기 스케일</td></tr><tr><td>Color</td><td>공통</td><td>파티클 색상 (ColorSequence)</td></tr><tr><td>Transparency</td><td>공통</td><td>파티클 불투명도 (0–1)</td></tr><tr><td>Offset</td><td>공통</td><td>파티클 생성 위치 오프셋 (Vector3)</td></tr><tr><td>SpawnCount</td><td>burst</td><td>활성화 시 한 번에 생성할 파티클 수</td></tr><tr><td>SpawnRate</td><td>rate</td><td>초당 파티클 생성 수</td></tr><tr><td>Speed</td><td>rate</td><td>파티클 이동 속도 (0–100)</td></tr><tr><td>BoundSize</td><td>rate</td><td>파티클 생성 범위 크기</td></tr><tr><td>Duration</td><td>rate</td><td>이미터 지속 시간 (초)</td></tr></tbody></table>

{% hint style="warning" %}
`LoopCount`는 소스 파라미터가 아닙니다. `vfxRecipe.LoopCount = N`으로 설정해야 합니다.
{% endhint %}

### 종합 예제

이펙트를 재생하고, 재생 중에 색상과 크기를 바꾼 뒤, 재생이 끝나면 원래 값으로 되돌리는 예제입니다.

```lua
local vfxRecipe = script.Parent

local function playWithEffect()
    -- 재생 전 파라미터 설정
    vfxRecipe:SetParam("", "Size", 2)
    vfxRecipe:SetParam("", "Color", ColorSequence.new(Color3.fromRGB(0, 150, 255)))

    vfxRecipe.InfiniteLoop = false
    vfxRecipe.LoopCount = 2

    -- 재생 완료 시 원래 값으로 복원
    local conn
    conn = vfxRecipe.Finished:Connect(function()
        conn:Disconnect()
        vfxRecipe:SetParam("", "Size", 1)
        vfxRecipe:SetParam("", "Color", ColorSequence.new(Color3.fromRGB(255, 100, 0)))
    end)

    vfxRecipe:Play()
end

playWithEffect()
```

## 스크립트 기능

{% content-ref url="/pages/9k7KSspkTCvZ3rcAgBmK" %}
[VFXRecipe](/korean/development/api-reference/classes/vfxrecipe.md)
{% endcontent-ref %}