Visual Effect 컴포넌트 API

씬에 비주얼 이펙트 그래프의 인스턴스를 생성하기 위해 Unity는 Visual Effect 컴포넌트를 사용합니다. Visual Effect 컴포넌트는 씬의 게임 오브젝트에 연결되며, 시각 효과를 정의하는 비주얼 이펙트 그래프를 참조합니다. 이를 통해 다양한 포지션과 방향에서 다양한 효과 인스턴스를 생성하고, 각 효과를 독립적으로 제어할 수 있습니다. 런타임 시점에 효과를 제어하기 위해 Unity는 Visual Effect 컴포넌트를 수정하고 프로퍼티 오버라이드를 설정하는 데 사용할 수 있는 C# API를 제공합니다.

이 문서는 일반적인 사용 사례를 제시하고 컴포넌트 API를 사용할 때 고려해야 할 모범 사례를 설명합니다.

비주얼 이펙트 그래프 설정

런타임 시점에 비주얼 이펙트 그래프를 변경하려면 새로운 비주얼 이펙트 그래프 에셋을 effect.visualEffectAsset 프로퍼티에 할당하십시오. 비주얼 이펙트 그래프를 변경하면 컴포넌트가 일부 프로퍼티의 값을 초기화합니다.

초기화되는 값은 다음과 같습니다.

  • Total Time: 그래프를 변경하면 API가 이 값을 0.0f로 설정하는 Reset() 함수를 호출합니다.
  • Event Attributes: 컴포넌트가 모든 이벤트 속성을 폐기합니다.

초기화되지 않는 값은 다음과 같습니다.

  • Exposed Property Overrides: 새 비주얼 이펙트 그래프 에셋이 이전 에셋의 프로퍼티와 동일한 이름 및 타입을 지닌 프로퍼티를 노출하는 경우 이 프로퍼티의 값은 초기화되지 않습니다.
  • Random Seed 및 Reset Seed On Play Value.
  • Default Event Override.
  • Rendering Settings overrides.

재생 상태 제어

API를 사용하여 효과 재생을 제어할 수 있습니다.

일반 컨트롤

  • Play: 이벤트 속성이 필요한 경우 effect.Play() 또는 effect.Play(eventAttribute).
  • Stop: 이벤트 속성이 필요한 경우 effect.Stop() 또는 effect.Stop(eventAttribute).
  • Pause: effect.pause = true 또는 effect.pause = false. Unity는 이 변경 사항을 직렬화하지 않습니다.
  • Step: effect.AdvanceOneFrame(). effect.pause가 true로 설정된 경우에만 작동합니다.
  • Reset Effect: effect.Reinit(). 또한 다음을 수행합니다.
    • TotalTime을 0.0f로 초기화합니다.
    • Default Event를 비주얼 이펙트 그래프로 다시 보냅니다.
  • Play Rate: effect.playRate = value. Unity는 이 변경 사항을 직렬화하지 않습니다.

기본 이벤트

Visual Effect 컴포넌트(또는 연결된 게임 오브젝트)가 활성화되면 이벤트를 그래프로 보냅니다. 기본적으로 이 이벤트는 Spawn 컨텍스트의 표준 시작인 OnPlay입니다.

다음과 같은 방법으로 기본 이벤트를 변경할 수 있습니다.

랜덤 시드 컨트롤

모든 효과 인스턴스에는 랜덤 시드에 대한 설정과 컨트롤이 있습니다. 시드를 수정하여 비주얼 이펙트 그래프가 사용하는 무작위 값에 영향을 줄 수 있습니다.

  • resetSeedOnPlay = true/false: ReInit() 함수를 호출할 때마다 Unity가 새로운 랜덤 시드를 계산할지 여부를 제어합니다. 이로 인해 비주얼 이펙트 그래프에서 사용하는 각 무작위 값이 이전 시뮬레이션에서와 다르게 변합니다.
  • startSeed = intSeed: Random Number 연산자가 이 시각 효과에 대한 무작위 값을 생성하는 데 사용하는 수동 시드를 설정합니다. Unity는 resetSeedOnPlay가 true로 설정된 경우 이 값을 무시합니다.

프로퍼티 인터페이스

Visual Effect 컴포넌트에서 여러 메서드를 사용하여 Exposed 프로퍼티의 상태와 값에 액세스할 수 있습니다. 대부분의 API 메서드는 다음 메서드를 통해 프로퍼티에 대한 액세스를 허용합니다.

  • string 프로퍼티 이름. 사용하기 쉽지만, 가장 덜 최적화된 메서드입니다.
  • int 프로퍼티 ID. 문자열 프로퍼티 이름에서 이 ID를 생성하려면 Shader.PropertyToID(string name)를 사용합니다. 가장 최적화된 메서드입니다.
  • ExposedProperty 헬퍼 클래스. 문자열 프로퍼티 이름이 제공하는 편의성과 정수 프로퍼티 ID의 효율성을 결합합니다.

노출 프로퍼티 확인

컴포넌트의 비주얼 이펙트 그래프에 특정 노출 프로퍼티가 포함되었는지 확인할 수 있습니다. 이렇게 하려면 프로퍼티 타입에 해당하는 다음 그룹의 메서드를 사용하십시오.

  • HasInt(property)
  • HasUInt(property)
  • HasBool(property)
  • HasFloat(property)
  • HasVector2(property)
  • HasVector3(property)
  • HasVector4(property)
  • HasGradient(property)
  • HasAnimationCurve(property)
  • HasMesh(property)
  • HasTexture(property)
  • HasMatrix4x4(property)

각 메서드에 대해 비주얼 이펙트 그래프가 전달한 이름이나 ID가 동일한 올바른 타입의 노출 프로퍼티를 포함하고 있으면 메서드는 true를 반환합니다. 그렇지 않으면 메서드는 false를 반환합니다.

노출 프로퍼티의 값 가져오기

컴포넌트 API를 사용하면 컴포넌트의 비주얼 이펙트 그래프에서 노출 프로퍼티의 값을 가져올 수 있습니다. 이렇게 하려면 프로퍼티 타입에 해당하는 다음 그룹의 메서드를 사용하십시오.

  • GetInt(property)
  • GetUInt(property)
  • GetBool(property)
  • GetFloat(property)
  • GetVector2(property)
  • GetVector3(property)
  • GetVector4(property)
  • GetGradient(property)
  • GetAnimationCurve(property)
  • GetMesh(property)
  • GetTexture(property)
  • GetMatrix4x4(property)

각 메서드에 대해 비주얼 이펙트 그래프가 전달한 이름이나 ID가 동일한 올바른 타입의 노출 프로퍼티를 포함하고 있으면 메서드는 프로퍼티의 값을 반환합니다. 그렇지 않으면 메서드는 프로퍼티 타입의 기본값을 반환합니다.

노출 프로퍼티의 값 설정

컴포넌트 API를 사용하면 컴포넌트의 비주얼 이펙트 그래프에서 노출 프로퍼티의 값을 설정할 수 있습니다. 이렇게 하려면 프로퍼티 타입에 해당하는 다음 그룹의 메서드를 사용하십시오.

  • SetInt(property,value)
  • SetUInt(property,value)
  • SetBool(property,value)
  • SetFloat(property,value)
  • SetVector2(property,value)
  • SetVector3(property,value)
  • SetVector4(property,value)
  • SetGradient(property,value)
  • SetAnimationCurve(property,value)
  • SetMesh(property,value)
  • SetTexture(property,value)
  • SetMatrix4x4(property,value)

각 메서드는 해당 프로퍼티의 값을 전달한 값으로 오버라이드합니다.

프로퍼티 오버라이드 및 기본값 초기화

컴포넌트 API를 사용하면 속성 오버라이드를 원래 값으로 초기화할 수 있습니다. 이렇게 하려면 ResetOverride(property) 메서드를 사용하십시오.

이벤트

이벤트 전송

컴포넌트 API를 사용하면 런타임 시점에 이벤트를 컴포넌트의 비주얼 이펙트 그래프로 전송할 수 있습니다. 이렇게 하려면 다음 메서드 중 하나를 사용하십시오.

  • SendEvent(eventNameOrId)
  • SendEvent(eventNameOrId, eventAttribute)

eventNameOrId 파라미터는 다음 타입 중 하나일 수 있습니다.

  • string 프로퍼티 이름. 사용하기 쉽지만, 가장 덜 최적화된 메서드입니다.
  • int 프로퍼티 ID. 문자열 프로퍼티 이름에서 이 ID를 생성하려면 Shader.PropertyToID(string name)를 사용합니다. 가장 최적화된 메서드입니다.
  • ExposedProperty 헬퍼 클래스. 문자열 프로퍼티 이름이 제공하는 편의성과 정수 프로퍼티 ID의 효율성을 결합합니다.

선택적인 eventAttribute 파라미터는 Event Attribute Payload를 이벤트에 연결합니다. 페이로드는 그래프가 이벤트와 함께 처리하는 데이터를 제공합니다.

참고: 이벤트를 전송하면(또는 .Simulate 메서드를 사용하면) Visual Effect 컴포넌트는 LateUpdate 이후에 발생하는 다음 VisualEffect.Update에서 푸시된 모든 커맨드를 처리합니다.

이벤트 속성

이벤트 속성은 이벤트에 연결되는 속성으로, 비주얼 이펙트 그래프에서 처리할 수 있습니다. 이벤트 속성을 만들고 저장하려면 VFXEventAttribute 클래스를 사용하십시오. Visual Effect 컴포넌트는 VFXEventAttribute 클래스의 인스턴스 생성을 담당하며, 현재 할당된 비주얼 이펙트 그래프를 기반으로 그러한 인스턴스를 생성합니다.

이벤트 속성 생성

VFXEventAttribute를 생성하려면 Visual Effect 컴포넌트의 CreateVFXEventAttribute() 메서드를 사용하십시오. 동일한 속성을 사용하여 동일한 이벤트를 여러 번 보내려면 이벤트를 보낼 때마다 새로 생성하는 대신, VFXEventAtrribute를 저장하십시오. 비주얼 이펙트 그래프에 이벤트를 보내면 Unity는 현재 상태의 EventAttribute 복사본을 생성한 후 이 복사본을 보냅니다. 따라서 이벤트를 보낸 후 비주얼 이펙트 그래프에 보낸 정보에 영향을 주지 않고 EventAttribute를 안전하게 수정할 수 있습니다.

속성의 페이로드 설정

이벤트 속성을 생성한 후 프로퍼티 인터페이스 섹션에 설명된 Has/Get/Set 프로퍼티 메서드와 유사한 API를 사용하여 속성 페이로드를 설정하십시오.

  • Has: HasBool, HasVector3, HasFloat,... 속성이 존재하는지 확인합니다.
  • Get: GetBool, GetVector3, GetFloat,... 속성의 값을 가져옵니다.
  • Set: SetBool, SetVector3, SetFloat,... 속성의 값을 설정합니다.

전체 속성 API 문서는 Unity 스크립트 레퍼런스의 VFXEventAttribute를 참조하십시오.

속성 이름 또는 ID는 다음 중 타입 중 하나일 수 있습니다.

  • string 프로퍼티 이름. 사용하기 쉽지만, 가장 덜 최적화된 메서드입니다.
  • int 프로퍼티 ID. 문자열 프로퍼티 이름에서 이 ID를 생성하려면 Shader.PropertyToID(string name)를 사용합니다. 가장 최적화된 메서드입니다.
  • ExposedProperty 헬퍼 클래스. 문자열 프로퍼티 이름이 제공하는 편의성과 정수 프로퍼티 ID의 효율성을 결합합니다.

라이프사이클 및 호환성

이벤트 속성을 생성하면 현재 Visual Effect 컴포넌트에 할당된 비주얼 이펙트 그래프 에셋과 호환됩니다. 즉 동일한 VFXEventAttribute를 사용하여 동일한 그래프의 다른 인스턴스에 이벤트를 보낼 수 있습니다. Visual Effect 컴포넌트의 visualEffectAsset 프로퍼티를 다른 그래프로 변경하면 동일한 'VFXEventAttribute를 사용하여 이벤트를 더 이상 보낼 수 없습니다.

동일한 씬에서 여러 비주얼 이펙트 인스턴스를 관리하고 이벤트 페이로드를 공유하려는 경우 하나의 VFXEventAttribute를 저장하고 모든 인스턴스에서 사용할 수 있습니다.

예제(MonoBehaviour)

VisualEffect visualEffect;
VFXEventAttribute eventAttribute;

static readonly ExposedProperty positionAttribute = "Position"
static readonly ExposedProperty enteredTriggerEvent = "EnteredTrigger"

void Start()
{
    visualEffect = GetComponent<VisualEffect>();
    // Caches an Event Attribute matching the
    // visualEffect.visualEffectAsset graph.
    eventAttribute = visualEffect.CreateVFXEventAttribute();
}

void OnTriggerEnter()
{
    // Sets some Attributes
    eventAttribute.SetVector3(positionAttribute, player.transform.position);
    // Sends the Event
    visualEffect.SendEvent(enteredTriggerEvent, eventAttribute);
}

디버깅

Visual Effect 컴포넌트에는 다음 디버그 프로퍼티가 포함되어 있습니다.

  • aliveParticleCount: 전체 효과의 활성 파티클 수입니다.
    참고: 컴포넌트는 매초마다 이 값을 비동기식으로 계산합니다. 따라서 이 프로퍼티에 액세스하기 전에 최대 1초간 렌더링된 프레임 동안의 활성 파티클 수일 수 있습니다.
  • culled: 카메라가 이전 프레임의 효과를 컬링했는지 여부를 나타냅니다.