Combining Collision Effects in Niagara Data Channels

Overview

You can improve performance by using Niagara Data Channels (NDC) to combine multiple individual impact burst-effects into large, shared Niagara Systems. A few large Niagara Systems with many particles are much faster to simulate and render than many small Niagara Systems with few particles.

This tutorial walks you through creating a new project, creating a new data channel, using the spawning wizard, and setting up the Niagara System to listen to the data channel inputs.

This page covers:

• How to aggregate collision effects:

  • How to write impact collision events into a Niagara Data Channel

  • How to set up the NDC to spawn a listener Niagara System

• How that system will read impact events and spawn particles in response, at each impact location

• Some features and system interface notes

Create a New Project

Let’s make a new project using the First Person template.

• Launch Unreal Engine.

• In the Project Browser, choose the First Person template.

• Name the project NDCShooter.

• Adjust the Project Location as needed.

• Click Create.

Create a Niagara Data Channel

Create a new Niagara Data Channel asset called NDC_Impact. The projectile Blueprint will write data into this NDC for every collision. Then, the Niagara System will read these impact events and spawn particles in response.

• In the Content Drawer, right-click to access the right-click menu.

• Scroll to FX > Advanced > Niagara Data Channel.

• A new asset will appear in the active folder. Name the new asset NDC_Impact.

NDC Type

Niagara Data Channels can come in a variety of types. You can make custom types that can manage the data internally however you wish.

In this example, select the Niagara Data Channel Islands type. The Islands NDC type sub-divides the world into discrete Islands. The Islands writing into the NDC and the Islands reading from it will only be visible in the same spatially-local Island. Readers and writers that are far apart in the world will be in separate Islands and will not interact. Keeping Islands discrete is required so that one impact event is spawned in the correct place and only once.

Variables

Next, add some variables to the NDC. These are the variables that you can write to, and read from, in the channel.

1. Double-click the NDC_Impacts asset to open the editing window.

2. In the Channel Variables drop-down, click the + Plus icon.

3. Add a Position Type named Position.

4. Add a Vector Type named Normal (to indicate a direction of the surface that is hit during each impact).

5. Add an EPhysicalSurface Type named Surface that will allow passing in the surface type for the collision.

Other NDC Settings

Other Channel Variable Settings

For this example, leave the other settings in the NDC as the defaults. Other settings in this drop-down are:

• Keep Previous Frame Data: When enabled, the NDC will keep data around for an additional frame. Readers can read the previous frame rather than the current frame, which helps avoid tick-order dependencies. For more information, see Tick Ordering.

  • Leave this selected, as we will be reading the previous frame's data.

• Enforce Tick Group Read Write Order: When true, the Niagara system attempts to place all reads of this NDC after the Tick Group specified in Final Write Tick Group. There will be a warning in the log if a read and write happens out of order. For more information, see Tick Ordering.

  • For this example, leave this deselected.

• Final Write Tick Group: When selected, this feature will attempt to order NDC access so that other Niagara Systems reading the current frame data will tick after those writing to the NDC. Any writes to the NDC after this tick group will trigger a warning.

Islands Settings

Settings specific to the Islands drop-down are as follows:

• Mode: Controls how the Islands are created and sized.

  • Aligned Static: Islands are all aligned to set sizes in the world and are laid out in a regular grid.

  • Dynamic: Islands begin at the location of their first access with an initial size and can grow to include new nearby accesses that fall within range.

• Initial Extents: The initial size of the Islands when using Dynamic Mode.

• Max Extents: The maximum extent of the Islands. When using Aligned Static mode, they are always this size.

• Per Element Extents: An additional padding size added to the Island's bounds. It covers the range of any data being written into the Island.

  • For example, say you are writing impact events into the NDC and at each impact you're spawning FX bursts that can extend 100x100x100 units from the origin. You can pad the Island bounds by 100 so that if an impact falls very near the boundary of the Island, the bounds will cover the generated effects and avoid any rendering or culling artifacts.

• Systems: The Islands NDC type can specify one or more Niagara Systems to spawn along with each Island. In this way you can automatically spawn systems that will listen for, and respond to, data entering the NDC. The location and bounds of these Niagara Systems are automatically set to match their owning Island.

  • In this tutorial, a Niagara System will be spawned that will listen for and create impact effects for each impact event written into the NDC.

• Island Pool Size: The number of Islands to pre-allocate. This can help reduce initial activation cost, but it does have a memory cost. This setting is specifically to trade some memory cost for runtime activation performance.

Debug Rendering Settings

• Enabled: A master switch to toggle on/off all debug rendering for the NDC.

• Show Island Bounds: Renders a red cube outline to show the bounding box for each Island.

Create a Niagara System

To generate effects when an impact happens, you need to create a Niagara System that will listen for impact events in the NDC and spawn particles in response.

1. In the Content Drawer, right-click in the drawer to launch the right-click menu.

2. Select Niagara System.

   

3. A Niagara System asset will be created in the active folder. Name the new asset NS_NDC_Impacts.

   

4. In the template window, select the DirectionalBurst template. It will be modified for use as an NDC Islands listener system.

5. Click Create.

   

A NewNiagraSystem dashboard editing window will launch.

System/Emitter Lifetime

This Niagara System will be spawned when impact events happen and a new Island is spawned.

The Niagara System needs to loop and listen for new impacts being written into the NDC, rather than completing automatically after a set time. It does run and listen indefinitely, but it will also clean itself up after a short time of being unused via the Complete If Unused module.

In the Details tab, in the Emitter State drop-down, set the Life Cycle Mode to System.

To reduce performance costs to a minimum, the system needs to clean itself up when there are no more impact events happening. To do this, add a Complete if Unused module to the System stack. This will have the system enter a complete state and stop ticking.

When an Island has no active readers, it will clean itself up to automatically remove any ongoing overhead. If new impact events happen again in the same location, the NDC will spawn both a new Island and Niagara System.

Spawning

You can use a special module creation wizard to do most of the work handling particles spawned from the NDC. The wizard will auto-generate a number of Scratch Modules for any custom particle behaviors. You can do this work manually, but the wizard makes typical workflows much simpler and quicker.

In the wizard, you can select which Data Channel to use and configure how it will be used to spawn particles.

To open the wizard:

1. Double-click the Niagara System asset to open the editing dashboard.

2. In the DirectionalBurst emitter stack, right-click on Spawn Burst Instantaneous.

3. In the menu that opens, under Module Actions, select Insert Below.

4. In the Add new Module search box, type to search for Spawn From Data Channel.

5. Click to select the module, and an Add new module modal will open.

For the next steps, go to the next section Spawning Wizard Page One.

Spawning Wizard Page One

Page one of the wizard sets up the main elements of how to read NDC data in this emitter and how to spawn particles. Each option is detailed below:

1. For Data Channel, select NDC Imports.

2. For Spawn Mode, select Conditional Spawn.

3. Review the other settings (detailed in the bullets below) and click Next.

Page One Settings

• Data Channel: The Data Channel to use. Select the NDC we created earlier, NDC_Impacts.

• Spawn Mode: Here you can select which spawning function to use. Each of these will iterate over the entries in the NDC and spawn particles for each one.

• Conditional Spawning: Spawns a set number of particles defined by the module inputs for each item in the NDC data. Optionally allows for conditions to be placed on the spawning.

• Direct: Allows you to spawn a set number that is read from the NDC data itself. For example, you could have an integer Count variable inside the NDC and use that to define how many particles to spawn for each NDC item.

• Read Current Frame: If true, the current frame contents of the NDC is read by the module(s) this wizard is currently setting up. This defaults to off, which reads the previous frame data.

• Update Source Data Every Tick: If true, the data interface this wizard generates will update which NDC data it's accessing each frame. Depending on the NDC type this could be an expensive search. In this case, the Islands type is being used so the search would be iterating over all of the Islands until we found the correct Island to use for this Niagara System Component.

  • In the case of NDC Impact FX, the reading Niagara System is spawned by the NDC and fixed in place so you can uncheck this as you will always be accessing the same Island.

  • If you have a moving component that can move from Island to Island, then you might need it to be selected.

• Auto Transform Position Data: When enabled, this setting will add nodes inside these Niagara modules that will transform incoming position types. Positions coming into this Niagara System from the NDC will be automatically transformed to the simulation space of this Niagara System. This avoids possible issues with local space emitters.

Spawning Wizard Page Two

Page two of the spawning wizard is for setting up conditional rules for spawning. This enables precision actions, for example spawning particles only on specific surfaces, or only if a particular bool is set inside the NDC data.

1. For now, leave the default settings on this page, and use no conditions for spawning. This means that every entry in the NDC will spawn particles based on the default module inputs.

2. Click Next.

Spawning Wizard Page Three

On page 3, you can choose which variables from the NDC you would like to read inside the particle spawn, and where to store this data.

1. Leave the default settings, reading all NDC data into the StackContext.Module Target Namespace.

   1. In some cases you may want to read directly into the Particles namespace and so a variable Position from the NDC would be written to Particles.Position directly.

2. Click Create Module.

Spawning Wizard Results

Now the wizard has generated three modules:

• Init Data Channel: Creates the Niagara Data Channel Read Data Interface (NDC Read DI) that is used to read the NDC. It is placed in Emitter.SpawnDataChannel for later use in the emitter.

• Spawn From NDC Impacts: Uses the NDC Read DI to call spawning functions, in this case Spawn Conditional, to spawn particles into the emitter for every item in the NDC. For more on inputs to the modules and the Spawn Conditional function, See Spawning Functions.

• Init Particles From NDC: Reads the data from the correct NDC that spawned each particle and stores the data in StackContext.Module.Variable.

Notable parts of these modules are:

• GetNDCSpawnData: GetNDC Spawn Data is a utility function that allows us to access the NDC item that triggered the spawning for the current particle. It converts from an Execution Index for the current emitter spawn into per NDC spawned data.

• NDC Index: The index of the NDC item that spawned this particle. Primarily used to read the NDC data to initialize index values like position from the source NDC entry.

• NDC Spawn Index: The index of this spawned particle within the source NDC entry. Similar to the Execution Index but instead of being 0, the number of spawned particles is -1 for all spawned particles.

• NDC Spawn Count: The number of particles being spawned for the same NDC Index. Similar to Engine.ExecutionCount but instead of being the total number of spawned particles for the emitter, it is the number of spawned particles from the same NDC Index.

• Read: The Read function allows us to access data from a specific element in the NDC data. In this case, the index we want to read is the NDC element that spawned this particle. We can get the NDC element from GetNDCSpawnData. This function does not have to read all the data from a particular NDC. However, if it does try to read a variable that is not in the NDC, bSuccess will return false.

• Transform Position: If Auto Transform Position Data is set to true in the wizard,  an automatic transform of any position data gets added to this module.

Using the data

Now that particles have spawned, and our wizard-generated modules have read the NDC data into intermediate StackContext variables, we can use this data to initialize our particles.

We want to place our particles at the impact Position we've read from the NDC.

1. Move the Init Particle From NDC up to the top of the stack above Initialize Particle so that the data can be available.

2. In Initialize Particle, set the Position Mode to Direct Set and then select the Position that is read from the NDC.

We want the directional element of our impact to match the orientation of the impacted surface. To do this we'll change the velocity of the particles to move away from the impact point in the direction of the surface Normal value we passed in via the NDC.

1. In the Details tab, in the Add Velocity module, modify the directional velocity element (In Cone) to the effects inside the module.

2. Change the Cone Axis vector to the Impact: Normal vector we pass into the NDC.

Writing the Impact Events

The final part of the basic setup is to write the impact events to the NDC.This is done from the projectile Blueprint inside the Event Hit.

Open up /Game/FirstPerson/Blueprints/BP_FirstPersonProjectile. We need a relatively small amount of Blueprint code to feed the impact data into the NDC.

Write To Niagara Data Channel

In the Blueprint function Write To Niagara Data Channel we can write a single value into a specified Niagara Data Channel.

The following is a description of each of the Write To Niagara Data Channel node options:

• Channel: When you select the NDC asset, the node will auto-populate with the variables of the NDC.

• Search Parameters: Use these parameters to allow the NDC to choose which of its internal data to access, depending on the type of Data Channel being used. A Global NDC type has only one global set of data internally, so these search parameters are not needed. The Islands NDC type will use the parameters to choose which of the Islands to use and which data to access.

  • It is common practice to use a component reference for the NDC to read data from. An Island type NDC will only read the location, other Island types may read more complex data.

  • You can also directly provide (or override) the Location if you have no component or if the use case requires it. In this case, we want our NDC Islands and handler Niagara Systems to very specifically include the location of the impact effect. So we'll use the impact location and not provide a component.

    If you set this input as the default for the Island's type, the Level will try to use an Island at the origin of the world.

• Visible to Blueprint: only use this if you need to read this data from other Blueprints. Most often this visibility flag is useful when writing to an NDC from inside Niagara itself to export data back to a Blueprint.

• Visible to Niagara CPU: required when reading data inside a Niagara System on the CPU. This includes Niagara CPU emitters, and also CPU and GPU Emitter system and Emitter Stacks.

  • For example, to use these in combination with the Spawning functions on a CPU or GPU emitter, you must make the data visible to the CPU with this flag. If you spawn data in this way into a GPU emitter, you do not need the Visible to Niagara GPU flag (see below) because that data will be made visible automatically.

• Visible To Niagara GPU: required if reading data from a Niagara GPU emitter. This node can be left as false if you are using Spawn Conditional or Spawn Direct to spawn into a GPU emitter.

  • There are cases where we need to read NDC data on a GPU emitter but have not spawned particles into this emitter from the NDC. In this case, you must explicitly make the data visible to the GPU.

• Position and Normal Nodes: the pins on the node contain the actual data we'll pass to the NDC. The Hit Location and Hit Normal values feed in from the Event Hit module.

• Surface value: feeds into the NDC. For now leave this set as Default. See Advanced — Surface Filtering (below) for more information.

Results

Check out the video! Here is what is happening:

1. When  the projectiles generate hit events, the events write to the NDC.

2. When this data is consumed by the NDC it generates an Island at the correct location and spawns the linked Niagara System, NS_NDC_Impacts.

3. NS_NDC_Impacts will then spawn and initialize particles at each impact location by reading the data from the NDC.

Advanced — Surface Filtering

You can add extra conditions onto the SpawnConditional node to trigger spawning only when the NDC data meets those conditions. One example usage is to only spawn on impacting certain physical surfaces. Let's modify our example to define different surfaces in the scene and spawn differently for each.

Surface Setup

First we’ll need to set up our project with different surface types we want to impact.

1. Go to Edit > Project Settings, and use search to bring up Physical Surface settings.

2. Add some surface types such as Grass, Stone, Wood, and Metal.

Create a Physical Material asset for each of these surfaces. 

1. In the Content Drawer folder tree, go to Level Prototyping > Materials.

2. Right-click or select +Add in the Content Drawer.

3. In the menu scroll to Physics > Physical Material.

4. Click PhysicalMaterial class to select it.

   

5. Click Select.

   

When you see the new asset populate in the Content Drawer, double-click to open the Details menu.

Set the Surface Type for each. If you’d like, you can alter other material properties such as making stone and metal more dense.

Create a corresponding Material Instance for each Physical Material.

1. In the Content Drawer page tree, if you don’t already have a Surfaces folder under Materials, right-click in the page tree to add a New Folder and name it Surfaces.

2. Right-click or select +Add, scroll to and select Material > Material Instance.

3. Double-click the new asset to open the settings menu in the Details tab.

4. Adjust your settings as needed, then click Save.

The materials are applied to the simple map, and now there are some surfaces that the effects can respond to differently, as shown in the image below:

Modifying the Niagara System

Next, you need to make a few modifications to the Niagara System to have different reactions to the different surfaces.

Shared Data Interface

When you work with multiple emitters and read the same NDC, it can often be easier (and more efficient) to use a single NDC Read Data Interface (NDC Read DI). Let’s define a new NDC Read DI at the System level and reference this in all of our emitters.

Metal Sparks Example

Let’s create a new emitter that generates GPU sparks, but one that only spawns on collisions with Metal.

For simplicity, duplicate the existing emitter and flip it over to GPU simulation. Use the module wizard again to initialize our emitter to spawn from the NDC data correctly.

Delete the Init From Data Channel, Spawn From NDC Impacts, and Init Particle From NDC modules for this emitter, because this new emitter works slightly differently.

For the steps for opening the wizard, see Spawning.

1. In the new emitter right-click menu, select Spawn From Data Channel as the source for the new module. In this example, it is NDC_Imports.

2. On the first page of the wizard, leave Conditional Spawn selected.

3. Click Next.

   

4. On the second page, select the Surface variable to apply a condition, then click Next.

   

5. On the third page, write all the NDC variables to StackContext.Module Target Namespace, then click Create Module.

   

   1. This gives a new set of modules similar to the first emitter. These are Init Data Channel 01, Spawn From NDC Impacts 01, and Init Particle from NDC 01. The 01 signifies that these are entirely separate scratch modules from those in the first emitter.

      

6. From the Init From Data Channel 01 module, open the Details tab and read from your new System level DI.

   

7. Now you can see the Spawn From NDC Impacts 01 module in the Details tab. Modify the Comparison Operator inputs to Equals, and the Surface Condition to Metal. These fields control which surfaces the impacts are spawned on. In this case, set Equals and Metal, because we only want to spawn if the hit surface equals Metal.

   

8. The final part of the setup is to modify the projectile Blueprint to pass along the surface information to the NDC correctly. We must take the hit result from the collision event and extract the Surface Type enum, which we pass into the NDC.

   

9. In the projectile’s Collision Component settings, set Return Material on Move: to true (checkbox is selected).

   

10. Set a value on the projectile’s Collision Component so that this hit result properly returns the Phys Mat.

Results

Check out the video! The new sparks are smaller and yellow with higher spawn counts per impact. You can see that a new yellow-sparks emitter triggers when the projectiles hit a metal surface.

But not when the projectiles hit other surfaces like Stone.

For additional information on these more advanced spawning modules, see Spawning Functions.

Features and System Interface Notes

Custom Data Channel Types

Projects can implement their own custom NDC types that can partition incoming data however they wish, and provide other useful features. Examples of potential new NDC types could be:

• An NDC type that sub-divides the world using an octree rather than Islands

• An NDC type that stores data per player rather than spatially

Use the Islands NDC type as a template when creating a custom NDC type.

Tick Ordering

Every actor and component in the game will execute an event tick at various points. For those writing to, or reading from NDCs when this happens in relation to others, it can impact what data they can see.

An example: 

• Component A writes to an NDC and Component B reads from it.

• If Component B ticks before Component A, then the data that Component A writes into the NDC will not be visible to Component B.

To solve this problem we have two solutions: 

• Reading the previous frame’s data

• Tick dependency

Solution 1: Read the Previous Frame's Data

The simplest, and often best, way to get around this problem is to read the previous frame’s data. This way you are guaranteed to get the whole frame’s worth of data, regardless of when the source of the data was ticked.

The downside is increased memory usage, because you must keep NDC data around for another frame. It also introduces a frame of latency between the write and read. In most cases, this is irrelevant or not noticeable, but in specific cases it could be significant and undesirable.

Solution 2: Tick Dependency

Another way to solve the issue is to introduce some way to have Component B (reading the NDC) tick after Component A (writing to the NDC). Options for this are somewhat limited currently. Depending on if the NDC writes are happening on the CPU or GPU there are different options for this.

NDC data on the CPU is processed at the beginning of each new Tick Group. In some cases we can move our NDC access to earlier/later tick groups so that the reads happen after the writes. Blueprint actors can define the tick group in which they tick inside of the Actor Tick category of their class defaults. For more information on Tick Groups, see Actor Ticking in Unreal Engine.

Niagara Components can modify their Tick Behavior property to one of the following:

• Use Prereqs: The Niagara System will tick after all of its component’s prerequisites and data interface prerequisites.

• Use Component Tick Group: Ignores the component prerequisites and ticks the Niagara in the component’s specified Tick Group.

• ForceTickFirst/Last: Forces the system to tick in the first or last tick groups.

Altering the tick order with these settings can allow us to read NDC data on the same frame that it is generated. When using the Use Prereqs tick behavior (which is the default) we can also use a feature inside Niagara Data Channels to help order NDC access more specifically.

In the NDC asset we can set Enforce Tick Group Read Write Order and set a Final Write Tick Group for the Data Channel. These settings define a tick group that is the last time the NDC can be written to. Niagara Components using Use Prereqs will order the execution of systems that read this NDC to a Tick Group after the Final Write Tick Group if possible. If anyone writes to this NDC after this Tick Group, a warning will be posted to the log.

For GPU emitters, we cannot use these Tick-Group-based ordering features and the options are more limited. GPU emitters that read the current frame data from an NDC are automatically executed as late as possible in the GPU frame, similarly to how systems move that read the GBuffer to execute late in the frame. In many cases, this can be enough to allow same-frame reads, but it is not 100% robust.

Local Space Emitters

When you use NDCs to spawn particles into other Niagara Systems, local space emitters might prove a slight area of confusion. In some cases, emitters are authored by Effects Artists that assume the System will be attached or placed and oriented in a way that allows local space emitters to be used.

Positions can be in local space and particular directions, like positive Z, can be assumed to be Up for the emitter for adding velocity, and so on. These assumptions do not work for effects spawned from NDC for two reasons:

• Typically the data coming into the System from NDC will be in world space.

• The Niagara System that is spawning the particles is a shared system with its own transform. Its local space is not and cannot be specific for each NDC entry for spawned bursts.

The particles spawned in response to the NDC must take all their position and orientation from the NDC data itself. First, ensure positions are correct. You can either ensure you're using a non-local space emitter or you can transform incoming positions to the correct simulation space.

The spawn wizard option Auto Transform Position Data can do this transformation automatically.

Next, if you're adding velocity or have some other directional element to the effects, you must read this direction from the NDC if you want it to be unique per burst. In some cases just assuming Z is Up for all bursts might be fine.

In some specialized cases there might be NDC systems actually attached to particular components and they will feed in correct local space positions. It is actually desirable to have local space emitters and so it's impossible to create rigid rules that would limit the use of local space entirely. An example of this would be spawning impact effects while on a fast moving object in the world (such as a vehicle).

Spawning Functions

The Data Channel Reader Data Interface offers a number of functions that allow spawning particles into a target emitter for each item in the Data Channel. These iterate over each item in the NDC data and allow us to spawn particles into the target emitter based on a number of other inputs for each call. For each NDC entry and for each emitter, we track a spawn count and a scale that is manipulated by calls to these functions.

• Spawn Conditional allows you to specify a number to spawn, and places conditions on the spawn based on data inside the NDC. This allows you to do things like only spawning for certain impacted surfaces or not spawning a particularly expensive emitter, for example if we pass a Simple flag into the NDC data.

• Spawn Direct allows us to have the NDC data itself specify the spawn count to use.

• Scale Spawn Count allows us to add a scaling value to each spawn based on data in the NDC.

Each of these functions offer a mode input that allows you to either accumulate with earlier set counts and scales, or to override them. By default we use Accumulate. An example of using override would be if using SpawnConditional to set the spawn count to zero for a particular surface type.

In this case, if an emitter wanted to spawn particles for every surface but metal. A final call to SpawnConditional with a condition of Surface == Metal could override the count to 0.

Spawn Conditional Node Options

Spawn Conditional will spawn a set amount of particles for each entry in the NDC. It can optionally compare data in the NDC against data you pass into the function call and skip spawning if the condition fails.

Spawn Direct Node Options

Spawn Direct will spawn particles into an emitter for each entry in the NDC. The Spawn Direct function takes the spawn count from a value inside the NDC data. The variable to use from the NDC can be selected at the top of the function call node. Or, it can be set up from the Spawn from Data Channel wizard.

Scale Spawn Count Node Options

Scale Spawn Count will apply a scale to the spawn count for each NDC and each emitter based on a value from the NDC data. Select the NDC variable you want to scale by at the top of the function call node. You can also set this from the Spawn From Data Channel wizard.