FluidNinja VFX Tools

Niagara Manual

Document updated: 18 February 2021

Latest FluidNinja VFX Tools version: 1.4.0.0
Latest supported UE version: 4.26.1

NinjaTools 1.4 comes with improved Ninja-to-Niagara data pipeline, introducing

fully autonomous Niagara Systems that do not rely on blueprint func ons.
More info: Ninja 1.4 vs 1.3 chapter

NinjaTools is genera ng and processing baked fluid simula on.

For real me (non-baked) fluid simula on, see: NinjaLIVE
For standalone Niagara Flipbook player, see: NinjaPLAY

Support: [email protected]
Updates, news: h ps://twi er.com/FluidNinjaVFX
Project home page: unrealengine.com/marketplace/fluidninja-vfx-tools

Tutorials, Previews:
h ps://www.youtube.com/playlist?list=PLVCUepYV6TvObCSpGGtWPi98lvHXA1_rw

Document share URL:

h ps://drive.google.com/file/d/19FAnIfwJHfMHNUnkEApoVu18LHgPjVN4
Intro Links

A step-by-step guide to build basic texture sampling emi ers: PDF / ARTICLE
In this project we are combining (A) pre-rendered and (B) genera ve approaches:

A. driving par cle masses with baked 2D fluid simula on data

B. using the baked data in addi ve / genera ve manner

Example 1: accelera ng par cles with baked velocity fields, while allowing them
to collide with scene objects - making the par cle flow somewhat responsive
Example 2: raymarching baked simula on density in real me and use the result
as par cle color - making the par cle cloud shaded by actual scene ligh ng

Baked density and velocity data is stored as flipbooks - and could be sampled two ways:

A. inside Niagara, using Ninja FlipbookPlayer Module (introduced in NinjaTools v 1.4)

NinjaPlayer is also available as a standalone package: LINK
B. outside Niagara, using Material based Flipbook players - then wri en to a
RenderTarget every frame - and re-sampled in Niagara using the built in Texture
Sample module (this method has been used in NinjaTools v 1.3).
Method “A” is op mal ---> these systems perform be er compared to “B”
In the above tutorial we are building two Niagara Systems from scratch. One that is se ng
In both cases: sampling converts raw sim data to float and vector values that could be ini al par cle proper es by sampling a simple flow map texture - and by modifying this, a
used to modify all kinds of par cle a ributes, like posi on, scale, color, velocity, second system that is dynamically altering condi ons by sampling a flipbook.
accelera on, drag… etc. All assets provided. We are ending up with this scene: LINK

More Ninja/Niagara related links

Genera ng sim data
1 minute project intro: LINK 4 minutes project overview: LINK
The data that drives par cles generated inside Unreal Editor via NinjaTools. 5 minutes video on UV coords: LINK 10 mins on demo level contents: LINK
It is extremely small - as opposed to VDBs or other animated volumetric data. 20 minutes on technical details: LINK
Comparison: a single frame of the classic 512px Stanford Bunny VDB is 74 Mbytes -
while our genera ve data is typically in the 1-4 Mbytes range with 8-32 frames. Niagara tests playlist: LINK Ninja playlist: LINK
Ninja at UE marketplace: LINK Ninja User Manual: LINK
Contents

Intro, Links 3
Demo Project structure 6
Core assets / asset loca ons 12
Baking fluidsim in UE 13
Texture Sampling Pipeline 13
Texture sampling UV from Spawning loca on 14
Generated and Sta cMesh based UVs
2 Emi er setups

Fluidsim data usage, examples 15

Input variables, User Parameters 16
Embedded structures
Se ng up systems
Se ng up autonomous and blueprint dependent systems 17
NinjaTools 1.4 vs 1.3 18

This documenta on is primarily made to support FluidNinja Niagara modules

and Tutorial levels, but provides knowhow for everybody who would like to use
baked fluidsim to drive Niagara Systems.

Niagara Tools and example levels are included in Ninja version 1.4 for UE 4.25 / 4.26
In case if you download Ninja for UE 4.20 - 4.24, Niagara contents are NOT included.
Demo Project structure

FluidNinja 1.4 comes with five Niagara example levels. Level contents demonstrate how to For the purposes of raymarching demonstra on, NiagaraSystem-Container Blueprint has
u lize already baked fluid data to drive and shade GPU par cle systems. been created. Some systems placed on level are embedded to an instance of this blueprint.
The blueprint contains debug func ons and pre-processes data for NiagaraSystems (eg.:
It is important to know that data could flow the other way too: Ninja could read writes RenderTargets for the Niagara TextureSampler, calculates light direc on vector for
Niagara systems as simula on input and generate fluidsim based on Niagara par cles. Raymarching...etc.) Typically, users would include NiagaraSystems in their projects, and
So, we have two-way data flow between Ninja and Niagara. Genera ng & baking transfer only the needed blueprint func ons to their own control-classes (the actors or
fluidsim is covered by other tutorials and example levels (see the manual and the actor-components that spawn / control niagara systems in their projects).
youtube playlist) - we are skipping this part now.

Returning to the Niagara example project structure:

● The Niagara use-case levels are populated by NiagaraSystems

● All systems use / reference three basic, pre-constructed NiagaraEmi ers
● The base emi ers are built using (A) standard and (B) custom NiagaraModules

Users could employ these tools in their own projects many ways:

● Generate new fluid data with Ninja Core and use this data as input for the
provided NiagaraSystems (easy - see Se ng up systems chapter)
● Customize systems: tweak params / disable modules / add modules to base
emi ers (needs a few hours of experimen ng)
● Create new emi ers to extend or modify func onality (needs a bit of Niagara
know-how)
● Re-construct custom modules to achieve new func onali es (medium level)
Smoke Level: various data pipelines using a smoke loop
Smoke Level: shading pipeline enabled - resul ng real- me dynamic ligh ng
CloudVortex Level: various data pipelines using a vortex loop
Flower Level: combining a classic painted texture (as density map) with simula on velocity
data to create a swirling ou low / “magic circle” VFX ( also see cover page, middle pic)
Ninja Base Emi er and Custom Modules in Niagara Editor
Core assets / asset loca ons

5 Niagara demo levels:

Located at: /Content/FluidNinja/Levels/
- Usecases_Niagara_*
*CloudVortex, Flower, Intro, Smoke, TiledPa ern

1 NiagaraSystem container blueprint:

Located at: /Content/FluidNinja/Usecases/Niagara/SystemsRaymarching/
- BP_FluidNinja_NiagaraSystemContainer

25 NiagaraSystems:
Located at: /Content/FluidNinja/Usecases/Niagara/*
*Systems, SystemsRaymarching
NS_*.*, (Eg.: NS_FlowerAndRunes_2tx_VeloDensity_VeloAddi ve_Stylized.uasset)

NiagaraEmi ers and custom NiagaraModules:

Located at: /Content/FluidNinja/Core/Niagara/

- NE_FluidNinja_FlipbookPlayerEmi er
- NE_FluidNinja_Ini alStateEmi er
- NE_FluidNinja_Sta cMeshWithFlipbookEmi er

- NM_FluidNinja_FlipbookPlayer
- NM_FluidNinja_Mul TextureModule
- NM_FluidNinja_PostsolverPosi onOffsetModule
Baking fluidsim in UE

Simula on is performed real- me in Unreal Editor by FluidNinja

Core Tools - and baked to Unreal Texture2D objects instantly.
The materials that embed and play-back baked data are
automa cally generated (NinjaPlay Material Instances).

“Blueprint dependent” Niagara Systems (Ninja 1.3) need these

materials to access flipbook data.
Systems introduced in Ninja 1.4 contain their own, internal
flipbook player as Niagara module - they do not need blueprints
and materials to access flipbooks.

For more details on simula on & baking :

see FluidNinja Manual PDF and tutorial videos.

Manual: drive.google.com/file/d/1eRQtcUtkkL6idelmbsfXCO03pbqBuwRu
Videos: nyurl.com/vs2l9a9 Why do we need the two-step method at all?

We need to process flipbook data in two steps, in case we would like to generate some
Texture Sampling Pipeline flipbook-derived, dynamic data every frame - like raymarching based self shadows.
We can not apply a raymarching shader on a complete density flipbook - we need to access
individual flipbook frames that play at the given me, consider the actual light direc on and
Axiom: we need to sample baked fluid data (a flipbook texture) inside Niagara to make
calculate a temporary frame, containing the shading info. --- In theory, raw density and
baked values available as float / vector / color values and drive arbitrary par cle parameters
velocity data could be accessed by the internal, niagara flipbook player - but it is hard to
with these.
keep an external and an internal player in sync - so, we are doing a two step samping on
raw density and velocity as well.
We could do this in one step - OR - two:
In the Niagara Module Stack hierarchy, FluidNinja Mul Texture Reader samples the three
(A) Acces baked density and velocity data directly, using Ninja FlipbookPlayer Module
textures simultaneously (velocity, density, shading) - using (self)generated or externally
(introduced in NinjaTools v 1.4). --- or --- (B) Accessing flipbook data it in two steps, using
provided UV coordinates.
Material based Flipbook players to convert Atlas maps to individual frames ---> wri ng to a
The Reader exposes the sampled data as float, vector or color values for other
RenderTarget on every ck ---> re-sample the RenderTarget in Niagara using the built in
(downstream) modules. Eg, the accelera on module could access velocity vectors and
Texture Sample module (this method has been used in NinjaTools v 1.3).
influence par cle movement. Or a Color module could access float density data to make
The first method is op mal ---> these systems perform be er compared to the 2nd.
sparse areas more transparent.
Texture sampling UV from Spawning loca on
Various Setups

Generated and Sta cMesh based UVs ---- see this tutorial video: LINK The following Module / Emi er / Blueprint combina ons are needed:

UV coordinates provide a way to access / sample texture values with posi onal data,
described with a pair of values (U,V) in the 0-1 range. Top le corner is 0,0, bo om right is Setup A
1,1 - and a field of frac onal numbers between. Imagine we are genera ng par cles in a
local coordinate system using a 0,0 - 1,1 bounding box. In this setup, par cle posi on could Key Module: NM_FluidNinja_Mul TextureModule OR
be used as a UV coordinate to access texture values. Each par cle is assigned with a value NM_FluidNinja_FlipbookPlayer
corresponding to its coordinates. Now, we could scale, rotate or move our par cle system (generates UV, samples textures, exposes data for other modules)
(transform it to world space) - by applying an inverse transform, we could s ll access the
texture accurately. Emi er: NE_FluidNinja_FlipbookPlayerEmi er
Both Ninja FlipbookPlayer and Ninja Mul Texture Reader are calcula ng UV coordinates (+ all systems containing/referencing this emi er)
based on the extension and transform of the par cle system.
The above modules could use externally provided UV coords too: combined with Sample Blueprint: BP_FluidNinja_NiagaraSystemContainer_Type1
Sta c Mesh Module, we could access the UVs of Sta cMeshes and spawn par cles on the Op onal - in case we need a raymarching pass
Mesh surface.
The above described methods sampling textures in a point-like / eyedropper manner (like
each par cle is sampling a "single pixel"). With Skeletal Meshes we are using a different Setup B
approach.
Key Modules: Sample Sta c Mesh
(samples mesh triangles for posi on, velocity, normals and UV)
2 Emi er setups NM_FluidNinja_Mul TextureModule OR
NM_FluidNinja_FlipbookPlayer
Looking at (1) par cle spawning loca ons and (2) UV sources, we could define 2 setups: (uses external UV provided by upstream modules,
samples textures, exposes data for other modules)
A. GPU Par cles spawned in a primi ve volume (grid, box, spehere...etc) / Textures are
sampled using generated UV space (derived from the bounding box of the par cle Emi er: NE_FluidNinja_Sta cMeshWithFlipbookEmi er
spawning primi ve) (+ all systems containing/referencing this emi er)

B. GPU Par cles spawned on Sta c Mesh surface, Mesh UV is used to sample Textures Mesh: The sampled Sta cMesh must have "Allow CPU access" flag set ON
(see: Sta cMesh Viewer / Details / General Se ngs / Allow CPU Access)
Notes on Local / Global space usage Input data: shading / Type: float

Type A and B emi ers are by default Local Space emi ers. To turn them to Global Space, go Op onally, we could use a Raymarching shader to calculate dynamic self-shadowing per
to Emi er Proper es and set Local Space flag to OFF. frame (based on density and system/light transforms), and bake this real- me to a third
texture, sample it with Niagara: our cloud of par cles starts to respond to global or local
Type A emi ers require one more change: go to FluidNinja Mul Texture Reader module / lights, casts long shadows at sunset, changes in an instant when a point light moves nearby.
Texture Param Group / Texture Offset: we need to add "Engine Owner Posi on" to our We could colorize shaded and highlighted areas differently: bluish tone in the shadows,
custom offset vector. warm tones on the highlights: we could imitate the effects of direct/indirect ligh ng - a key
component to achieve realism.

Fluidsim data usage, examples Decoupling velo / density

We assume that velocity and density are coming from the same core simula on / being
used together. This is not necessary.
Input data: velocity
Type: mo on vector, driven parameters: ● There are cases when one data type is enough to produce sa sfactory results (most
● Accelera on: push GPU par cles to field determined direc on. The force is addi ve: stylized VFX falls into this category, see use-cases level for examples)
par cles could be stopped by collision or slowed down by fric on (although being ● We could decouple velo & density - and combine regular textures with fluidsim. Think
driven by baked data) of a circle of runes as density, and a turbulent fluid as velocity. Velocity could be used
● Speed (scalar, derived from velocity) could influence color: moving par cles change to wash away / displace the density input.
brightness or hue
● Velocity: overwrite intrinsic par cle velocity and mo on trajectories become Sta cMesh surface spawning
completely predetermined (system is not responding to collision, fric on and other
forces) By default, we are spawning par cles via geometric primi ves. By construc ng
dedicated meshes we could support / enhance fluid par cles: think curved / organic
Input data: density surfaces for a spell VFX, or a simple arc for a waterfall.
Type: float, driven parameters:
● Color, Opacity: colorize dense/sparse areas differently, make sparse areas transparent
● Drag: slow down par cles in high density areas to form conglomerates Please have a look at the Niagara Systems on the use-case levels!
● Posi on: separate dense / sparse areas (use FluidNinja Post-solver Posi on Offset
Module)
● Scale: stretch sprites or meshes according to density
Input variables, User Parameters

Niagara Systems embed / control / composite par cle Emi er(s). An Emi er comprises Hierarchical systems are good at "crea ng diversity, that could be managed". Think of the
stacked modules that spawn, modify and render par cles. Module behaviour usually usual prac ce of having a single parametric base material and a sea of instances with
depends on input values. Highligh ng three ways of providing module input: various param setups - and the way how we set parameters dynamically to these instances
via blueprints. The same could be applied to Niagara: having a single base emi er with
1. Type in a constant at UI input field / browse for an asset carefully planned parametric inputs, and embedding this base emi er in a thousand
2. Link other module's output NiagaraSystem, so we could have unique param setups and we can selec vely enable /
3. Link a variable disable exis ng modules (or add new ones).

Variables (= parameters) created in the User namespace are exposed for external agents Our hierarchy: we could place our autonomous Niagara Systems directly on level - and
(eg. a Blueprint, or the Component Details panel in the Level Editor). The Niagara System provide it with params (flipbook assets, frame numbers, play speed) using the Actor Details
Se ngs panel / User Parameters is the place to create them, using the (+) sign. A default panel in the Level Editor --- OR we could place a NiagaraSystem Container Blueprint on
value could be provided, that is used at ini alisa on / used un l a custom value is set level. The blueprint is embedding a Niagara System as a component. Important: in this case
externally. we are using the Actor Details again, but instead of providing flipbooks, we are assigning
flipbook player materials to the blueprint.
Note, that User Parameters provide a way to feed niagara modules with externally
generated data. On our example levels we are using this channel to (A) assign Niagara Ninja Data flow: User sets a value on the blueprint actor details panel, on level. Using this
FlipbookPlayer module with flipbook assets - OR - (B) forward ninja flipbook player material template, the blueprint sets the Niagara User Param at beginplay. The NiagaraSystem is
(NinjaPlay) output to the Ninja Mul Texture Reader module (inside Niagara) via the forwarding the User Param value to the modules that would like to read this value.
NiagaraSystem Container Blueprint.
Extra twist: for the purposes of demonstra on, we want to (1) preview our NiagaraSystems
in Editor and (2) make them visually consistent (look the same) in Niagara Editor / Level
Embedded structures / chain of dependent variables Editor / In Game (run me / during play). Since our Density / Velocity / Shading pipelines
come to life on BeginPlay, we are (A) using single frame placeholder images as User Param
The most simple case that we could imagine is having a NiagaraSystem placed directly on default values and (B) we are ini alizing our systems in the Construc on Script. The
level (not embedded in a blueprint) or spawned at run me, and the texture sampling placeholders values are replaced with dynamically generated content at BeginPlay. For this
module in the system is set directly (manually) with a constant (a texture asset). No reason, we are running a Reini alize command (blueprint node) on BeginPlay.
dynamic input, no variables, no embedding, it just works - a good setup for prototyping /
sketching.
Se ng up autonomous systems: 6. Shading is generated at run me - by default a raymarching shader material is set, no
need to change this

7. Normally, RenderTargets for Niagara are dynamically generated and internally

1. Bake fluidsim with Ninja Core forwarded to the blueprint embedded Nigara System - this part became dysfunc onal
2. Make sure you export Texture assets (density and velocity flipbooks) in UE 4.26.0. Un l the bug is being fixed by EPIC, we have switched the systems to
3. Drag a Niagara System on level / or duplicate an exis ng one “Manually defined RenderTargets” mode:
4. Set ini al variables at Actor Details panel
a. Density and/or velocity flipbook Create 3 RenderTargets in the Content Browser for density/velo/shading
b. Flipbook frame numbers (horizontal & ver cal subframes) a. Set the RenderTargets as wri ng target to the Blueprint, on the Actor Details
c. Play speed panel, in the “RenderTargets” parameter group
d. Op onally: colors b. Set the RenderTargets as input to the Niagara System, at the Component
Details panel, in the “Override Parameters” group.
Done!
Accessing Component Details panel: click the Niagara System Container Actor
on level. Go to the Actor details panel. On the top of the panel, in the
Se ng up blueprint dependent systems: “Components List” select NiagaraSystemComponent. No ce how the Details
Panel has changed - now, it is revealing Component Details. Find the “Override
Parameters” group.
1. Bake fluidsim with Ninja Core Done!
2. Make sure you export both (A) Texture assets and (B) Basic Player Material at baking
In case if you'd like to (1) init or spawn your systems only at run me + (2) you do not need a
3. Drag the container blueprint on level / or duplicate an exis ng one visually matching preview in Niagara Editor + (3) you do not need preview in LevelEditor, the
4. set the most important ini al variables following simplifica ons could be made:
a. Pick a NiagaraSystem as template (Details /Niagara Params) A. Disable Construc on Script nodes (in the base blueprint)
b. Set the baked Player Material as Density Input (Details /Niagara Params) B. Disable Reini alize node in the Event Graph (base blueprint)
c. Set a “Light Direc on Provider” actor (Details /Blueprint Params) C. Set the User Param default values to something generic*
*not related to a specific baked fluidsim, but serves the purposes of previewing - eg.
5. In case if you need velocity input for your Niagara System: use the Ninja logo templates, located at: /FluidNinja/Core/Niagara/DefaultAssets/
a. Clone the Density Player material instance
b. Replace density flipbook with velocity flipbook User Param default values should be (re)set at two places, separately:
(that is auto exported at baking, together with density) 1. go to Niagara Editor / System / User Params
c. Set the new (cloned) Velocity Player Material as Velocity Input 2. go to Level Editor, select Blueprint, select NiagaraSystemComponent on the details
(again, at actor's Details Panel) panel, scroll down to Override Parameters
NinjaTools 1.4 vs 1.3

As a result of the 4.26.0 engine bug, the original “Ninja -to- Niagara” data pipeline
Ninja 1.4 update emerged as a solu on / workaround to an Unreal Engine 4.26.0. Bug,
(developed under UE 4.25) is dysfunc onal under UE 4.26.0.
that blocked the Ninja-to-Niagara data flow. You could read more about the bug here:
In case you try to migrate Ninja 1.3 Niagara Systems to UE 4.26.0 on your own:
Report, descrip on and repro: LINK /// Official EPIC bug cket: LINK
they will not work - un l EPIC fixes the bug / or you implement the needed changes.
In the effort of fixing things, NinjaTools v1.4 has significantly improved the Ninja-to-Niagara
Update: on 13 January 2021 EPIC has fixed the bug - the fix will be included in UE 4.26.1
data pipeline ( compared to v1.3 ) --- by introducing fully autonomous Niagara Systems that
do not rely on blueprints at all.
NinjaTools v 1.4 provides two solu ons to this problem:
Tools 1.4 also keeps a modified version of the original “blueprint dependent” systems.

A. v1.3 Niagara Systems could be fixed with a minor modifica on, by replacing Dynamic
Niagara Systems on the NinjaTools 1.4 demo levels could be grouped this way:
RenderTargets with premade (“sta c”) ones --- “Blueprint dependent” Niagara
Systems placed on NinjaTools 1.4 demo levels are implemen ng this mod, and
A. In case the system is not using raymarching (no self-shadows on the par cle cloud),
running fine under UE 4.26.0.
it is implemented using the new, “blueprint independent” approach.
B. v1.3 Niagara systems could be simply replaced by autonomous, “blueprint
Most systems belong to this category.
independent” systems
B. In case the system is u lising raymarching, the modified version of the original (v 1.3),
“blueprint dependent” Niagara Systems is used.
In general, the new systems are much easier to use / set up: simply provide the flipbooks /
frame numbers and play speed at the Component Details Panel in Level Editor --- done!
The legacy tutorials and videos describing the general structure and workings of Ninja 1.3
systems are s ll valid and could be applied to the “blueprint dependent” systems in v 1.4.

For standalone Niagara Flipbook player, see: NinjaPLAY

Here is a link to the original Niagara Manual PDF, released with Ninja 1.3: LINK

This 39 Megabytes ZIP contains the original NinjaTools v1.3 Niagara Content
(before the 1.4 update) - in case you need it: LINK