Particle effect attributes

Last update: v1.10.0 - See also: Particle system overview

Particle effect attributes are vector values that can be accessed from scripts anywhere inside any layer of an effect. Particle attributes are useful to allow gameplay code to control particle effects behavior on a per-instance scale.
Since version 1.6.0, you can also publish samplers as attribute-samplers, and have your shapes, curves, etc, changed or entirely overridden per-instance by the gameplay code.

Overview

The particle effect attributes panel is visible by default when opening the particle editor:

The attributes will appear inside the node properties panel.
Here are the attributes of the 'FlameThrower.pkfx' effect, in the default sample effects package:

Compact mode

Expanded mode (click on item #8)

1: attribute type icon allows to quickly see what type this attribute is. Here, 'float'. 2: attribute value slider to quickly see in-editor how changing the attribute affects the FX 3: attribute description Description of the attribute. Will be displayed in a tooltip when hovering the mouse on the attribute. Can be made multiline by inserting "\n" 4: reset button resets all attribute values to their default value. 5: create button creates a new attribute at the end of the list. (you can also create a new attribute after an existing one by right-clicking in the panel) 6: reset to default resets this attribute to its default value. 7: save as default saves the current value as the new default value for this attribute. 8: expand properties unrolls the attribute and shows all its properties 9: delete button removes the attribute

Something to note about the quick-tweaking sliders is that they are not saved in the effect file. When opening the effect, they are set to the 'DefaultValue' of the attribute. Their sole purpose is to quickly check how the effect behaves when the attributes change. It allows you to emulate in the editor attribute modifications that would normally occur ingame.
The slider allows you to change the attribute of all spawned instances, between 'MinValue' and 'MaxValue'.

The editor uses the min and max values, wether or not 'HasMin' or 'HasMax' is checked, to setup the slider's range, so if your attribute requires no min and max, but you want to test its value between, say, -10 and 10, you'll just have to set the min/max values to -10 and 10, and keep 'HasMin' or 'HasMax' unchecked. This way, the game will still be able to set values below -10 and above 10, but you'll still have a slider to quickly test the attribute behavior in-editor.

If 'MinValue' is equal to 'MaxValue', The slider will effectively have a 0-wide range, and you will not be able to move it. that's expected behavior.

Attribute Properties

Property name	Default value	Description
AttributeName	<empty>	Name of the attribute, published to the scripts
AttributeType	float	Type of the attribute, can be any of the following types: float float2 float3 float4 int int2 int3 int4
AttributeScope	instance	Scope of the attribute, can be any of the following scopes: global : the same values are used for all the instances of the effect. ex: a value telling if it's the day or the night, or a value telling if it's raining or not, or a global air temperature, or uniform wind speed. NOTE: Disabled in the current version of the editor (v1.8.4) instance : each effect instance has its own copy of the attribute, and the gameplay code can set different values on a per-instance basis. ex: the strength of a flamethrower, the intensity of a fire...
AttributeDescription	<empty>	Description of the attribute, displayed in a tooltip when you move the mouse over the attribute. can contain "\n" sequences to create newlines in the tooltip. The first words of the description are also displayed inline after the attribute name.
DefaultValue	0.0	Initial value of the attribute, of type 'AttributeType', if untouched at effect instantiation time.
HasMin	true	Checked if the attribute has a min value below witch it cannot go.
HasMax	true	Checked if the attribute has a max value above witch it cannot go.
MinValue	0	min value of the slider, of type 'AttributeType', used only if 'HasMin' is checked.
MaxValue	1	max value of the slider, of type 'AttributeType', used only if 'HasMax' is checked.

Access inside scripts

Attributes are automatically accessible from all the scripts of the particle system. They appear as a variable of type 'AttributeType', named 'AttributeName'.

For example, if we create a 'float2' attribute named 'TeamColor', containing the red and blue values of a team color, we can write inside a script:

Color = float4(TeamColor.x, 0, TeamColor.y, 1);

or:

Color = TeamColor.x0y1;

(see swizzling) This will set the particle color to whatever the gameplay sets the 'TeamColor' attribute to.

Example

Here is an example of the 'Throttle' attribute being moved around in the effect 'FlameThrower.pkfx' coming in the base samples package.
The attribute is primarily used to control the spawn velocity of the tracer particles that spawn the flame trails:

	Velocity *= Throttle;

Note that the Velocity is initialized with a stream function (which is a shape sampler) before the spawn script is run, and we're just scaling the sampled velocity

Throttle = 1.0
Throttle = 0.8
Throttle = 0.6
Throttle = 0.4
Throttle = 0.2
Throttle = 0.0

Special attributes

Deprecated v1.10.0, use the view functions instead

If you create the following attributes, the editor will recognize them, and set them each frame to the corresponding viewport's camera data:

• float3 ViewPosition : 3D coordinates of the camera position Deprecated v1.10.0, use the view.position() function instead
• float3 ViewDirection : 3D vector along which the camera is looking Deprecated v1.10.0, use the view.axisForward() function instead
• float3 ViewForward : camera 'forward' vector, Same as 'ViewDirection' Deprecated v1.10.0, use the view.axisForward() function instead
• float3 ViewUp : camera 'up' vector Deprecated v1.10.0, use the view.axisUp() function instead
• float3 ViewSide : camera 'side' vector Deprecated v1.10.0, use the view.axisSide() function instead

Attribute samplers

Since version 1.6.0, you can also publish samplers as attribute-samplers, and have your shapes, curves, etc, changed or entirely overridden per-instance by the gameplay code.