Unreal Cascade User Guide

Document Summary: Guide to using the Unreal Cascade particle-based effects system.

Document Changelog: Created by Alan Willard; wikied by Joe Graf. Maintained by Richard Nalezynski.

Introduction

Cascade is a tool for creating particle-based effects using emitters in the Unreal Engine.

Using Cascade

Opening Cascade

Cascade Overview

Cascade Layout

Cascade is arranged with four windows:

Menu Bar

Edit

Regenerate lowest LOD

Save Package

View

View Origin Axes

View Particle Counts

View Particle Times

View Particle Distance

View Geometry

View Geometry Properties

Save Cam Position

Window

Properties: Shows Properties Pane.

Unreal Curve Editor: Shows Curve Editor.

Preview: *Shows Preview Pane.

Tool Bar

There is also a toolbar, as shown below:

The toolbar contains the following controls (from left to right on the toolbar):

Emitter List

The Emitter representation in the EmitterEd viewport, there is a single column of modules contained in the EmitterEd window (#2). This represents a single particle emitter contained in the system. Each column is made up of an emitter block, followed by any number of module blocks.

The emitter block is shown below:

The following buttons are displayed on the emitter block (left to right):

/ This button will enable/disable emitter. The first image is displayed when the emitter is enabled, the second when disabled. It is important to note that when disabled, the emitter will not have Tick or Render called on it.

The middle button is the rendering mode for the emitter. Clicking it will switch to the next rendering mode available. The following icons are supported:

	The emitter should render normally.
	The emitter should render wire-crosses at the positions of the particles.
	The emitter should render points at the positions of the particles.
	The emitter should not rendered at all.

The final button on the emitter block is the following:

This button will send the relevant emitter properties to the curve editor window (#4).

Each module in an emitter appears in a column under the emitter block. The following image is of a module in Cascade:

The upper right icon is the button for sending the relevant module data to the curve editor. The lower right icon is the button to enable/disable the module. (NOTE: Disabled modules that are shared between emitters will be disabled on all emitters!)

The final button is only present on modules that can render a 3D representation of themselves in the preview viewport.

/

The left image indicates that the 3D preview should be drawn. The right indicates it is currently disabled.

Curve Editor

Adding a module to the graph

Adding a module to the Graph Editor is very simple. The green box that appears on the left side of a module will add that module to the graph editor. The color of the module that appears in the Graph Editor is determined randomly when the module is created. To change this, open the Cascade set of properties in the Property window for the module you want to modify, and set the color there.

Manipulating the graph

The yellow box that appears to the right of the entry in the Graph Editor toggles rendering the splines for that module. Right clicking on one of these entries will allow you to remove it from the graph.

Creating points on the graph

Note that you need to make sure the Distribution you are modifying is a 'curve' type (eg DistributionFloatConstantCurve) before you can add multiple points etc.

To create points in the Graph Editor, ctrl-left click on the spline for the value you want. The easiest way to do this is by turning off all the other modules by using the checkbox discussed above. All modules start at 0 with a single key at time 0. Ctrl-Left clicking on the spline anywhere in the timeline will create a point there. This point can be dragged around at will, but as discussed above if the spline represents a vector (XYZ) then it will move all 3 keys for that vector in time but not in value.

Right clicking on a keypoint will bring up a menu and let you manually enter the Time or Value of that keypoint. If its a key in a color curve, it will also let you select its color using the color picker.

If the module is ColorOverLife, then the splines rendered will reflect the current color at that time, while the points will be colored to reflect the particular channel for that spline. One other difference with ColorOverLife is that all values will be limited to 255, so you cannot drag a point above that value line.

See the Curve Editor User Guide page for more details.

Controls

Mouse Controls

Movement controls for Cascade are as such:

In the Preview pane, left mouse button rotates the scene around the particle system center, right mouse button will zoom in and out.

In the Emitter pane, left-clicking on an emitter or module will select that emitter. Left-click dragging on a module will move that module wherever it is dropped, provided there is an emitter under it. This can be used to drag a module up or down in a stack, or to another emitter. Right-click will open up a context-sensitive dialog for creating a new emitter (clicked on empty space), creating a new module (clicked on empty space within an emitter), deleting a module (clicked on a module name), or deleting an entire emitter (clicked on the main emitter module at the top).

Shift-left click and drag will instance a module between emitters, which is expressed as a + next to the module name, and the modules will share the same color.

Ctrl-left click and drag will copy a module from the source emitter to the target one.

Middle-mouse click and drag will pan around in the Emitter pane.

With an emitter selected in the Emitter pane, using the left/right arrow keys will alter its place in the order of the overall particle system. Emitters are updated and rendered by the particle system in the left-to-right order they appear in Cascade.

In the Properties pane, left-click selects fields or opens rollouts for properties.

In the Graph view, the controls change depending on what mode you are in. There are two modes for manipulating the Graph view, these are:

Pan Mode: Left-click drag will move the view around, mousewheel zooms in and out uniformly.

Zoom Mode: Left-click drag will scale the graph vertically, right-click drag will scale the graph horizontally.

If a spline already exists in the graph, then left-clicking anywhere on that spline will create a key at that point. Keys can be moved by left-click dragging them, but in a module with multiple values being graphed (such as RGB for Color Over Lifetime) anytime a key is created, a key is added to the other splines of that module. These keys will always be kept at the same time as the others, so if the key for Red is moved forward or backwards in time, the keys for Green and Blue will be moved horizontally as well (but not vertically).

The other two buttons in the Graph view are Fit buttons. The button on the left will zoom and pan the view to the horizontal extents of the currently visible splines, and the button on the right will do the same on the vertical axis.

Keyboard Controls

Hot Keys

Working with Emitters

Creating a Particle System

To create a particle system in Unreal Engine 3, open the Generic browser and either open File>New and choose Particle System from the dropdown at the bottom of the dialog box, or right click on empty space in the Generic browser and choose New Particle System from the context menu. Both these methods will prompt for Package, Group, and Name. Fill in the appropriate data, and the new Particle System will appear in the Generic browser outlined in white.

Creating a Sprite Emitter

Creating an emitter inside of Cascade is very easily accomplished. Simply right-click in the Emitter list pane of Cascade and choose New Sprite Emitter. An emitter will be created with Lifetime and Initial Size modules. (Currently these modules do not contain useful default settings; this will be updated in the future). Set the Lifetime to 1 Min/Max and the Size to 30 for X,Y,and Z Min/Max. This will give the particle valid settings to render.

Basic Emitter Options

Right-clicking on an emitter block will bring up a menu of the following options:

Rename Emitter - Let's you change the name of the emitter (Alternatively, you could change the name by going to EmitterName in the global settings, and typing in the new name).

Duplicate Emitter - Duplicates the emitter within the particle system.

Duplicate + Share Emitter - Duplicates the emitter within the particle system, sharing all the modules between the source emitter and the duplicated one.

Delete Emitter - Deletes the emitter (Alternatively you could just select the emitter and hit the DELETE key).

Export Emitter - Exports the emitter from the current Cascade window to a particle system that is selected in the General Browser. (Open the particle system with the emitter you want to export, go to the General Browser and select the desired target particle system, the go back to the Cascade window and select Export Emitter.)

Creating Modules

Creating modules is done in much the same manner as creating an Emitter. Right-click in the blank space below the Emitter you wish to add to, and choose the Module you want from the drop down list provided.

Copying Emitters

Open the particle system that contains the emitter you want to copy, select the particle system you want it to be copied to in the generic browser, right click on the emitter you want to copy, and choose Emitter>Export Emitter. That will create a copy of the emitter in the other particle system.

Modules

Module Information

If you change a property to a distribution type that changes over time, some modules use 'relative time' and some use 'absolute time' (more on distributions below).

• Absolute time is basically the containing emitter time. If you have an emitter set up for 3 loops of 2 seconds, Absolute time for modules in that emitter will run from 0 to 2 seconds three times.

• Relative time is between 0 and 1, indicating the the lifetime of each particle.

Descriptions of the currently available modules can be found at ParticleSystemReference.

Module Interaction

Modules interact with each other based on their location in the stack within an emitter. For example, creating an emitter with an Initial Location of Min(x=2, y=2, x=2), Max(x=-2, y=-2, z=-2) will spawn the particles in a very small box, then an Initial Velocity with the StartVelocityRadial set to 100 Min and Max will cause the particles to move away from the center of the box. Adding another Initial Location with Max and Min values of 100 for X, Y, and Z will move the entire emitter 100 units away in all directions, but the particles will still move away from the center of the newly located box. Moving the second Initial Location module above the Initial Velocity module will cause the particles to move away from the origin of the system rather than the location offset.

Distribution Types

See the Particles Reference page for more details.

Particle System Level of Detail (LOD)

Particle systems in UnrealEngine3 now provide level-of-detail support. This document will cover the creation of LOD levels in your particle system as well as the in-game usage of them.

Cascade LOD Controls

The following section of the Cascade toolbar covers the LOD controls.

Cascade LOD Controls

A break down of each control follows.

The LOD Slider Control

The LOD Slider, pictured above, allows for real-time interpolation between existing LOD levels. The highest LOD level is represented by an LOD setting of 0, the lowest is represented by 100. By moving the slider bar, or typing values directly into the text edit field, different levels will be utilized in the real-time preview window. When the selected value is between static LOD levels, the editor will interpolate between the two nearest static levels. This allows for previewing potential static levels for addition to the system.

Jump to Highest LOD Button

When the Jump to Highest LOD button is pressed, the system will be set to the highest available static LOD.

Jump to Higher LOD Button

When the Jump to Higher LOD button is pressed, the system will be set to the next available higher static LOD than the current LOD setting.

Add LOD Button

When the Add LOD button is pressed, the system will insert a new static LOD level at the current level setting on the slider bar.

Jump to Lower LOD Button

When the Jump Lower to LOD button is pressed, the system will be set to the next available lower static LOD than the current LOD setting.

Jump to Lowest LOD Button

When the Jump to Lowest LOD button is pressed, the system will be set to the lowest available static LOD.

LOD Combo Selection

The LOD Combo allows for the selection of any existing static LOD level.

Regen Lowest LOD Button

When the Regen Lowest LOD button is pressed, the particle system will remove all existing lower LOD levels and regenerate a new the lowest.

Regen Lowest LOD Duplicate Button

When the Regen Lowest LOD Duplicate button is pressed, the particle system will remove all existing lower LOD levels and regenerate a new the lowest that is an exact copy of the highest level.

Delete LOD Button

When the Delete LOD button is pressed, the currently selected static LOD level will be deleted from the particle system.

Creating LOD Levels in a Particle System

The following section will go over the intended design flow for creating particle systems will full LOD support.

The highest LOD level is used to layout the overall desired effect. It is important to note that modules can only be added/deleted when editing at the highest LOD level. In this example, a single subUV emitter is created displaying a frame of a texture showing a red 1. This is done via a SubImage Index module with a constant index set to 0. The resulting system is shown in the screen-shot below.

Highest LOD Level

The image is slightly blurry due to the large size selected for the particles. This was done for demonstrating the LOD level selection that will happen in-game.

Once the designer feels the particle system is ready for LOD development, he should select Regenerate Lowest LOD from the Edit menu. This will cause the system to regenerate the lowest LOD level. (It will also delete any static LOD levels that were created in the interim.) At the current time, this will simply duplicate the highest LOD level with a lower spawn rate. Once feedback is collected from internal teams, appropriate generation routines for common modules will be implemented.

After selecting the lowest LOD level, tweaking of values can commence on it to get the appropriate look. One thing to note is that by default, all modules in the static LOD level are marked un-editable. This is represented by the module showing a marbled background. (This background texture is subject to change.) To edit a module in a static LOD level, it must be enabled. This is done by right-clicking the module and selecting Enable Module from the context menu.

In our example, we have enabled the SubImage Index module for editing and set the index to 3. This results in an emitter showing a green 4, and is shown below:

Lowest LOD Level

Note that the spawn rate was automatically set to 10% of the highest LOD level.

The next step would involve previewing LOD settings in-between the highest and lowest via the slider bar. In this case, we select a slider value of 33 and drop a static LOD level by pressing the Add LOD button. The SubImage Index module is enabled and has the index set to 2. This results in the emitter showing a yellow 2, as shown below:

LOD Level 1 (Setting 33)

The same was done for a level setting of 66. The SubImage Index was set to 3 resulting in an emitter displaying a blue 3, as shown below:

LOD Level 2 (Setting 66)

LOD Method and Distance Settings

In-game control of particle system LOD is accomplished one of two ways. An enumeration in each particle system called LODMethod provides the method for determining how.

The first allowed value is Direct mode, indicated by selecting PARTICLESYSTEMLODMETHOD_DirectSet for the LODMethod property. When this mode is selected, the particle system will use the LOD level that is set on it. This is intended for game-spawned effects, and assumes that the appropriate level will be set on it as required.

The second allowed value is Automatic mode, indicated by selecting PARTICLESYSTEMLODMETHOD_Automatic for the LODMethod property. When this mode is selected, the particle system will determine the LOD level to utilize at spawn time, as well as each time it loops for looping effect. The level is determined by calculating the distance from the camera, looking up the appropriate level in the LODDistances array. The system will select the level based on the distance being greater than or equal to the entries in the array.

The following image shows the property window for our particle system example:

The LODDistances Property Window

In this example, LOD 0 (the highest) would be used when the emitter is from [0..1249] units from the camera. LOD 1 would be from [1250..1874], LOD2 from [1875..2499], and LOD3 when the distance is greater than 2500 units.

The LODDistanceCheckTime is used to set how often (in seconds) each ParticleSystemComponent set to Automatic mode will perform distance checks for LOD determination at run-time. In this case, each instance of this particle system in the level will perform its distance check every tenth of a second.