unreal-niagara

Unreal Niagara VFX

Niagara を使用して UE5 でリアルタイムのビジュアルエフェクトを作成・制御します。System／Emitter／Module の階層を理解し、ゲームプレイから操作できるパラメーターを公開して、実行時にエフェクトをスポーンします。対象は UE 5.8 です。（Niagara は従来の Cascade システムに代わるものです。）

使用する場面

• Niagara System（NS_）と Emitter（NE_）を作成するとき、Spawn／Update ステージにモジュールを組み込むとき、ゲームプレイで使用する User パラメーターを公開するとき、または Blueprint や C++ からエフェクト（衝撃、マズルフラッシュ、炎、魔法）をスポーン／操作するときに使用します。
• プロジェクトに Niagara の NS_／NE_ アセットがある場合、または UNiagaraComponent を参照している場合に使用します。

使用しない場面： マテリアル／シェーダーの作成（パーティクルではなく、表面の見た目に関するもの）は別のトピックです。エンジンをまたぐシェーダーの概念については shader-programming を参照してください。エフェクトのオーディオについては audio-design を参照してください。

基本的なワークフロー

1. 階層を理解します。 Niagara System（NS_）は、配置またはスポーンするエフェクトで、1 つ以上の Emitter（NE_。多くの場合、エミッターテンプレート）を含みます。各エミッターは、Emitter Spawn/Update、Particle Spawn/Update、任意の Event Handler、Render の各ステージを実行します。
2. Module から動作を構築します。 モジュールは各ステージで上から下へ実行されます（Spawn Rate、Add Velocity、Gravity Force、Color over Life など）。順序は重要です。後のモジュールは、先行するモジュールが書き込んだ値を読み取ります。
3. パラメーターの名前空間を把握します。 System、Emitter、Particle、User があります。Blueprint／C++ から公開・設定できるのは User 名前空間のパラメーターだけで、その他はシミュレーション内部で使用されます。
4. 実行時にスポーンします。 UNiagaraFunctionLibrary::SpawnSystemAtLocation（ワールド位置）または SpawnSystemAttached（コンポーネント／ソケットに追従）を使用します。どちらも UNiagaraComponent を返します。
5. エフェクトを操作します。 返されたコンポーネントで User パラメーター（色、スポーンレート、ターゲット位置など）を設定し、Activate／Deactivate を呼び出します。
6. 確認します。 Niagara エディターのプレビューとレベル内で動作を確認します。バウンズ（特に GPU エミッター）を確認し、エフェクトが正しくカリング／破棄されることを確かめます。

パターン

1. ワールド位置にワンショットエフェクトをスポーンする（C++）

#include "NiagaraFunctionLibrary.h"
#include "NiagaraComponent.h"

// ImpactSystem is a UPROPERTY(EditAnywhere) TObjectPtr<UNiagaraSystem>.
void AProjectile::SpawnImpact(const FVector& Location, const FRotator& Rotation)
{
    UNiagaraComponent* FX = UNiagaraFunctionLibrary::SpawnSystemAtLocation(
        GetWorld(), ImpactSystem, Location, Rotation);
    // FX auto-destroys when finished for a one-shot (system marked non-looping).
}

2. ソケットにアタッチしてスポーンする（銃に追従するマズルフラッシュ）

UNiagaraComponent* Muzzle = UNiagaraFunctionLibrary::SpawnSystemAttached(
    MuzzleSystem, WeaponMesh, FName("MuzzleSocket"),
    FVector::ZeroVector, FRotator::ZeroRotator,
    EAttachLocation::SnapToTarget, /*bAutoDestroy*/ true);

3. 実行時に公開された User パラメーターを操作する

// Only User-namespace parameters can be set from gameplay. Names match the User parameter.
if (UNiagaraComponent* Fire = UNiagaraFunctionLibrary::SpawnSystemAttached(
        FireSystem, RootComponent, NAME_None, FVector::ZeroVector, FRotator::ZeroRotator,
        EAttachLocation::KeepRelativeOffset, /*bAutoDestroy*/ false))
{
    Fire->SetVariableFloat(FName("SpawnRate"), 250.f);                 // User.SpawnRate
    Fire->SetVariableLinearColor(FName("FireColor"), FLinearColor::Red);
}

4. Blueprint での同等の処理（ノードの流れ）

Spawn System at Location (System = NS_Impact, Location, Rotation)  -> returns Niagara Component
On the returned component:
  Set Niagara Variable (Float)  Name="SpawnRate"  Value=250
  Set Niagara Variable (LinearColor)  Name="FireColor"  Value=Red

注意点

• ゲームプレイから System／Emitter／Particle パラメーターを設定しようとする — 設定は反映されません。User 名前空間で公開してください。コンポーネント経由で設定できるのは User パラメーターだけです。
• Cascade のチュートリアルを使用する — Cascade は従来の非推奨システムです。現在のシステムは Niagara であり、エミッター／モジュールのワークフローも異なります。
• エフェクトが消える、または正しくカリングされない — バウンズが固定されているか不正確な可能性があります。明示的な Fixed Bounds が必要な GPU Compute エミッターでは特に注意してください。エミッター／システムにバウンズを設定します。
• ループするエフェクトが停止しない — bAutoDestroy = false でスポーンした後、Deactivate() を呼び出していません。返されたコンポーネントのライフタイムを管理するか、ワンショットエフェクトではシステムを非ループに設定します。
• GPU シミュレーションからゲームプレイを操作できない — GPU パーティクルのデータは CPU に簡単には読み戻せません。ゲームプレイが反応する必要のある衝突／イベントには、GPU ではなく CPU エミッター（またはデータインターフェース経由で Niagara からゲームプレイへの連携）を使用してください。
• モジュール順序の不具合 — 値を初期化するモジュールより前に Force／Velocity モジュールを配置すると、ゼロを読み取ります。スタックの上から下への順序に注意してください。

参考資料

• 主要なドキュメント：「Niagara Effects の概要」 (https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine) および UNiagaraFunctionLibrary／UNiagaraComponent API。C++ から使用するには、*.Build.cs に Niagara モジュールを追加します。

関連スキル

• shader-programming — パーティクルマテリアル向けのマテリアル／シェーダーの概念。
• unreal-cpp-gameplay — ゲームプレイコードからのエフェクトのスポーンとモジュールの設定。
• unreal-blueprints — ビジュアルスクリプトからのエフェクトのトリガー。