niagara-vfx

name	niagara-vfx
description	Create and control visual effects using Unreal's Niagara system — UNiagaraSystem, UNiagaraComponent, UNiagaraFunctionLibrary; the system/emitter/module/parameter hierarchy; spawning effects at a world location or attached to an actor/socket (SpawnSystemAtLocation, SpawnSystemAttached); setting User Parameters from C++ (SetVariableFloat, SetVariableVec3, SetVariableActor, SetFloatParameter, SetColorParameter); CPU vs GPU simulation trade-offs; Data Interfaces (skeletal mesh, static mesh, collision); component lifetime management (bAutoDestroy, Activate/Deactivate, OnSystemFinished); and Niagara Data Channels. Use when spawning particle or VFX (fire, smoke, impacts, trails, magic), attaching effects to actors or sockets, driving an effect from gameplay parameters, choosing CPU vs GPU emitters, or migrating from Cascade (deprecated).
metadata	{"engine-version":"5.8","category":"vfx-audio"}

Niagara VFX

Niagara is Unreal's visual-effects system. It replaced Cascade (legacy — avoid for new work; a converter plugin exists). Effects are authored in the Niagara Editor as Systems composed of Emitters built from Modules, then spawned and parameterized from gameplay C++. Your role in C++ is: spawn a system, attach it, set its User Parameters, and manage its lifetime.

When to use this skill

• Spawning particle/VFX at a world location or attached to an actor or socket.
• Driving an effect from gameplay (color, intensity, beam target, spawn rate).
• Choosing between CPU and GPU emitters and budgeting their performance cost.
• Triggering effects from animation notifies or ability system cues.
• Integrating Data Interfaces (skeletal mesh surface, collision, splines).

System/emitter/module hierarchy

Level	Asset type	Runtime type	Role
System	UNiagaraSystem	FNiagaraSystemInstance (internal)	Top-level container; one per "effect" (e.g. NS_Explosion)
Emitter	UNiagaraEmitter	FNiagaraEmitterInstance (internal)	One particle behavior set (sparks, smoke, decal); several per system
Module	script asset	compiled HLSL	Single behavior (Add Velocity, Curl Noise, Sphere Location)
Parameter	FNiagaraVariable	FNiagaraParameterStore	Typed data (float, vector, bool, actor, DI) flowing through the stack

Execution flows top-to-bottom within each stack group: Emitter Spawn → Emitter Update → Particle Spawn → Particle Update → Event Handlers → Render. Each stage carries a namespace (System, Emitter, Particle, User, Engine) that controls read/write access.

User Parameters live in the User namespace and are the interface between C++ and the effect. Expose a parameter in the Niagara Editor, then set it at runtime.

Enable the Niagara plugin (on by default) and add "Niagara" to your module's Build.cs PublicDependencyModuleNames before using the C++ API.

Spawning from C++

#include "NiagaraFunctionLibrary.h"   // UNiagaraFunctionLibrary
#include "NiagaraComponent.h"         // UNiagaraComponent

// Fire-and-forget at a world location. bAutoDestroy=true (default) cleans up after completion.
UNiagaraComponent* Blast = UNiagaraFunctionLibrary::SpawnSystemAtLocation(
    this,           // world-context object
    BlastSystem,    // UPROPERTY(EditAnywhere) TObjectPtr<UNiagaraSystem>
    ImpactLocation,
    ImpactRotation);

// Attached to a component/socket — follows the actor, respects attachment rules.
UNiagaraComponent* Muzzle = UNiagaraFunctionLibrary::SpawnSystemAttached(
    MuzzleSystem, WeaponMesh, TEXT("MuzzleSocket"),
    FVector::ZeroVector, FRotator::ZeroRotator,
    EAttachLocation::SnapToTarget,
    /*bAutoDestroy*/ true);

Both functions return a UNiagaraComponent* (null if pre-cull check rejects it). Hold it in a UPROPERTY only when you need persistent control; for bursts, let bAutoDestroy handle cleanup.

For a persistent looping effect (aura, engine exhaust), create the component yourself:

// In actor constructor:
FX = CreateDefaultSubobject<UNiagaraComponent>(TEXT("FX"));
FX->SetupAttachment(GetRootComponent());
FX->SetAsset(AuraSystem);
FX->bAutoActivate = true;

// To toggle:
FX->Activate(/*bReset*/ true);
FX->Deactivate();                // stops emitting, lets existing particles finish
FX->DeactivateImmediate();       // kills particles immediately

Setting User Parameters at runtime

User parameters must be declared in the Niagara System editor (User namespace, exposed). Names must match exactly (case-sensitive, no namespace prefix needed via the Set* helpers):

// UFXSystemComponent base-class helpers (inherited by UNiagaraComponent):
FX->SetFloatParameter(TEXT("SpawnRate"),    500.f);
FX->SetColorParameter(TEXT("Color"),        FLinearColor::Red);
FX->SetVectorParameter(TEXT("BeamEnd"),     TargetLocation);
FX->SetActorParameter(TEXT("TargetActor"),  EnemyActor);

// UNiagaraComponent's own typed setters (use FName; preferred in 5.8):
FX->SetVariableFloat(TEXT("Intensity"),     1.5f);
FX->SetVariableVec3(TEXT("WindDir"),        FVector(1, 0, 0));
FX->SetVariableBool(TEXT("bIsActive"),      true);
FX->SetVariableInt(TEXT("BurstCount"),      5);
FX->SetVariableLinearColor(TEXT("BeamColor"), FLinearColor::Blue);
FX->SetVariableActor(TEXT("Target"),        TargetActor);

// Read back a parameter:
bool bValid = false;
float Rate = FX->GetVariableFloat(TEXT("SpawnRate"), bValid);

The SetNiagaraVariable* string-based variants (e.g. SetNiagaraVariableFloat) are deprecated since 5.3 — use the SetVariable* or Set*Parameter forms.

Component lifetime

Pattern	When to use
bAutoDestroy = true (default)	One-shot bursts (impacts, hit sparks) — component destroys itself
Persistent UPROPERTY component	Looping or toggle-able effects (aura, engines)
Pool via ENCPoolMethod	High-frequency spawning; pool reuse reduces allocation cost

// Subscribe to completion for custom cleanup or chaining:
FX->OnSystemFinished.AddDynamic(this, &AMyActor::OnFXFinished);

UFUNCTION()
void AMyActor::OnFXFinished(UNiagaraComponent* PSystem)
{
    // PSystem is finishing; if bAutoDestroy is false, destroy or return to pool here
}

Store persistent UNiagaraComponent* pointers in UPROPERTY members — bare pointers will be garbage collected (memory-and-gc).

CPU vs GPU simulation

Feature	CPU emitters	GPU emitters
Max particle count	~tens of thousands	millions
Gameplay read-back	yes (position queries, events)	not supported
Collision	depth-buffer, distance-field, ray-trace (5.7), or none	distance-field/scene-depth only
Per-particle callbacks	yes	no
Game-thread cost	scales with count	near-zero on game thread

Choose CPU when gameplay logic needs to read particle data or react to collisions. Choose GPU for massive counts (explosions, rain, ambient particles) where gameplay read-back is not required. Each emitter in a system chooses independently; a system can mix CPU and GPU emitters.

Data Interfaces

Niagara Data Interfaces (UNiagaraDataInterface, base class in NiagaraDataInterface.h) let emitters sample external data:

• Skeletal Mesh DI — emit from surface triangles, bones, or sockets; sample bone positions.
• Static Mesh DI — emit from static geometry; environment scatter.
• Collision Query DI — distance-field or ray-traced collision per-particle.
• Curve DI — sample a float/vector/color curve by time or particle age.
• Spline DI — distribute particles along a USplineComponent.
• Texture DI — sample a 2D texture for position/color masks.
• Render Target DI — read or write a UTextureRenderTarget2D on the GPU.
• Niagara Data Channel (5.3+) — cross-system particle communication via shared channels.

Set a mesh-based DI from C++ using the function library helpers:

// Bind a skeletal mesh component to a DI named "BodyMesh":
UNiagaraFunctionLibrary::OverrideSystemUserVariableSkeletalMeshComponent(
    FX, TEXT("BodyMesh"), GetMesh());

// Bind a static mesh component to a DI named "GroundMesh":
UNiagaraFunctionLibrary::OverrideSystemUserVariableStaticMeshComponent(
    FX, TEXT("GroundMesh"), StaticMeshComp);

Triggering from animation / gameplay events

• Anim Notifies (animation-system) — add a ANS_PlayNiagaraEffect notify to a montage or animation; it fires SpawnSystemAttached for you without C++.
• Gameplay Cues (gameplay-ability-system) — GAS spawns Niagara effects through UGameplayCueNotify subclasses; the cue handle targets the right location/effect automatically.
• Custom events/delegates — call SpawnSystemAtLocation or Activate from any UFUNCTION wired to a delegate.

Component pool

UNiagaraFunctionLibrary::SpawnSystemAtLocation accepts ENCPoolMethod::AutoRelease or ENCPoolMethod::ManualRelease to pull from a world-level UNiagaraComponentPool. Pooling is beneficial when the same system is spawned at high frequency (gunshots, footsteps). Avoid pooling for rare or once-per-level effects.

Gotchas

• Parameter name mismatch → Set*Parameter/SetVariable* silently no-ops; confirm names in the Niagara System editor (User namespace, exposed checkbox).
• Calling Set* before the asset is assigned → parameters are queued but may not apply; set the asset first (SetAsset()), then set parameters.
• Leaked persistent component — if bAutoDestroy = false and nothing destroys the component, it accumulates. Bind OnSystemFinished or call DestroyComponent().
• Persistent component not in a UPROPERTY → GC'd mid-effect; store it as a member.
• GPU emitter with gameplay read-back — not supported; the game thread cannot read per-GPU- particle data. Switch the emitter to CPU, or use NiagaraDataChannel for indirect communication.
• Heavy CPU particle counts → game-thread cost scales linearly; move to GPU or reduce counts. Use stat Niagara and the Niagara Debugger for live budgeting.
• Scalability culling — UNiagaraComponent integrates with the scalability manager; very- distant or budget-capped effects are pre-culled and SpawnSystemAtLocation returns null. Check for null before calling Set*.
• Cascade assets — UParticleSystem and UParticleSystemComponent are legacy; new work should use Niagara. The Cascade-to-Niagara Converter plugin (editor-only) assists migration.

Version notes

• SetNiagaraVariable* (string overloads) deprecated since 5.3; use SetVariable* (FName).
• GetSystemInstance() deprecated since 5.0; use GetSystemInstanceController().
• NiagaraDataChannel (cross-system communication) introduced in 5.3, expanded in 5.4/5.5.
• Lightweight Emitters (reduced overhead for simple effects) are in active development; see the Niagara Lightweight Emitters doc for current status.

References & source material

Engine source (UE 5.8, Engine/Plugins/FX/Niagara/Source/Niagara/):

• Public/NiagaraComponent.h — UNiagaraComponent: Activate:226, Deactivate:227, SetFloatParameter:72, SetColorParameter:74, SetVectorParameter:73, SetActorParameter:75, SetVariableFloat:533, SetVariableVec3:506, SetVariableActor:558, SetVariableBool:551, SetVariableInt:542, OnSystemFinished:754, bAutoDestroy:176, SetAsset:295, SetEmitterEnable:78.
• Classes/NiagaraSystem.h — UNiagaraSystem (derives UFXSystemAsset):238, GetExposedParameters:368, GetEmitterHandles:313.
• Public/NiagaraFunctionLibrary.h — UNiagaraFunctionLibrary: SpawnSystemAtLocation:93, SpawnSystemAttached:96, OverrideSystemUserVariableSkeletalMeshComponent:112, OverrideSystemUserVariableStaticMeshComponent:102.
• Classes/NiagaraDataInterface.h — UNiagaraDataInterface base class.
• Classes/NiagaraDataInterfaceSkeletalMesh.h — UNiagaraDataInterfaceSkeletalMesh.
• Public/NiagaraActor.h — ANiagaraActor (actor wrapper, SetDestroyOnSystemFinish).

Official docs (UE 5.8):

• Creating Visual Effects (Niagara) — https://dev.epicgames.com/documentation/unreal-engine/creating-visual-effects-in-niagara-for-unreal-engine
• Niagara Overview — https://dev.epicgames.com/documentation/unreal-engine/overview-of-niagara-effects-for-unreal-engine
• Niagara Key Concepts — https://dev.epicgames.com/documentation/unreal-engine/key-concepts-in-niagara-effects-for-unreal-engine
• Collisions in Niagara — https://dev.epicgames.com/documentation/unreal-engine/collisions-in-niagara-for-unreal-engine
• Niagara Data Channels — https://dev.epicgames.com/documentation/unreal-engine/data-channels-in-niagara-for-unreal-engine
• Debugging and Optimization in Niagara — https://dev.epicgames.com/documentation/unreal-engine/debugging-and-optimization-in-niagara-effects-for-unreal-engine
• Cascade to Niagara Converter Plugin — https://dev.epicgames.com/documentation/unreal-engine/cascade-to-niagara-effects-converter-plugin-for-unreal-engine

Deep-dive references in this skill:

• references/system-and-emitter-model.md — full system/emitter/module hierarchy, stack groups, namespaces, execution order, and inheritance.
• references/spawning-and-parameters.md — spawn variants, parameter store internals, pooling, and worked example.
• references/data-interfaces-and-performance.md — Data Interface catalog, CPU/GPU trade-off details, scalability, and the Niagara Debugger.

Related skills: animation-system, gameplay-ability-system, materials-and-shaders, asset-management, memory-and-gc.