unreal-niagara

Unreal Niagara VFX

使用 Niagara 在 UE5 中构建和控制实时视觉特效：了解 System/Emitter/Module 层级，公开可由游戏逻辑驱动的参数，并在运行时生成特效。目标版本为 UE 5.8。（Niagara 已取代旧版 Cascade 系统。）

适用场景

• 创建 Niagara System（NS_）和 Emitter（NE_）、在生成/更新阶段连接模块、向游戏逻辑公开 User 参数，或通过 Blueprint 或 C++ 生成/驱动特效（撞击、枪口焰、火焰、魔法）时使用。
• 项目包含 Niagara NS_/NE_ 资源或引用了 UNiagaraComponent 时使用。

**不适用场景：**材质/着色器创作（决定表面外观，而非粒子）是单独的主题；shader-programming 涵盖跨引擎着色器概念。特效音频 → audio-design。

核心工作流

1. 了解层级。 Niagara System（NS_）是要放置/生成的特效；它包含一个或多个 Emitter（NE_，通常是发射器模板）。每个发射器分阶段运行：Emitter Spawn/Update、Particle Spawn/Update、可选的 Event Handler，以及 Render。
2. 通过模块构建行为，模块在每个阶段内按从上到下的顺序执行（Spawn Rate、Add Velocity、Gravity Force、Color over Life 等）。顺序很重要——后续模块会读取先前模块写入的值。
3. 了解参数命名空间：System、Emitter、Particle 和 User。只有 User 命名空间的参数会公开给 Blueprint/C++ 并可由其设置；其他参数仅供模拟内部使用。
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；游戏逻辑需要响应的碰撞/事件应使用 CPU 发射器（或通过数据接口从 Niagara 传递到游戏逻辑），而非 GPU。
• 模块顺序错误——Force/Velocity 模块放在初始化数值的模块之前时会读到零。请注意从上到下的堆栈顺序。

参考资料

• 主要文档："Overview of Niagara Effects" （https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine） 以及 UNiagaraFunctionLibrary / UNiagaraComponent API。要在 C++ 中访问这些 API，请将 Niagara 模块添加到 *.Build.cs。

相关技能

• shader-programming — 粒子材质的材质/着色器概念。
• unreal-cpp-gameplay — 从游戏逻辑代码生成特效和模块设置。
• unreal-blueprints — 通过可视化脚本触发特效。