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
Last updated