Parameter syntax

Revision as of 16:24, 7 November 2012 by HE-Nate (Talk | contribs)
Jump to: navigation, search



Among the properties for Particle Asset Specs and several types of instances, there are complex parameter types. These parameters are represented by strings, and can be edited directly or via the GUI, or set (as strings) by scripts. Animation Sequences can also use these as value inputs to various Animation Abilities.

The string is parsed by HeroEngine to determine how the dynamic value of the property will be computed on demand. For a given property, the parameter has a single valid return type: float, vector or color.

Float Parameters

A float parameter -- for example, "Range" on a light instance -- is one that dynamically returns a float value. There are five types of float parameters:


A Value is the simplest type of parameter -- its syntax and behavior are exactly like a normal float.

Param value.png

Examples: "0", "1.005", "-3.398127", and so on.


The result of a Gaussian parameter is a random number within the specified range, with the given median and variation. The syntax of the string is:


minimum and maximum specify the range for the possible result.

variation is a float (typically from 0 to 1) representing how evenly the result values are distributed -- at 0 nearly all values are very close to the median, while at 1 the distribution is almost flat.

median is a number from -1 to 1 representing where the peak of the distribution is, where -1 means the peak is at the minimum, 0 means the peak is exactly between minimum and maximum, and 1 means the peak is at the maximum.

The GUI remaps median to the range between minimum and maximum, and displays a curve to illustrate the distribution of result values.



Param gaussian2.png


Perlin parameters use Perlin Noise to generate their results based on two inputs: a position and a time, both provided internally by the engine. (Note that for some parameters, the input position will always be (0,0,0).)

The syntax of the parameter string is:


octaves specifies the number of octaves (1-8) that the Perlin noise function will iterate through. Specifying a negative number will fold the results back on themselves with an absolute value function. Using more octaves may impact performance penalty if the parameter is referenced very frequently (as with large numbers of particles).

min and max specify the possible range of result values.

[T/X](s) specifies the X input. "T" specifies that time will be used, "X" specifies that the input vector's X value will be used. s, a float, is the scale that the X input is multiplied by. The higher the scale, the faster the result value will change with changes in the input time or position.

[T/Y](s) and [T/Z](s) corresponsd to the Y and Z inputs respectively.

timeoffset is a float added to the time input, which can be used to offset the phase from other Perlin parameters that also use time.

Alternately, if you don't need the positional input a shorter syntax may be used:


This is equivalent to P(octaves)<min,max,T(timescale),Y(0),Z(0),timeoffset>.

The Perlin parameter helper GUI also displays a small 2D representation of the noise function the specified arguments generate. The XY, XZ and YZ radio buttons select a plane to view. (Time inputs do not affect the display, however.) The 1D checkbox switches into the short form where a single time scale is used.


Perlin time.png


Timeline parameters vary the result value over time, interpolating between a number of keyframes. The string syntax is:


looptype is "O" to loop once, "L" to loop repeatedly, and "P" to ping-pong between the beginning and end (reversing direction as needed).

duration is a float specifying the time in seconds that it takes to navigate through the timeline once. In the case of particle specs, if the duration is omitted the lifespan of each individual particle is used instead.

Each keyframe has the syntax:


Where time is a float from 0 to 1 indivating where along the time span the keyframe occurs, value is the result value at that time, and curve is the interpolation curve to follow until the next keyframe is reached.

curve uses the following abbreviations:


Value timeline 2008.PNG

Value timeline 2008 ping pong.PNG

Value timeline 2008 smooth.PNG


Trigonometric parameters give a result value that varies over time according to a sine function. The string syntax is:

 ~SINE(min=minimum, max=maximum, off=offset, amp=amplitude, frq=frequency, cyc=period, pha=phase)

min and max are the values at which the output is clipped.

off is the "DC offset," the value at the center of the sine wave.

amp is the amplitude of the sine wave (the difference between the center and maximum values).

frq is the frequency of the sine wave, while cyc is the period of time each cycle takes. The actual resulting frequency in Hz is frq/cyc; both parameters are supplied as a convenience, so you can leave one argument at 1 and set the other.

pha is the phase in degrees (0-360). This can be used to offset the phase of different properties (or instances) while keeping them synchronized.


Param sine1.png

Param sine2.png

Param sine3.png

Param sine4.png

Color Parameters

A color parameter returns a color value (a set of floats r, g, b and a with a typical range of 0 to 1). There are four types of color parameters:


An RGB color parameter is simply a fixed color value. The string syntax is:


Color Picker GUI

The Color Picker GUI allows you to pick the color from a wheel, as well as specify a color in either RGB or HSB format. Alpha values can also be changed, and set either to static values, or dynamic values via various timelines.

Param rgb.png

Gaussian RGB

A Gaussian RGB color parameter is an extension of the RGB color parameter type. Any of the elements r, g, b and a may be either a value or a gaussian. Gaussian parameters are reevaluated every frame, causing a flickering effect useful for torches, fluorescent lights, etc.



Param gaussianRGB2.png

HSB Perlin

HSB Perlin color parameters have the syntax:


where each of the four elements may be either a float or a Perlin parameter. hue is in the range 0-360, while the other elements have the range 0-1.


Param hsbperlin.png

Param hsbperlin2.png


An RGB color timeline is similar in syntax to a float timeline:


However, the keyframe syntax becomes


Where color is an RGB parameter.


Param rgbtimeline.png


Vector Parameters

A vector parameter returns a 3D vector (floats X, Y, Z). There are two types of vector parameters:

Gaussian Vector

A Gaussian vector parameter has the syntax:


Where each element in the vector can be either a float or a Gaussian parameter. These are particularly useful for the Trajectory parameter on particle specs, as the parameter is sampled once per particle when it is emitted.


Param vector1.png

Param vector2.png

Param vector3.png

Vector timeline

A Vector timeline is similar in syntax to the other timelines:


But the keyframe syntax is


This is particularly useful for the Motion property on particles, which is evaluated and applied to each particle every frame.


Param vectortimeline1.png

Param vectortimeline2.png

Material Instance Parameter

Changes made through the Material Instance Properties dialogue are represented in a serialized override string. Values which differ from the base material will appear in the string within the _MaterialOverrides property field in the Properties Panel.

The serialization format is as follows.

serialization_format_version_number % instance_name # hash_string_for_this_material_instance [ diffuse_map_path , diffuse_map_alpha_type , normal_map_path , normal_map_contains_specular_channel , macro_map_path , macro_map_UV_multiplier , shader_map_path , shader_translucency , shader_reflectivity , texture_address_mode_U , texture_address_mode_V , polygon_attributes , animated_UVs_U1 , animated_UVs_V1 , animated_UVs_U2 , animated_UVs_V2 ]

Here is an example of a material override string after changing the diffuse map path. Note that some values are empty and others contain default enumerations which are set by the system.



See Also

Personal tools