ue-niagara-effects

UE Niagara Effects

You are an expert in controlling Unreal Engine's Niagara VFX system from C++.

Context Check

Read .agents/ue-project-context.md before proceeding. Confirm:

• The Niagara plugin is listed under enabled plugins (Plugins/FX/Niagara).
• The target module's Build.cs has "Niagara" (and optionally "NiagaraCore") in PublicDependencyModuleNames.
• Platform targets: note whether mobile or dedicated-server builds are in scope, because Niagara is typically suppressed on dedicated servers and may need LOD simplification on mobile.

Information Gathering

Before writing Niagara C++ code, clarify:

1. Effect lifecycle — one-shot (fire and forget) or persistent / looping?
2. Parameter needs — which Niagara User Parameters must be set from gameplay (positions, colors, scalars)?
3. Data interfaces required — SkeletalMesh, StaticMesh, Curve, Array, or custom?
4. Simulation target — CPU or GPU sim? (affects which DI features are available)
5. Performance budget — pooling required? Mobile scalability tier?
6. Completion handling — does gameplay need a callback when the effect finishes?

---

System Structure (UE Concept Map)

UNiagaraSystem  (asset: UNiagaraSystem)
  └── UNiagaraEmitter[]         (per-emitter asset, referenced via FNiagaraEmitterHandle)
        └── UNiagaraScript[]   (Spawn / Update / Event scripts; authored in Niagara editor)
              └── Modules       (stack of NiagaraScript nodes; not C++ classes)

Runtime instances:
  UNiagaraComponent             (scene component that drives one UNiagaraSystem instance)
    └── FNiagaraSystemInstance  (internal runtime state; access via GetSystemInstanceController())

Key rule: authors expose parameters to C++ by setting their namespace to User. in the Niagara editor. Only User.* parameters can be overridden at runtime from C++.

---

Spawning Niagara Systems

Fire-and-Forget (One-Shot) at World Location

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

// Minimal one-shot spawn — component auto-destroys when the system completes.
UNiagaraComponent* NiagaraComp = UNiagaraFunctionLibrary::SpawnSystemAtLocation(
    this,                           // WorldContextObject
    ImpactVFXSystem,                // UPROPERTY(EditAnywhere) UNiagaraSystem*
    HitLocation,                    // FVector Location
    FRotator::ZeroRotator,          // FRotator Rotation
    FVector(1.f),                   // FVector Scale
    /*bAutoDestroy=*/ true,
    /*bAutoActivate=*/ true,
    /*PoolingMethod=*/ ENCPoolMethod::AutoRelease,   // use pool when available
    /*bPreCullCheck=*/ true
);

// Set parameters before the first tick if needed.
if (NiagaraComp)
{
    NiagaraComp->SetVariableVec3(FName("User.HitNormal"), HitNormal);
    NiagaraComp->SetVariableLinearColor(FName("User.HitColor"), DamageColor);
}