Parameter syntax

Revision as of 16:33, 7 November 2012

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.

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:

• "<-1, 1, .5, 0>" -- a pretty standard bell curve with results in the -1 to 1 range, more likely to be near 0.

• "<0, 10, 0.05, -1>" -- most results will be near 0, but there will be rare results up to a maximum possible value of 10.

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:

• "P(1)<0.05,0.15,1,0>" Varies a property (for instance, Size2D on a billboard particle spec) over time, between the ranges of 0.05 and 0.15.

• "P(1)<0.05,0.15,3,0>" Varies the property 3 times faster than the first example.

• "P(8)<0.05,0.15,3,0>" Note the much more complex behavior over time, with tiny small variations and larger trends.

• "P(-1)<0.05,0.15,3,0>" Changes may appear to be more dramatic, and values are reflected linearly around the lowest value.

• Set Size2D to "1", XScale2D to "P(2)<0.02,0.2,1,0>" and YScale2D to "P(2)<0.02,0.2,1,1>". Note how the result values are out of phase, causing the particle to stretch and squash along one axis and then the other.

• Here is P(2)<0, .5, 1, 0> being used to vary the Size2D parameter of a particle over its lifetime.

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:

• "H" = HOLD
• "L" = LINEAR
• "S" = SMOOTH
• "I" = EASE_IN
• "O" = EASE_OUT
• "T" = TWIST
• "Q" = SQUARE
• "P" = INV_SQUARE

Examples:

• "[0:0:L][1:0.2:L]O" on a billboard particle spec's Size2D property will start each particle at a size of 0, and linearly interpolate across the life of the particle to a maximum size of 0.2.

• "[0:0:L][1:0.2:L]P;1" will cause all particles using that spec to grow from 0 to 0.2 linearly over 1 second, shrink back to 0 over 1 second, and repeat.

• "[0:0:S][0.1:0.2:H][0.9:0.2:S][1:0:L]O" will cause each particle to smoothly grow from 0 to .2 over 1/10 of the particle's lifespan, maintain that size until 9/10 of the lifespan has passed, and then smoothly shrink back to 0.

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:

• "~SINE(min=0,max=1,off=0.5,amp=0.5,frq=1,cyc=1,pha=0)" oscillates between 0 and 1, completing a full cycle once per second.

• "~SINE(min=0,max=1,off=1,amp=0.5,frq=1,cyc=1,pha=0)" would oscillate between 0.5 and 1.5, but the maximum value is clipped at 1.

• "~SINE(min=0,max=1,off=0,amp=10,frq=1,cyc=1,pha=0)" would oscillate between -10 and 10, but the values are clipped from 0 to 1. The high amplitude results in a very steep transition from 0 to 1.

• Create two lights, one red and one green. Give the red light an intensity of "~SINE(min=0,max=2,off=1,amp=3,frq=1,cyc=1,pha=0)" and the green light an intensity of "~SINE(min=0,max=2,off=1,amp=3,frq=1,cyc=1,pha=180)". The lights will blink at the same rate but at opposite phases.

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.

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:

• "#<.0,1.0,.291,-.356>,0,0,1" The red element will vary between 0 and 1, while green and blue remain fixed at 0 and alpha at 1.

• "#<.0,1.0,.1,-1.0>,<.0,.5,.3,-1.0>,<.0,1.0,.5,-1.0>,<.0,1.0,.11,1.0>" All four elements vary, with an overall tendency toward a high-alpha bluish color.

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:

• "HSB(P(-3)<0,360,X(0.1),Y(3),Z(1),0>; 0.5; 0.5; 0.6)" hue varies with the input position; since there is no time element, at any given position the hue will always be the same. saturation, brightness and alpha remain constant.

• "HSB(35;1;P(4)<.2,.6,T(3.0),Y(1.0),Z(1.0),.0>;1)" brightness varies over time, creating a smoother flickering effect for lights than Gaussian parameters can achieve.

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:

• "[0.295:#.812,.127,.659,1.0:L][0.66:#.788,.119,.677,1.0:O][0.87:#.376,.265,.704,1.0:L]L;1.3" The color cycles through red, green and blue in a 2 second loop.

• "[0:#0,0,0,0:L][.25:#1,1,1,1:H][.75:#1,1,1,1:L][1:#0,0,0,0:L]L;4" Smoothly fade in and out.

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

• "(0,1,0)" A simple vector pointing straight up.

• "(<-0.5,0.5,0.1,0>,1,<-0.5,0.5,0.1,0>)" A vector that tends to point upwards, but there is some variation along the X and Z axes. Particles spray from their emitter in a cone.

• "(0,<-4,4,0.1,0>,0)" A random vector along the Y axis. Particles move in two directions at random velocities, most of them slow.

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

• "[0:(0,0,-1):H][0.5:(0,.5,0):H][1:(0,0,0):L]O" Start moving in a straight line along the Z axis. Halfway through the particle's life span, take a 90 degree turn and move up along the Y axis at half speed.

• "[0.075:(3.75,-3.75,3.75):S][0.23:(3.75,-3.75,-7.630000114):S][0.68:(3.75,-3.75,9.180000305):S][1:(3.75,-3.75,3.75):I]O;3" Moves downward along the Y axis while curving on the Z axis:

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 ]

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

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.

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

See Also

• Material Instances

• Privacy policy
• About HEWIKI
• Disclaimers

• Copyright (c) 2006-2013 Idea Fabrik Plc. All Rights Reserved.
• HeroCloud is a registered trademark of IdeaFabrik Plc, all rights reserved
• HeroEngine is a registered trademark of IdeaFabrik Plc, all rights reserved