Visual Effect コンポーネント API

Unity はシーンで Visual Effect Graph のインスタンスを作成する際に、Visual Effect コンポーネントを使います。Visual Effect コンポーネントは、シーンのゲームオブジェクトに設定され、ビジュアルエフェクトを定義する Visual Effect Graph を参照します。これにより、様々な位置と向きで異なるエフェクトのインスタンスを作成し、各エフェクトをそれぞれ個別に制御することができます。ランタイムでエフェクトを制御するために、Unity は Visual Effect コンポーネントを変更し、プロパティオーバーライドを設定するための、C# API を提供しています。

このドキュメントでは、一般的なユースケースを紹介し、コンポーネント API を活用する際に考慮すべき、良い実践方法を解説します。

Visual Effect Graph の設定

ランタイムに Visual Effect Graph を変更するには、新しい Visual Effect Graph Asset を effect.visualEffectAsset プロパティに割り当てます。Visual Effect Graph を変更する際、コンポーネントはプロパティの値のいくつかをリセットします。

リセットする値は以下の通りです。

Total Time: グラフを変更する際、API は Reset() 関数を呼び出し、この値を 0.0f に設定します。
Event Attributes: コンポーネントはすべての Event 属性を破棄します。

リセット しない 値は以下の通りです。

Exposed Property Overrides: 新しい Visual Effect Graph アセットが以前のアセットのプロパティと同じ名前とタイプを持つプロパティを開放 (アクセス可能に) する場合、このプロパティの値はリセットされません。
Random Seed および Reset Seed On Play Value
Default Event Override
Rendering Settings overrides

再生状態の制御

API を使うと、エフェクトの再生を制御できます。

一般的な制御

Play : effect.Play() または Event の Attribute が必要な場合は effect.Play(eventAttribute)
Stop : effect.Stop() または Event の属性が必要な場合は 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 を Visual Effect Graph に再送します。
Play Rate : effect.playRate = value。Unity はこの変更をシリアル化しません。

デフォルトイベント

Visual Effect コンポーネント (またはコンポーネントが設定されたゲームオブジェクト) が有効になると、イベントがグラフに送信されます。デフォルトで OnPlay イベントが送信され、通常 Spawn Contexts はこれにより開始されます。

デフォルトのイベントは、以下の方法で変更できます。

Visual Effect Inspector で、Initial Event Name フィールドを変更。
コンポーネント API 内で initialEventName = "MyEventName";
コンポーネント API 内で initialEventID = Shader.PropertyToID("MyEventName");
ExposedProperty Helper クラスを利用。

ランダムシードの制御

すべてのエフェクトインスタンスには、ランダムシードに対する設定と制御があります。シードを変更すると、Visual Effect Graph が使うランダム値に影響を与えることができます。

resetSeedOnPlay = true/false: ReInit() 関数を呼び出すたびに、毎回新しいランダムシードを計算するかを制御します。Visual Effect Graph が使うランダム値それぞれは、前のシミュレーションとは異なるものになります。
startSeed = intSeed: Random Number 演算子がこの Visual Effect に対するランダム値を作成する際に使う、手動シードを設定します。resetSeedOnPlay が true に設定されている場合、Unity はこの値を無視します。

プロパティインターフェース

開放された (Exposed) プロパティの状態と値にアクセスするために、 Visual Effect コンポーネントでは複数のメソッドを使うことができます。API メソッドのほとんどは、以下のメソッドでプロパティにアクセスできます。

string プロパティ名。簡単に使えますが、最も最適化されていないメソッドです。
int プロパティ ID。ストリングプロパティ名からこの ID を生成するには、Shader.PropertyToID(string name) を使います。これは最も最適化されたメソッドです。
ExposedProperty Helper クラス。ストリングプロパティ名の使い易さに、整数プロパティ ID の効率性を合わせたメソッドです。

開放された (exposed) プロパティの確認

コンポーネントの Visual Effect Graph に指定した開放プロパティが含まれているかを確認することができます。これを行うには、プロパティタイプに応じて以下のグループのメソッドを使ってください。

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

各メソッドについて、Visual Effect Graph に同じ名前またはパスする ID を持つ、正しいタイプの開放されたプロパティが含まれる場合に、メソッドは true を返します。そうでなければ、メソッドは false を返します。

開放された (exposed) プロパティ値の取得

コンポーネント API では、コンポーネントの Visual Effect Graph 内で開放プロパティ値を取得することができます。実行する際は、プロパティタイプに応じて以下のグループからのメソッドを使ってください。

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

各メソッドで、Visual Effect Graph に指定した同じ名前または ID を持つ、正しいタイプの開放されたプロパティが含まれる場合、メソッドはそのプロパティ値を返します。そうでなければ、メソッドはプロパティタイプのデフォルト値を返します。

開放 (exposed) プロパティ値の設定

コンポーネント API を使うと、コンポーネントの Visual Effect Graph 内で開放されたプロパティの値を設定することができます。実行する際は、プロパティタイプに応じて、以下のグループからのメソッドを使ってください。

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 を使うと、ランタイムにイベントをコンポーネントの Visual Effect Graph に送信できます。これは、以下のメソッドのいずれかを使って実行します。

SendEvent(eventNameOrId)
SendEvent(eventNameOrId, eventAttribute)

eventNameOrId パラメーターは、以下のタイプのいずれかになります。

string プロパティ名。簡単に使えますが、最も最適化されていないメソッドです。
int プロパティ ID。ストリングプロパティ名からこの ID を生成するには、Shader.PropertyToID(string name) を使います。これは最も最適化されたメソッドです。
ExposedProperty Helper クラス。ストリングプロパティ名の使い易さに、整数プロパティ ID の効率性を合わせたメソッドです。

オプションの eventAttribute パラメーターは、Event Attribute Payload を Event に取り込みます。ペイロードは、Graph が Event で処理するデータを提供します。

ノート: Event を送信する (または .Simulate メソッドを使う) 際、Visual Effect コンポーネントは、次の VisualEffect.Update 内のすべてのプッシュされたコマンドを処理します。これは LateUpdate の後で実行されます。

Event Attribute

Event Attribute は Event に設定される Attribute (属性) で、Visual Effect Graph によって処理されます。Event Attribute を作成し格納するには、VFXEventAttribute クラスを使います。Visual Effect コンポーネントは、VFXEventAttribute クラスのインスタンスを作成し、現在割り当てられている Visual Effect Graph に基づき、インスタンスを作成します。

Event Attribute の作成

VFXEventAttribute の作成には、Visual Effect コンポーネントの CreateVFXEventAttribute() メソッドを使います。同じ Event を同じ属性で複数回送信したい場合は、Event 送信のたびに新しく作るのではなく、VFXEventAtrribute を格納します。Event を Visual Effect Graph に送る際、Unity は現在の状態で EventAttribute のコピーを作成して送信します。つまり、Event 送信後、Visual Effect Graph に送った情報に影響を及ぼすことなく、EventAttribute を変更できます。

Attribute のペイロード設定

EventAttribute を作成したら、Property インターフェースセクションで解説した Has/Get/Set プロパティメソッドに類似した API を使って、Attribute のペイロードを設定します。

Has : HasBool, HasVector3, HasFloat,... Attribute が存在するかを確認します。
Get : GetBool, GetVector3, GetFloat,... Attribute の値を取得します。
Set : SetBool, SetVector3, SetFloat,... Attribute の値を設定します。

Attribute API の完全ドキュメントは、Unity Script Reference 内の VFXEventAttribute を参照してください。

属性名または ID は、以下のタイプのいずれかになります。

string プロパティ名。簡単に使えますが、最も最適化されていないメソッドです。
int プロパティ ID。ストリングプロパティ名からこの ID を生成するには、Shader.PropertyToID(string name) を使います。これは最も最適化されたメソッドです。
ExposedProperty Helper クラス。ストリングプロパティ名の使い易さに、整数プロパティ ID の効率性を合わせたメソッドです。

ライフサイクルと互換性

Event Attribute を作成すると、現在 Visual Effect コンポーネントに割り当てられている、Visual Effect Graph アセットと互換性があります。つまり、同じ VFXEventAttribute を使って、同じグラフの他のインスタンスに Event を送信することができます。Visual Effect コンポーネントの visualEffectAsset プロパティを別のグラフに変更する場合は、同じ VFXEventAttribute を使って Event を送信できなくなります。

複数の Visual Effect インスタンスを同じシーンで管理し、Event ペイロードを共有したい場合は、1 つの VFXEventAttribute を格納して、すべてのインスタンスに使うことができます。

例 (MonoBehaviour)

VisualEffect visualEffect;
VFXEventAttribute eventAttribute;

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

void Start()
{
    visualEffect = GetComponent<VisualEffect>();
    // 以下と一致する Event Attribute をキャッシュします
    // visualEffect.visualEffectAsset graph.
    eventAttribute = visualEffect.CreateVFXEventAttribute();
}

void OnTriggerEnter()
{
    // Attributes をいくつか設定します
    eventAttribute.SetVector3(positionAttribute, player.transform.position);
    // Event を送信します
    visualEffect.SendEvent(enteredTriggerEvent, eventAttribute);
}

デバッグ

Visual Effect コンポーネントにはそれぞれ、以下のデバッグプロパティが含まれています。

aliveParticleCount: エフェクト全体で生きているパーティクル数です。
ノート: コンポーネントはこの値を毎秒非同期的に計算します。つまり、このプロパティにアクセスする 1 秒前までにレンダリングされたフレーム内に生存するパーティクル数である場合があります。
culled: カメラが前のフレームでエフェクトを除去したかを示します。