Parameter syntax

From HEWIKI
Jump to: navigation, search

Contents

Overview

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:

Value

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.

Gaussian

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,maximum,variation,median>

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.

Examples:

HeroBladeGaussianVectorParameter.png

Param gaussian2.png

Perlin

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:

 P(octaves)<min,max,[T/X](s),[T/Y](s),[T/Z](s),timeoffset>

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:

 P(octaves)<min,max,timescale,timeoffset>

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.

Examples:

Perlin time.png

Timeline

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

 [keyframe]{[keyframe]...}looptype{;duration}

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:

 [time:value:curve]

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:

Examples:


Value timeline 2008.PNG

Value timeline 2008 ping pong.PNG

Value timeline 2008 smooth.PNG

Trigonometric

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.

Examples:

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:

RGB

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

 #r,g,b,a

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.

Examples:

ParameterSyntaxGaussianRGB.png

Param gaussianRGB2.png

HSB Perlin

HSB Perlin color parameters have the syntax:

 HSB(hue;saturation;brightness;alpha)

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.

Examples:

Param hsbperlin.png


Param hsbperlin2.png

Timeline

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

 [keyframe]{[keyframe]...}looptype{;duration}

However, the keyframe syntax becomes

 [time:color:curve]

Where color is an RGB parameter.

Examples:

Param rgbtimeline.png

HeroBladeRGBTimelineSyntax.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:

 (x,y,z)

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.

Examples::

Param vector1.png

Param vector2.png

Param vector3.png

Vector timeline

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

 [keyframe]{[keyframe]...}looptype{;duration}

But the keyframe syntax is

 [time:(x,y,z):curve]

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

Examples

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.

This section describes the serialization format in detail. For definitions on the properties themselves, see the Material Instance Properties Options section.

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 ]

serialization_format_version_number

This number represents the designation of the above format. This is the first format for Material Instances, so it is designated "0".

instance_name

The name of the instance will be depicted both in the serialization string as well as in the Material Instance Properties dialogue material selection table view. The name of a material instance is derived and identical to the base material from which the instance is inherited. Additionally, a list of material names on an HBNode can be retrieved using the HSL external client function ListNodeMaterials().

hash_string_for_this_material_instance

A hash value is used to internally key this material instance in a material instance manager. To avoid redundancies, the hash value is used as a unique identifier for the material. Input for the hash function which creates the hash value is simply the entire serialized string without this hash value.

diffuse_map_path

This is the FQN repository path to the .dds file to be used as the diffuse map.

diffuse_map_alpha_type

The alpha types are serialized as enumrated integers here. There are currently 5 values (representing enumerated types) ranging from 0 - 4. For more information on this and the following properties, see the Material Instance Properties Options section

normal_map_path

This is the FQN repository path to the .dds file to be used as the normal map.

normal_map_contains_specular_channel

This value is either 1 (true) or 0 (false), indicating that there IS or IS NOT a specular channel in the normal map.

macro_map_path

This is the FQN repository path to the .dds file to be used as the macro map.

macro_map_UV_multiplier

Must be an unsigned integer value.

shader_map_path

This is the FQN repository path to the .fx file to be used as the shader map.

shader_translucency

Represented as a positive floating-point value.

shader_reflectivity

Represented as a positive floating-point value.

texture_address_mode_U

Like the diffuse_map_alpha_type value, this is an enumerated type. The supported range is from 0 - 2.

texture_address_mode_V

Like the diffuse_map_alpha_type value, this is an enumerated type. The supported range is from 0 - 2.

polygon_attributes

This property is planned for support at a future time and should be ignored for now.

animated_UVs_U1

Represented as a floating-point value.

animated_UVs_V1

Represented as a floating-point value.

animated_UVs_U2

Represented as a floating-point value.

animated_UVs_V2

Represented as a floating-point value.


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.


0%mushroom_demo6#82b311bfb05255ae1e9822a0c49b3aab[/techart/hill/grannyexport/textures/orange_utility.dds,1,,,,1,,0,0,1,1,1,0,0,0,0]


MaterialInstancePropertiesDialogueExample.png

See Also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox