VFXRecipe

개요

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

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

사용 방법

VFXRecipe 배치

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

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

레이어 구성

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

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

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

재생 설정

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

스크립트로 제어하기

재생·정지

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

local vfxRecipe = script.Parent

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

wait(3)
vfxRecipe:Stop()

재생 완료 감지

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

local vfxRecipe = script.Parent

vfxRecipe.InfiniteLoop = false
vfxRecipe.LoopCount = 3

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

vfxRecipe:Play()

파라미터 제어

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

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)으로 현재 파라미터 값을 읽습니다.

local vfxRecipe = script.Parent

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

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

local vfxRecipe = script.Parent

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

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

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

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

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

LoopCount는 소스 파라미터가 아닙니다. vfxRecipe.LoopCount = N으로 설정해야 합니다.

종합 예제

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

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()

스크립트 기능

VFXRecipe