Particle Effects

This feature requires FreeSpace Open

Revision information.....

FSO Git Commit: Date: 2016-08-04 SHA: a570eca

Note: Please update the revision information when the page is updated. If your edit had nothing to do with new code entries then please do not edit the revision information

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the Modular Tables and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual +nocreate ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with +nocreate in mind for when that is implemented.

List of Tables

General Info

• Begins with #Particle Effects
• Contains zero or more particle effect definitions
• Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

$Effect:

• Creates a new effect and specifies its name. The name must be at least one character long.
• Syntax: String

$Type:

• Sets the type of this effect. See Effect Types for possible values.
• Syntax: String

Effect Types

There are multiple different types of effects. They are specified by passing the given name to $Type.

Single

This effect type creates exactly one particle per processing step.

Properties

The properties of this created particle can be specified by a #Particle properties construct.

Timing properties

For specifying how long this effect is active an #Effect timing construct is used.

Composite

A composite effects contains multiple other effects which are all displayed at the same time. The amount of child effects is not limited. This type currently does not support +nocreate.

+Child effect:

• This specifies a child effect that should be added to the composite effect. The effect is specified using #Inline effect creation.

Cone

This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a normal distribution around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

Properties

The common properties of the created particles can be specified by a #Particle properties construct.

+Deviation:

• Sets the standard deviation from the direction vector.
• Required if +nocreate is not present
• Syntax: float, in degrees

+Velocity

• Sets the velocity of the created particles. This is a #Uniform random range.
• Required if +nocreate is not present
• Syntax: See #Uniform random range

+Number

• Sets the amount of created particles. This is a #Uniform random range.
• Required if +nocreate is not present
• Syntax: See #Uniform random range

+Direction

• Sets the direction the cone will be centered around. Can be one of:
  • Incoming: The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it had when the effect was created.
  • Normal: The normal of the impact.
  • Reflected: The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot.
  • Reverse: The reverse of the incoming vector
• Optional
• Syntax: String, one of the strings specified above

+Trail effect:

• Sets the particle effect used for the trail of the created particles. This option uses #Inline effect creation.
• Optional
• Syntax: See #Inline effect creation.

Common syntax constructs

Some syntax constructs are used multiple times by different types. Due to the similarity they are described one at this point and then references by the documentation of the individual effects.

Particle properties

This contains some common properties of particles, e.g. the used animation or the size.

+Filename:

• Sets the filename of the animation that should be used.
• Required if +nocreate wasn't used
• Syntax: String, filename

+Size:

• Sets the size of the created particles. This is a uniformly distributed random range, see #Uniform random range.
• Required if +nocreate wasn't used
• Syntax: See #Uniform random range

+Lifetime:

• Sets the life time of the particles. This is a uniformly distributed random range, see #Uniform random range, or the string <none> in which case the runtime of the animation is used. Defaults to <none>.
• This is optional
• Syntax: See #Uniform random range, or the string <none>

Effect timing

Effect timings are used to specify for how long and after how much delay an effect is active. Each effect timing is parsed in its entirety each time it is expected. That means that if you use +nocreate then you must respecify all values. This restriction may be lifted in the future.

+Duration:

• Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string Onetime. If the effect should always be active you can specify the string Always. Otherwise a non-negative random range is expected.
• This is optional
• Syntax: Onetime, Always, or a #Uniform random range.

+Delay:

• Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is Onetime.
• This is optional
• Syntax: See #Uniform random range, or the string <none>

Inline effect creation

At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use $New Effect which will create a new, unnamed effect. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If $New Effect is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. +nocreate is not valid within this element.

Random range

The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

Uniform random range

• This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
• Syntax: Float list, one or two values

Normal distribution random range

• This accepts 1 or 2 values. This random range generates values according to a normal distribution. The first value specified the mean value of the distribution. The second value specified the standard deviation of the distribution, this defaults to 1.
• Syntax: Float list, one or two values

Example

#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
	+Filename: exp05
	+Size: (5 7)
	+Lifetime: (0.6)
	+Deviation: 5
	+Velocity: (500 700)
	+Number: (20 30)
	+Direction: Reflected
	+Trail effect: $New Effect
		$Type: Single
			+Filename: exp20
			+Size: (10)
			+Lifetime: (1)
			+Duration: Always


$Effect: ApocalypseIgnition
$Type: Single
	+Filename: exp20
	+Size: (10 20)
	
$Effect: ApocalypseHomed
$Type: Composite
	+Child effect: $New Effect
		$Type: Single
			+Filename: exp05
			+Size: (5 7)
			+Duration: (2 10)
	+Child effect: $New Effect
		$Type: Single
			+Filename: exp06b
			+Size: (5 7)
			+Duration: (2 10)
			+Delay: (8 15)

#End