niagara-authoring
Create, modify, compile, and visually evaluate AAA-quality Niagara particle systems in the editor.
SKILL.mdUnrealEngine/skills/niagara-authoring/SKILL.md
GitHubSkill: Niagara VFX Authoring
This skill defines the workflows, architectural rules, and standard operating procedures (SOPs) for AI agents to create, modify, compile, parameterize, and visually evaluate AAA-quality Unreal Engine 5 Niagara particle systems.
1. Niagara Architecture & Stack Execution Flow
A Niagara System executes in hierarchical phases. Modules in each phase execute sequentially from top to bottom:
UNiagaraSystem
├── System Phases:
│ ├── SystemSpawn (Initial system initialization)
│ └── SystemUpdate (Per-frame system lifetime, system parameters)
└── UNiagaraEmitter (One or more emitters per system)
├── Emitter Phases:
│ ├── EmitterSpawn (Emitter lifetime, burst intervals)
│ └── EmitterUpdate (Spawn rate, burst triggers)
├── Particle Phases:
│ ├── ParticleSpawn (Initial particle attributes: Location, Velocity, Mass, Lifetime, Color, Size)
│ ├── ParticleUpdate (Per-frame attribute mutation: Forces, Drag, Acceleration, Color Curves, Collision)
│ └── ParticleEvent (Event response: OnCollision, OnDeath, Location events)
└── Renderers:
└── SpriteRenderer / MeshRenderer / RibbonRenderer / LightRenderer / DecalRenderer
Module Stack Ordering Rules
- Solvers Last in Update: When using physics forces (
GravityForce,Drag,AccelerationForce,PointAttractor), always ensureSolveForcesAndVelocityis placed after all force modules inParticleUpdate. - Age & Lifetime First:
UpdateAgemust run inParticleUpdatebefore size/color scale modules that sample particle normalized age (Particles.NormalizedAge). - Spawn Position Before Velocity: Place spawn shape/location modules (
SphereLocation,BoxLocation,CylinderLocation) beforeAddVelocity.
2. Standard Tool Workflow
Step 1: Asset Initialization
- Create System:
{ "_tool_name": "create_niagara_system", "asset_path": "/Game/VFX/NS_Explosion" } - Create Effect Type (Scalability & LODs):
{ "_tool_name": "create_niagara_effect_type", "asset_path": "/Game/VFX/NE_ExplosionScalability" } - Create Niagara Data Channel (High-Frequency Decoupled Events):
{ "_tool_name": "create_niagara_data_channel", "asset_path": "/Game/VFX/NDC_Impacts" }
Step 2: Add Emitters
Append clean template emitters or duplicate from existing systems using add_niagara_emitter.
- Stock Templates:
SpriteBurst,RibbonTrail,MeshDebris,GPUSimulation, or any engine template path (e.g./Niagara/DefaultAssets/Templates/Emitters/SimpleSpriteBurst.SimpleSpriteBurst). - From Existing System: Pass
system_pathandemitter_templateas the source system, with optionalsource_emitter_nameto extract a specific emitter. - Note: The engine automatically duplicates the template into the system's private package, ensuring templates on disk are never contaminated.
{
"_tool_name": "add_niagara_emitter",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_template": "SpriteBurst",
"emitter_name": "CoreFlash"
}
Step 3: Add Logic Modules (add_niagara_module)
Inject stock or custom modules into any execution phase (SystemSpawn, SystemUpdate, EmitterSpawn, EmitterUpdate, ParticleSpawn, ParticleUpdate, ParticleEvent):
- Stock Module Names:
AddVelocity,GravityForce,Drag,Collision,AccelerationForce,SpawnBurstInstantaneous,SpawnRate,ScaleSpriteSize,ScaleColor,SolveForcesAndVelocity,UpdateAge,SphereLocation,BoxLocation,PointLocation. - Asset Path Lookup: Pass full content paths (e.g.
/Niagara/Modules/Spawn/Location/SphereLocation.SphereLocationor project scripts/Game/VFX/Modules/M_CustomForce). - Phase Rules:
- For
SystemSpawnorSystemUpdate, omitemitter_name. - For emitter/particle phases, provide
emitter_name. - Use
target_index(0-based) to insert at a precise position in the stack.
- For
{
"_tool_name": "add_niagara_module",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_type": "Drag",
"target_index": 1
}
Step 4: Configure Pins, Direct Data Interfaces & Reset Pins
- Flexible Input Modes: Provide either:
- Literal
value(e.g."1.5","(X=0,Y=0,Z=-980)","(R=1,G=0.5,B=0,A=1)") link_parameter(e.g."User.PrimaryColor","Particles.NormalizedAge")- Direct Data Interface / Asset Input: Provide
asset_path,interface_class, and/orpropertiesdirectly to configure the pin's internal Data Interface without needing an intermediate User parameter (ideal when the asset/channel does not need runtime gameplay rebinding).
- Literal
- Targeting Multiple Modules: When an emitter contains multiple modules of the same type, use
module_index(0-based) ornode_guidto target the exact instance.
// Example 1: Linking to an existing parameter
{
"_tool_name": "set_niagara_module_pin",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_type": "ScaleColor",
"pin_name": "ScaleAlpha",
"link_parameter": "Particles.NormalizedAge"
}
// Example 2: Direct Data Interface configuration on module input
{
"_tool_name": "set_niagara_module_pin",
"system_path": "/Game/VFX/NS_ImpactListener",
"emitter_name": "ListenerEmitter",
"phase": "ParticleUpdate",
"module_type": "ReadFromDataChannel",
"pin_name": "DataChannel",
"interface_class": "NiagaraDataInterfaceDataChannelRead",
"asset_path": "/Game/VFX/NDC_Impacts"
}
- Direct Curve Module Input (
set_niagara_module_pinwithcurve_keys): To configure an inline curve data interface (e.g.ScaleSpriteSize.Uniform Curve Sprite ScaleorScaleColor.ScaleAlpha) directly on a module input pin:
{
"_tool_name": "set_niagara_module_pin",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_type": "ScaleSpriteSize",
"pin_name": "Uniform Curve Sprite Scale",
"curve_keys": [
{ "time": 0.0, "value": 1.0 },
{ "time": 1.0, "value": 0.0 }
]
}
For multi-channel curves (e.g. NiagaraDataInterfaceColorCurve or vector curves), pass an object keyed by channel name:
{
"_tool_name": "set_niagara_module_pin",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_type": "ScaleColor",
"pin_name": "Linear Color Curve",
"curve_keys": {
"Red": [{ "time": 0.0, "value": 1.0 }, { "time": 1.0, "value": 0.2 }],
"Green": [{ "time": 0.0, "value": 0.8 }, { "time": 1.0, "value": 0.0 }],
"Blue": [{ "time": 0.0, "value": 0.1 }, { "time": 1.0, "value": 0.0 }]
}
}
Note: Multi-channel curves also accept channel abbreviations ("R", "G", "B", "A", "X", "Y", "Z"), or a flat array [{"time": 0.0, "value": 1.0}, ...] to apply uniformly across all channels. Ensure the module's mode switch (e.g. ScaleColor's Color Scale Mode = RGBA Linear Color Curve) is set so the curve pin is active.
Inspect existing curve keys on any curve DI module input using list_niagara_parameters with scope "ModuleInput", "GraphInput", or "all".
- Resetting Module Pins (
reset_niagara_module_pin): To remove an input override, restore autogenerated default values on static switches, and clean up upstream exclusive or orphaned input nodes:
{
"_tool_name": "reset_niagara_module_pin",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_type": "ScaleColor",
"pin_name": "ScaleAlpha",
"clean_orphaned_nodes": true
}
- Dynamic Input Scripts on Module Pins (
dynamic_input): To attach a dynamic calculation script (e.g.Multiply_Int,Multiply_Float,Divide_Float) to a module pin instead of a literal constant:
{
"_tool_name": "set_niagara_module_pin",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "EmitterUpdate",
"module_type": "SpawnBurstInstantaneous",
"pin_name": "Spawn Count",
"dynamic_input": "Multiply_Int"
}
Step 5: Configure & Manage Renderers
Add visual renderers (add_niagara_renderer), update existing renderers (edit_niagara_renderer), or remove unwanted/default renderers (remove_niagara_renderer):
- Add Renderer:
{
"_tool_name": "add_niagara_renderer",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"renderer_type": "Light",
"properties": {
"RadiusScale": 250.0,
"bCastShadows": false
}
}
- Edit Renderer (modify properties or enable/disable):
{
"_tool_name": "edit_niagara_renderer",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"renderer_name_or_type": "SpriteRenderer",
"b_is_enabled": false,
"properties": {
"Material": "/Game/Materials/M_ParticleGlow"
}
}
- Remove Renderer:
{
"_tool_name": "remove_niagara_renderer",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"renderer_name_or_type": "SpriteRenderer"
}
Removing Modules & Emitters
- Remove Module (
remove_niagara_module):
{
"_tool_name": "remove_niagara_module",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash",
"phase": "ParticleUpdate",
"module_name": "Drag"
}
- Remove Emitter (
remove_niagara_emitter):
{
"_tool_name": "remove_niagara_emitter",
"system_path": "/Game/VFX/NS_Explosion",
"emitter_name": "CoreFlash"
}
Step 6: Expose Parameters, Bind Data Interfaces & Inspect
- Parameter Store Scope Rules:
set_niagara_parameterandset_niagara_data_interfaceconfigure the UNiagaraSystem asset's parameter store (User.scope).Emitter.andSystem.scopes are internal to execution graphs and cannot be written directly to the asset parameter store. To configure emitter/system-level inputs, useset_niagara_module_pindirectly or expose aUser.parameter and link it.
- User Parameters (
set_niagara_parameter): Expose parameters for Blueprints, C++, or material overrides:{ "_tool_name": "set_niagara_parameter", "system_path": "/Game/VFX/NS_Explosion", "parameter_name": "User.PrimaryColor", "data_type": "LinearColor", "value": "(R=1.0,G=0.4,B=0.05,A=1.0)" } - User Data Interfaces (
set_niagara_data_interface): When gameplay code or Blueprints need to dynamically assign or modify data interfaces at runtime:- Bind the external data interface to a
User.parameter viaset_niagara_data_interface:{ "_tool_name": "set_niagara_data_interface", "system_path": "/Game/VFX/NS_ImpactListener", "parameter_name": "User.NDCReader", "interface_class": "NiagaraDataInterfaceDataChannelRead", "asset_path": "/Game/VFX/NDC_Impacts", "asset_property_name": "DataChannelAsset" } - Link the module pin to that
User.parameter viaset_niagara_module_pin:{ "_tool_name": "set_niagara_module_pin", "system_path": "/Game/VFX/NS_ImpactListener", "emitter_name": "ListenerEmitter", "phase": "ParticleUpdate", "module_type": "ReadFromDataChannel", "pin_name": "DataChannel", "link_parameter": "User.NDCReader" }
- Bind the external data interface to a
- Multi-Scope Parameter Inspection (
list_niagara_parameters): Inspect parameters across any scope (all,User,System,Emitter,ModuleInput,GraphInput), including bound assets, DI classes, module input overrides, and detection of orphaned graph input nodes:{ "_tool_name": "list_niagara_parameters", "system_path": "/Game/VFX/NS_Explosion", "scope": "all", "include_module_inputs": true, "include_orphaned_nodes": true } - Parameter Cleanup (
remove_niagara_parameter): Remove obsolete, misspelled, or orphaned parameters from the system parameter store:{ "_tool_name": "remove_niagara_parameter", "system_path": "/Game/VFX/NS_Explosion", "parameter_name": "User.ObsoleteParam" }
Step 7: Synchronous Compilation Verification
Call compile_niagara_system to build bytecode and verify zero compilation errors across all system, emitter, and event scripts:
{
"_tool_name": "compile_niagara_system",
"system_path": "/Game/VFX/NS_Explosion"
}
Step 8: Temporal Vision Capture Loop
Call capture_niagara_system_isolated to render a 2x2 keyframe grid (10%, 30%, 60%, 90% simulation window):
{
"_tool_name": "capture_niagara_system_isolated",
"system_path": "/Game/VFX/NS_Explosion",
"duration_seconds": 1.5,
"max_dimension": 512
}
- Inspect the returned image artifact:
- Check quadrant 1 (10%): Initial burst shape, core flash intensity.
- Check quadrant 2 (30%): Expansion velocity, debris dispersal.
- Check quadrant 3 (60%): Drag deceleration, smoke volume buildup.
- Check quadrant 4 (90%): Alpha fade, scale dissipation, zero hard pop artifacts.
- Inspect the bottom-left 1-meter white scale indicator bar to verify physical world sizing.
3. General VFX Design Recipes
Recipe A: Instantaneous Burst (Explosions, Impacts, Muzzle Flashes)
- Emitter: Add
SpriteBurstor cloneSimpleSpriteBurst. - EmitterUpdate: Add
SpawnBurstInstantaneous, setSpawnCountto desired particle count (e.g. 50–200). - ParticleSpawn:
- Add
SphereLocation(orBoxLocation) with radius ~20–50cm. - Add
AddVelocitywith radial velocity 500–1500 cm/s. - Set
Lifetimerange (e.g. Min: 0.3s, Max: 0.8s).
- Add
- ParticleUpdate:
- Add
Drag(value: 2.0–5.0) to rapidly decelerate high-speed particles. - Add
ScaleSpriteSizeorScaleColorlinked toParticles.NormalizedAge. - Add
SolveForcesAndVelocityat the end ofParticleUpdate.
- Add
- Renderer: Add
LightRendererwithRadiusScale: 300.0for dynamic flash.
Recipe B: Continuous Ambient Stream (Fire, Smoke, Steam)
- Emitter: Add
GPUSimulationorSpriteBursttemplate. - EmitterUpdate: Add
SpawnRate(e.g. 50–500 particles/sec). - ParticleSpawn:
- Add
SphereLocationorPointLocation. - Add
AddVelocitywith upward cone direction(X=0, Y=0, Z=150). - Set
Lifetimerange (e.g. 1.5s–3.0s).
- Add
- ParticleUpdate:
- Add
AccelerationForcepointing upwards(X=0, Y=0, Z=100). - Add
ScaleSpriteSizewith a curve expanding size over lifetime. - Add
ScaleColorfading alpha to 0.0 atNormalizedAge: 1.0. - Add
SolveForcesAndVelocity.
- Add
- Renderer: Ensure the assigned material uses
DepthFadeto prevent clipping against geometry.
Recipe C: Physical Debris / Sparks
- Emitter: Add
MeshDebrisorSpriteBurst. - ParticleSpawn:
- Add
AddVelocitywith high random cone velocity. - Set
Mass(e.g. 1.0–5.0).
- Add
- ParticleUpdate:
- Add
GravityForce(X=0, Y=0, Z=-980). - Add
Collisionmodule withRestitution: 0.4andFriction: 0.2. - Add
SolveForcesAndVelocity.
- Add
- Renderer: Add
MeshRendererand setMeshesproperty to a debris static mesh.
4. Advanced Architectural Patterns
Niagara Data Channels (NDCs) for High-Frequency Events
- Never use
SpawnSystemAtLocationfor high-frequency or overlapping events (e.g. machine gun impacts, footsteps, shell casings, sparks). Spawning individual actor components for repetitive events creates heavy GC and draw call overhead. - Architecture:
- Create a Data Channel asset (
create_niagara_data_channel). - Setup a persistent listener Niagara System with
set_niagara_data_interface(NiagaraDataInterfaceDataChannelRead). - Blueprints or C++ traces write compact hit matrices and material IDs directly to the channel.
- Create a Data Channel asset (
Scalability & Effect Types
- Assign an
EffectTypeto every production asset: Distance culling, max instance budgets, and LOD culling prevent frame drops during intense gameplay. - Culled at low scalability: dynamic light renderers, secondary sub-emitters, mesh debris.
5. Performance Optimization Checklist
- GPU Simulation: If particle count $\ge 1,000$, use GPU simulation target (
SimTarget = ENiagaraSimTarget::GPUSim). - Fixed Bounds: Always enable Fixed Bounds on finished assets to eliminate per-frame bounding box recalculations.
- Translucency Softness: For smoke/fire sprites, assign materials configured with
DepthFadeto prevent hard clipping against world geometry. - Scalability Assigned: Ensure every asset is tied to a valid
EffectTypewith distance culling enabled. - SolveForces Order: Ensure
SolveForcesAndVelocityis the last module inParticleUpdatewhenever forces or velocities are modified.