Overview

A “template” refers to a node containing a nodegraph. Other software with similar capabilities often calls them “sub-graphs”, “groups”, “functions”, or “modules”.

They allow to encapsulate complex graphs and behaviors, and expose them to the user as a single, simpler node.
They are the central building block of PopcornFX v2 effects. The overwhelming majority of effects you will see and make will use templates.

Unlike the “functions” concept, they do not need to have inputs and outputs and behave as a literal functions which takes inputs, does some processing, and outputs a result. They can contain and do pretty much whatever you want, from simple math nodes or scripts, up to an entire hierarchy of particle layers with complex events interactions, or even an entire effect.

Unlike the “modules” concept in UE4’s niagara or Unity’s VFX graph, they are not limited to a single simulation state. Templates can contain computations done both at spawn, evolve, and even render. This allows true abstraction of complex behaviors, without leaking unnecessary implementation details to the potentially less technical end-user. It makes them quicker and less error-prone to use.

Templates can either be defined locally inside an effect, or made public and shared across different effects. We encourage you to place your commonly used templates into “template-only” effect files to make sharing easier.

Core template library

PopcornFX v2 ships with a set of base templates, called the core template library. These include low-level helper nodes such as “scene.axisUp” or “remap”, up to commonly used simulation nodes, such as physics or collision nodes, trails, event placement helpers, and more….

Its main goal is to factorize commonly used functionality into nodes which are easy to use, to gain time when creating effects.

We regularly augment the core template library with new helpers as the tool evolves and we gain more insight on what users need and end up doing often.

Please see the core template library page for more details.

The core template library files are to be seen as “reserved”. Editor updates can and will upgrade those files, and will stomp any custom-made modifications.

If you want to modify a template in a core-library file, you should copy/paste it into one of your own files and use that version instead.

Using templates

Templates can be added to a graph like any other node, see the nodegraph UI page.

Templates appear like any other node in the graph, but have a small red marker to show this node is a template and has a sub-graph:

As nodes, templates can expose the following to the “outside world”:

• Properties: Allows the user to feed data into the template from the propertygrid. Properties are constants and cannot vary dynamically, unless that property is also exposed as an input pin.
• Input pins: Allows the user to feed data into the template from a nodegraph wire. All input pins also have an associated property. That property gets grayed-out when something is plugged into the pin, as the wire will override the data defined inline in the property.
• Output pins: Allows the user to retreive information from the node as a nodegraph wire, and use it in the rest of the graph. This is often the result of a computation, or an outgoing event.

You can view the the sub-graph of a template node by double-clicking on that node, hitting the ‘Enter’ key, or right-clicking and selecting ‘Open’ in the contextual menu.

If the template is defined in an external file, its sub-graph will appear read-only, as any change made to the shared graph will affect all other effects using the template.

For example, the “vrand” template defined in “Core.pkfx” in the core template library:

Creating templates

There are two main ways to create a new template:

1- Group existing nodes

• Select the nodes you want to group into a new template
• Hit the Ctrl+G hotkey
• Type the name of your new template in the dialog-box, and validate.

2- Create new graph from scratch

• Go to the effect treeview panel
• In the second section, right-click and select “Create new template”.
• Type the name of your new template in the dialog-box, and validate.

You can then double-click on the template to open its nodegraph and start adding nodes.

Creating pins & properties

All templates inputs (properties, input pins) and outputs (output pins) are specified using a special node inside the template graph: The template export node.

This node specifies if it should export an input or output, the exported name, the type of the value, and a lot of other properties allowing you to fine-tune the appearance and characteristics of what you export.

For instance, you can specify the min/max values of an input. If it’s a property, whether it should appear as a regular numeric value, a slider or a dropdown. Semantics will tell the editor how it should treat that value, color semantics will display a color-picker in the propertygrid when the user of your template selects the node, etc…

There are three ways to create export nodes:

1. You can manually type “input”, “property”, or “output” in the node creation dialog.
2. You can right-click on an existing node and convert it to an export node. This works for constant nodes and samplers/resource nodes. It will take the current value of the node and set it as the default value of the export.
3. Auto-exporting an existing pin or property of a node already present in the graph.

Auto-exporting properties & pins

When creating templates, you can find yourself wanting to forward the property of a node to the parent graph.

The obvious way is to create an export node, wire it into the pin of the node whose value you want to expose, and reproduce the exported settings of the original node.

This can quickly become a tedious process, especially when making layer templates.

Another way is to auto-export the property. Every input pin and property has an auto-export button next to its visibility button:

Clicking this button toggles the export of the property to the parent graph.

Nodes that have some of their properties auto-exported will be displayed with a yellow marker on the top right side:

This is showcased in the effect “Particles/Tutorials/015_Templates.pkfx” of the online package “Tutorials“.

The “Jets” template of the effect “Particles/Fireworks_MTL_Philippines.pkfx” of the online package “Samples” is a good example of the benefit of auto-exporting child layer properties.

The template without auto-export:

The same template with auto-export:

Here, the remaining input nodes are used instead of an auto-export because we wanted to change the property order and category name.

Sharing templates

When selecting a template in the effect treeview, you will be able to change its “Public” property. Public templates are visible to all other effects in a project.

When your project grows, it will become important to have dedicated files where you place your public templates. This will help minimize dependencies between effects. Projects without clean template files will often end up with lots of inter-effect dependencies, where effect A needs effect B, which needs effect C, which also needs effect D, which itself needs effect A, just because they all use templates defined in one of the other.

We advise to create template files in your own folder under the project’s “Library” directory.

Do not create template files in “Library/PopcornFXCore/” !
The contents of this folder are to be seen as “reserved”, editor updates can and will upgrade those files, and will stomp any custom-made modifications.

If you want to modify a template in a core-library file, you should copy/paste it into one of your own files and use that version instead.

This becomes increasingly important when sharing effects and templates between different project, or on a marketplace.

Advanced customization

There are a couple of more advanced functionalities you can use when creating templates, to improve the end-user experience and make mistakes easy to spot.

Pin rules

In more complex templates, some properties or pins might not make sense based on the value of other properties.

Think of a template that handles different behaviors and allows users to switch between them using a dropdown. You might only want to expose some properties when a specific mode is set, and hide them the rest of the time.

You can do this using pin rules.

Pin rules allow you to control the visibility of property or pin based on the value of other properties.

The export node lets you specify up to 2 rules, which test the value of another property. Based on the result of the test, it will change the visibility of the current pin or property.

As an example, here is the rule setup of the ‘SpawnCount’ property of the multiplier node in the core template library:

It will change its visibility based on the value of the ‘SpawnCountMode’ property.

The base visibility is ‘Visible’, and the property will become ‘Disabled’ when ‘SpawnCountMode’ is equal to 1.

You can chain up to 2 different rules, and combine their results based on different boolean operators: ‘Rule1 AND Rule2’, or ‘Rule1 OR Rule2’

Diagnostic nodes

In some cases, the validity of some inputs can depend on the specific values of some other inputs. It can be useful to notify the user of your template that the values he/she entered are not expected or might cause issues.

Diagnostic nodes are perfect for that.
They take a boolean true/false input, and based on that value, will emit a diagnostics message.

This is used in the multiplier node to show a warning when using a “TotalParticleCount” spawn count mode, when the multiplier is set as infinite:

There are 4 diagnostic nodes: info, warning, error, and assert.

Assert and error both emit an error. The only difference is that the “error” node will emit an error when the input condition is ‘true’, and the “assert” node will emit an error when the condition is ‘false’.

An error or assert node that triggers a compile-time error will cause the entire layer compilation to fail. If you want the graph to be compiled and the simulation to still run despite the diagnostic, you should use a warning or info diagnostic instead.

All resulting compile-time diagnostics appear in the effect-analysis report, visible in the content browser’s details view. This makes it easy to spot and fix effects with issues in a project:

The generated documentation of an effect (v2.2.0) also lists all compile-time diagnostics.

Icons & color

You can change the color of your template by selecting it in the effect treeview, and changing its “Class Type” property.

It is also possible to change the icon of your template for one of the builtin icons.
However, you cannot yet browse a list of available icons, and there is no way to specify a custom icon. This will change in a future build.