ue-niagara-vfx

Niagara VFX

For effect-specific design, use ue-niagara-flamethrower for sustained flame jets, ue-niagara-renderers-and-materials for visible particle geometry, ue-niagara-sequenced-effects for timed multi-emitter effects, ue-niagara-custom-modules for custom particle logic and events, or ue-niagara-mesh-disintegration for mesh-sampled dissolution.

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

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

// 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 (ue-memory-and-gc).

CPU vs GPU simulation

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 (ue-animation-system) — add a ANS_PlayNiagaraEffect notify to a montage

or animation; it fires SpawnSystemAttached for you without C++.

• Gameplay Cues (ue-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: ue-animation-system, ue-gameplay-ability-system, ue-materials-and-shaders, ue-asset-management, ue-memory-and-gc.