unreal-niagara

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unreal Niagara VFX

Unreal Niagara 视觉特效

Build and control real-time visual effects in UE5 with Niagara: understand the System/Emitter/Module hierarchy, expose parameters you can drive from gameplay, and spawn effects at runtime. Targets UE 5.4+. (Niagara replaces the legacy Cascade system.)

使用Niagara在UE5中构建和控制实时视觉特效：理解System/Emitter/Module层级结构，暴露可由游戏玩法驱动的参数，并在运行时生成特效。适用于**UE 5.4+**版本。（Niagara已取代旧版Cascade系统。）

When to use

适用场景

Use when creating a Niagara System (
```
NS_
```
) and Emitters (
```
NE_
```
), wiring modules in the spawn/update stages, exposing User parameters to gameplay, or spawning/driving an effect (impact, muzzle flash, fire, magic) from Blueprint or C++.
Use when the project has Niagara
```
NS_
```
/
```
NE_
```
assets or references
```
UNiagaraComponent
```
.

When not to use: material/shader authoring (the look of a surface, not particles) is a separate topic;

shader-programming

covers cross-engine shader concepts. Audio for the effect →

audio-design

适用于创建Niagara System (
```
NS_
```
)和Emitter (
```
NE_
```
)、在生成/更新阶段连接模块、向游戏玩法暴露User参数，或者通过Blueprint或C++生成/驱动特效（如冲击效果、枪口火焰、火焰、魔法特效）时。
适用于项目中包含Niagara
```
NS_
```
/
```
NE_
```
资源或引用
```
UNiagaraComponent
```
时。

不适用场景： 材质/着色器创作（指表面外观，而非粒子）属于独立主题；

shader-programming

涵盖跨引擎着色器相关内容。特效相关音频请参考

audio-design

。

Core workflow

核心工作流程

Understand the hierarchy. A Niagara System (
```
NS_
```
) is the effect you place/spawn; it contains one or more Emitters (
```
NE_
```
, often emitter templates). Each emitter runs in stages: Emitter Spawn/Update, Particle Spawn/Update, optional Event Handler, and Render.
Build behaviour from Modules, which execute top-to-bottom in each stage (Spawn Rate, Add Velocity, Gravity Force, Color over Life, etc.). Order matters — a later module reads the values earlier ones wrote.
Know the parameter namespaces:
```
System
```
,
```
Emitter
```
,
```
Particle
```
, and User
. Only User-namespace parameters are exposed to and settable from Blueprint/C++; the others are internal to the simulation.
Spawn at runtime with
```
UNiagaraFunctionLibrary::SpawnSystemAtLocation
```
(world position) or
```
SpawnSystemAttached
```
(follows a component/socket), which return a
```
UNiagaraComponent
```
.
Drive the effect by setting its User parameters on the returned component (color, spawn rate, a target position) and
```
Activate
```
/
```
Deactivate
```
it.
Verify in the Niagara editor preview and in-level; check bounds (especially GPU emitters), and confirm the effect culls/destroys correctly.

理解层级结构。一个Niagara System (
```
NS_
```
)是你放置/生成的特效，它包含一个或多个Emitter (
```
NE_
```
，通常为发射器模板)。每个发射器按阶段运行：Emitter生成/更新、粒子生成/更新、可选的事件处理器以及渲染阶段。
通过模块构建行为，模块在每个阶段按从上到下的顺序执行（如生成速率、添加速度、重力、生命周期颜色等）。顺序至关重要——后续模块会读取之前模块写入的值。
了解参数命名空间：
```
System
```
、
```
Emitter
```
、
```
Particle
```
以及**
```
User
```
。只有User命名空间**的参数会暴露给Blueprint/C++并可被设置；其他参数仅用于模拟内部。
在运行时生成，使用
```
UNiagaraFunctionLibrary::SpawnSystemAtLocation
```
（世界位置）或
```
SpawnSystemAttached
```
（跟随组件/插槽），这两个方法会返回一个
```
UNiagaraComponent
```
。
驱动特效，通过返回的组件设置其User参数（如颜色、生成速率、目标位置），并调用
```
Activate
```
/
```
Deactivate
```
来激活/停用特效。
验证，在Niagara编辑器预览窗口和关卡中检查特效；检查边界（尤其是GPU发射器），并确认特效能正确剔除/销毁。

Patterns

常见模式

1. Spawn a one-shot effect at a world location (C++)

1. 在世界位置生成一次性特效（C++）

cpp

#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).
}

cpp

#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. Spawn attached to a socket (muzzle flash that follows the gun)

2. 生成并附着到插槽（跟随枪械的枪口火焰）

cpp

UNiagaraComponent* Muzzle = UNiagaraFunctionLibrary::SpawnSystemAttached(
    MuzzleSystem, WeaponMesh, FName("MuzzleSocket"),
    FVector::ZeroVector, FRotator::ZeroRotator,
    EAttachLocation::SnapToTarget, /*bAutoDestroy*/ true);

cpp

UNiagaraComponent* Muzzle = UNiagaraFunctionLibrary::SpawnSystemAttached(
    MuzzleSystem, WeaponMesh, FName("MuzzleSocket"),
    FVector::ZeroVector, FRotator::ZeroRotator,
    EAttachLocation::SnapToTarget, /*bAutoDestroy*/ true);

3. Drive an exposed User parameter at runtime

3. 在运行时驱动暴露的User参数

cpp

// 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);
}

cpp

// 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 equivalent (node flow)

4. Blueprint等效实现（节点流程）

text

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

text

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

Pitfalls

常见陷阱

Trying to set a System/Emitter/Particle parameter from gameplay — it won't take. Expose it in the User namespace; only User parameters are settable via the component.
Using Cascade tutorials — Cascade is legacy/deprecated. Niagara is the current system; the emitter/module workflow differs.
Effect disappears or doesn't cull right — fixed/incorrect bounds, especially for GPU Compute emitters which need explicit Fixed Bounds. Set bounds on the emitter/system.
Looping effect never stops — spawned with
```
bAutoDestroy = false
```
and never
```
Deactivate()
```
d; manage the returned component's lifetime, or mark the system non-looping for one-shots.
GPU sim can't drive gameplay — GPU particle data isn't readily read back to the CPU; collision/events that gameplay must react to should use CPU emitters (or Niagara → gameplay via the data interface), not GPU.
Module order bugs — a Force/Velocity module placed before the one that initializes the value reads zero. Mind the top-to-bottom stack order.

尝试从游戏玩法中设置System/Emitter/Particle参数——这不会生效。需将参数暴露在User命名空间中；只有User参数可通过组件设置。
使用Cascade教程——Cascade已过时/被弃用。Niagara是当前使用的系统，其发射器/模块工作流程与Cascade不同。
特效消失或无法正确剔除——边界设置错误或固定，尤其是GPU Compute发射器需要明确设置Fixed Bounds。需在发射器/系统上设置正确的边界。
循环特效无法停止——生成时设置了
```
bAutoDestroy = false
```
且从未调用
```
Deactivate()
```
；需管理返回组件的生命周期，或者将系统标记为非循环以用于一次性特效。
GPU模拟无法驱动游戏玩法——GPU粒子数据无法轻松回读到CPU；游戏玩法需响应的碰撞/事件应使用CPU发射器（或通过数据接口实现Niagara到游戏玩法的交互），而非GPU发射器。
模块顺序错误——Force/Velocity模块若放在初始化值的模块之前，会读取到零值。需注意从上到下的堆叠顺序。

References

参考资料

Primary docs: "Overview of Niagara Effects" (

https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine

) and the

UNiagaraFunctionLibrary

UNiagaraComponent

API. Add the

Niagara

module to

*.Build.cs

for C++ access.

主要文档：《Niagara特效概述》（

https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine

）以及

UNiagaraFunctionLibrary

UNiagaraComponent

API。若要在C++中使用，需将

Niagara

模块添加到

*.Build.cs

文件中。