ue-niagara-effects

What this skill does

# 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

```cpp
#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);
}
```

### Attached to a Component (Persistent / Looping)

```cpp
// Attaches to a socket and stays active until manually deactivated.
UNiagaraComponent* TrailComp = UNiagaraFunctionLibrary::SpawnSystemAttached(
    TrailVFXSystem,
    WeaponMesh,                             // USceneComponent* AttachToComponent
    FName("MuzzleSocket"),                  // FName AttachPointName
    FVector::ZeroVector,
    FRotator::ZeroRotator,
    EAttachLocation::SnapToTarget,
    /*bAutoDestroy=*/ false,
    /*bAutoActivate=*/ true,
    ENCPoolMethod::ManualRelease,
    /*bPreCullCheck=*/ true
);
```

### Persistent Component on an Actor (Preferred for Repeated Use)

```cpp
// In header:
UPROPERTY(VisibleAnywhere)
TObjectPtr<UNiagaraComponent> EngineTrailVFX;

// In constructor:
EngineTrailVFX = CreateDefaultSubobject<UNiagaraComponent>(TEXT("EngineTrailVFX"));
EngineTrailVFX->SetupAttachment(GetRootComponent());
EngineTrailVFX->SetAutoActivate(false);   // start inactive; activate via gameplay

// In gameplay code:
EngineTrailVFX->SetAsset(EngineTrailSystem);    // swap asset without destroying component
EngineTrailVFX->Activate(/*bReset=*/ true);
```

### Lifecycle Control

```cpp
NiagaraComp->Activate(/*bReset=*/ false);       // activate; resume if paused
NiagaraComp->Activate(/*bReset=*/ true);        // activate with full reset
NiagaraComp->Deactivate();                      // stop spawning, let particles drain
NiagaraComp->DeactivateImmediate();             // kill all particles immediately
NiagaraComp->ResetSystem();                     // restart from time 0
NiagaraComp->ReinitializeSystem();              // full re-init + restart (expensive; prefer ResetSystem)
NiagaraComp->SetPaused(true);                   // pause simulation
NiagaraComp->SetAutoDestroy(true);              // destroy component when system finishes
```

---

## Setting Parameters from C++

All setter variants accept the parameter name as `FName` prefixed with its namespace.
User-exposed parameters use the `User.` prefix.

```cpp
// Scalar types
NiagaraComp->SetVariableFloat(FName("User.DamageAmount"), 150.f);
NiagaraComp->SetVariableInt(FName("User.ProjectileCount"), 12);
NiagaraComp->SetVariableBool(FName("User.bIsCritical"), bIsCriticalHit);

// Vector types
NiagaraComp->SetVariableVec2(FName("User.UVOffset"), FVector2D(0.5, 0.25));
NiagaraComp->SetVariableVec3(FName("User.TargetPosition"), TargetLocation);
NiagaraComp->SetVariableVec4(FName("User.CustomData"), FVector4(1, 0.5, 0, 1));
NiagaraComp->SetVariableLinearColor(FName("User.TintColor"), FLinearColor::Red);
NiagaraComp->SetVariableQuat(FName("User.Orientation"), GetActorQuat());

// Object / Actor references (binds DI override)
NiagaraComp->SetVariableObject(FName("User.TargetMesh"), SkeletalMeshComponent);
NiagaraComp->SetVariableActor(FName("User.SourceActor"), this);

// Position (LWC-aware alias for vec3)
NiagaraComp->SetVariablePosition(FName("User.WorldOrigin"), WorldSpaceOrigin);

// Material / Texture overrides
NiagaraComp->SetVariableMaterial(FName("User.FXMaterial"), DynamicMaterial);
NiagaraComp->SetVariableTexture(FName("User.FlowMap"), FlowTexture);

// Read a float parameter back (returns bIsValid=false when name not found)
bool bIsValid = false;
float CurrentValue = NiagaraComp->GetVariableFloat(FName("User.EmitRate"), bIsValid);
```

### Blueprint-Accessible Legacy Signatures (prefer FName variants above)

```cpp
// Old FString signatures still work but are slower due to FName conversion.
NiagaraComp->SetNiagaraVariableFloat(TEXT("User.SpeedScale"), 2.f);
NiagaraComp->SetNiagaraVariableVec3(TEXT("User.ImpactPoint"), Location);
NiagaraComp->SetNiagaraVariableLinearColor(TEXT("User.Color"), FLinearColor::Blue);
```

### Parameter Namespaces Reference

| Namespace prefix | Settable from C++ | Description                          |
|------------------|-------------------|--------------------------------------|
| `User.`          | Yes               | User-exposed; main runtime override  |
| `System.`        | No (read-only)    | System-level built-ins (Age, DeltaTime, etc.) |
| `Emitter.`       | No (internal)     | Per-emitter variables                |
| `Particle.`      | No (internal)     | Per-particle variables               |

See `references/niagara-parameter-types.md` for the full C++ type to Niagara type mapping.

---

## Data Interfaces from C++

Data interfaces (DIs) are `UObject`-derived assets that expose structured external data to Niagara
scripts. They appear as `User.*` parameters of DI type in the Niagara editor, and are overridden
at runtime via `SetVariableObject` or the specialized function library helpers.

### Binding Skeletal Mesh DI

```cpp
#include "NiagaraFunctionLibrary.h"

// Override the "User.SourceMesh" skeletal mesh DI on a running component.
UNiagaraFunctionLibrary::OverrideSystemUserVariableSkeletalMeshComponent(
    NiagaraComp,
    TEXT("User.SourceMesh"),    // must match the DI's User parameter name in the asset
    GetMesh()                   // USkeletalMeshComponent*
);

// Restrict which bones spawn from (destructive — modifi