Particle Effects

This feature requires FreeSpace Open

Revision information.....

FSO Git Commit: Date: 2024-08-26 SHA: 91a673ac586a57e8f7793f08985b6f17a7fd1aa7

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

List of Tables and related code files
* Notes Modular Tables
** Notes tables which only use modular tables
Ai.tbl*	/ai/aicode.cpp
Ai_profiles.tbl*	/ai/ai_profiles.cpp
Animation.tbl**	/model/modelanimation.cpp
Armor.tbl*	/ship/ship.cpp
Asteroid.tbl*	/asteroid/asteroid.cpp
Autopilot.tbl*	/autopilot/autopilot.cpp
Cheats.tbl*	/cheats_table/cheats_table.cpp
Colors.tbl*	/globalincs/alphacolors.cpp
Curves.tbl*	/math/curves.cpp
Controlconfigdefaults.tbl	/controlconfig/controlsconfigcommon.cpp
Credits.tbl*	/menuui/credits.cpp
Cutscenes.tbl*	/cutscene/cutscenes.cpp
Decals.tbl**	/decals/decals.cpp
Fireball.tbl*	/fireball/fireballs.cpp
Fonts.tbl*	/graphics/font.cpp
Game_settings.tbl*	/mod_table/mod_table.cpp
Glowpoints.tbl*	/model/modelread.cpp
Help.tbl*	/gamehelp/contexthelp.cpp
Hud_gauges.tbl*	/hud/hudparse.cpp
Icons.tbl*	/mission/missionbriefcommon.cpp
Iff_defs.tbl*	/iff_defs/iff_defs.cpp
Keywords.tbl*	Not In Codebase
Lighting_Profiles.tbl*	/lighting/lighting_profiles.cpp
Lightning.tbl*	/nebula/neblightning.cpp
Mainhall.tbl*	/menuui/mainhallmenu.cpp
Medals.tbl*	/stats/medals.cpp
Messages.tbl*	/mission/missionmessage.cpp
Mflash.tbl*	/weapon/muzzleflash.cpp
Music.tbl*	/gamesnd/eventmusic.cpp
Nebula.tbl*	/nebula/neb.cpp
Objecttypes.tbl*	/ship/ship.cpp
Options.tbl*	Not In Codebase
Particle effects(-part.tbm)**	/particle/effects...
Post_processing.tbl	/graphics/gropenglpostprocessing.cpp
Rank.tbl*	/stats/scoring.cpp
Scpui.tbl*	Not In Codebase
Scripting.tbl*	/parse/scripting.cpp
Ships.tbl*	/ship/ship.cpp
Sexps.tbl**	/parse/sexp/sexp_lookup.cpp
Sounds.tbl*	/gamesnd/gamesnd.cpp
Species_defs.tbl*	/species_defs/species_defs.cpp
Species.tbl*	/menuui/techmenu.cpp
Ssm.tbl*	/hud/hudartillery.cpp
Stars.tbl*	/starfield/starfield.cpp
Strings.tbl*	/localization/localize.cpp
Tips.tbl*	/menuui/playermenu.cpp
Traitor.tbl*	/stats/scoring.cpp
Tstrings.tbl*	/localization/localize.cpp
Virtual_pofs.tbl*	/model/modelreplace.cpp
Weapon_expl.tbl*	/weapon/weapons.cpp
Weapons.tbl*	/weapon/weapons.cpp

FS2 Open, 25.0:

This table has been significantly refactored for FSO 25.0. For documentation of the old table style, see Legacy Particle Effects

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.

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.

FS2 Open, 25.0:

• Particles as described here and as described in Legacy Particle Effects both share the *-part.tbm table, and can exist alongside oneanother within the same file.
• As such, it is not required to refactor legacy-style particles to the new format, unless the usage of newer features is desired.

$Effect:

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

+Filename:

• Sets the filename of the animation that should be used.
• Allows for setting list of filenames the animation should use. If multiple animations are listed it picks randomly from the list for each spawned animation.
• Syntax: String or String List, filename(s)

+Bitmap Alignment:

• Sets how the bitmap is aligned
• Syntax: One of Screen Aligned, Random, or Default (uses the setting defined globally in Game_settings.tbl#$Randomize particle rotation:)

+Radius:

• Sets the radius of the created particles. This is a random range; see Parsed random range.
• Exactly one of +Radius and +Parent Radius Factor is required.
• Syntax: See Parsed random range

+Parent Radius Factor:

• Sets the radius to be a factor of the current size of the particle that spawned it. Only works when spawned as a trail particle effect of another particle. This is a random range; see Parsed random range.
• Syntax: See Parsed random range

+Length:

• If specified, orients the animation along its velocity, and stretches it by this distance. This is a random range; see Parsed random range.
• This is optional
• Syntax: See Parsed random range

+Lifetime:

• Sets the life time of the particles. This is a random range; see Parsed random range, or the string <none> in which case the runtime of the animation is used. Defaults to <none>.
• This is optional, but only one between +Lifetime and +Parent Lifetime Factor may be used.
• Syntax: See Parsed random range, or the string <none>

+Parent Lifetime Factor:

• Sets the lifetime to be a factor of the remaining lifetime of the particle that spawned it. Only works when spawned as a trail particle effect of another particle. This is a random range; see Parsed random range.
• This is optional, but only one between +Lifetime and +Parent Lifetime Factor may be used.
• Syntax: See Parsed random range

+Remain local to parent:

• If this is true, the effect will be 'parented' to its spawner, and will move with it, inheriting all changes to the spawner's position and orientation. Very useful for some types of muzzle effect.
• Defaults to false.
• Syntax: Boolean

+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 Parsed random range.

+Delay:

• Specifies after how much time after the effect is triggered the effect starts creating particles.
• This is optional
• Syntax: See Parsed random range

+Spawns per second:

• Specifies how many times per seconds particles will spawn from this effect. If this is not specified then the effect is triggered every frame. If this is specified then the amount of triggers per second is always the same regardless of the FPS the game is running at. Values higher than the FPS (e.g. 120 if the game is running at 60 FPS) are handled correctly and will trigger the effect multiple times per frame if necessary.
• Batches of particles spawned at different points during a frame will be spawned at the correct positions along a moving spawner entity's trajectory, with millisecond precision, rather than all 'clumping' at the spawner's final position for that frame. This works for particles spawned from objects (like ships and weapons), and ones spawned from other particles (as with a $Trail effect), but does not currently work for particles spawned from beams.
• This is optional
• Syntax: number. Must be greater than 0.

+Particle Count Per Spawn:

• Sets the amount of particles created every time this effect spawns new particles. This is a Parsed random range.
• This setting is multiplicative with +Spawns per second:. The former defines how often things are spawned, while +Particle Count Per Spawn: defined how many individual particles are spawned each time.
• Syntax: See Parsed random range

+Direction:

• Sets the direction of the particle spawner. This influences many following options, which will be marked with affected by orientation. Can be one of:
  • Aligned: The direction of the particle spawner will be aligned by whatever created it. This could be the direction a muzzle is facing, a weapon is flying, a beam is shooting, etc.
  • HitNormal: The direction of the particle spawner will be set to the normal vector of the event that spawns the particle. This can be something like the normal vector of a weapon impact. If no normal vector exists for a given event, Aligned will be used instead.
  • Reflected: The direction of the particle spawner will be set to the Aligned direction after it is reflected off using the normal vector. This is a good way of simulating armor deflecting a shot. If no normal vector is present in the current event, it'll be set to Aligned instead.
  • Reverse: The reverse of the Aligned vector
• Optional
• Syntax: String, one of the strings specified above

+Position Offset:

• Offsets the position of the particle source relative to the spawner. Positive Z means "forward".
• affected by orientation
• For effects spawned from sources will a full orientation, such as ships (including primary or secondary muzzle effects) and weapons (including hit effects), all three dimensions will work correctly.
• For effects spawned from sources that just have a defined forward vector, such as particles (as with trail effects) or beams, the X and Y axes will have no influence.
• Optional
• Syntax: Vector, three floats, x, y and z values respectively

+Spawn Position Volume:

• Defines the volume around the particle effect spawner in which the particles will spawn (randomly distributed within the volume).
• affected by orientation
• Optional
• Syntax: One of the following types

Spheroid

+Radius:

• Specifies the radius of the volume
• Optional
• Syntax: float, default 1

+Bias:

• Causes the particles to spawn more frequently near the edges or near the center. Values greater than 1 bias the particles toward the center, less than 1 biases them towards the edge.
• Optional
• Syntax: float, default 1

+Stretch:

• 'Stretches' or squashes the spherical volume into an ellipsoid. Values greater than 1 stretch it, less than 1 squashes it.
• Optional
• Syntax: float, default 1

$Volume Curve:

• A modular curve set. Repeated occurrences of the following:

+Input

For possible inputs see the inputs for particle source curves

+Output

• One of: Radius Mult, Bias Mult, or Stretch Mult, which are multipliers for the respective tabled values of the spheroid volume

+Curve Name

• The name of the curve which maps the input to the output
• Syntax: string, the curve name

+Random Scaling Factor:

• A random range, which is used to divide the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Random Translation:

• A random range, which is used to offset the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Wraparound:

• If set, values outside the defined range of the curve will be wrapped around instead of clipped.
• Optional
• Syntax: boolean, default true

Cone

+Deviation:

• Specifies the standard deviation by how much an average particle will deviate from the given spawner direction in degrees.
• Exactly one of +Deviation or +Deviation Profile is required
• Syntax: float

+Deviation Profile:

• Specifies the deviation of a particle from the given spawner direction as a random range in radians.
• Syntax: See Parsed random range

+Length:

• Specifies the distance from the spawner at which particles spawn, in meters.
• Optional
• Syntax: See Parsed random range, default constant 1

$Volume Curve:

• A modular curve set. Repeated occurrences of the following:

+Input

For possible inputs see the inputs for particle source curves

+Output

• One of: Deviation Mult, or Length Mult, which are multipliers for the respective tabled values of the spheroid volume

+Curve Name

• The name of the curve which maps the input to the output
• Syntax: string, the curve name

+Random Scaling Factor:

• A random range, which is used to divide the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Random Translation:

• A random range, which is used to offset the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Wraparound:

• If set, values outside the defined range of the curve will be wrapped around instead of clipped.
• Optional
• Syntax: boolean, default true

+Velocity Volume:

• Defines a volume. The position sampled in this volume is used as the velocity vector for the spawned particles. I.e., a sphere as the velocity volume will let the particles randomly accelerate outwards evenly.
• affected by orientation
• Optional
• See #+Spawn Position Volume:

+Velocity Volume Scale:

• A random range, which is used to scale the velocity vector sampled from the velocity volume.
• Optional
• Syntax: See Parsed random range, default constant 1

+Velocity Direction Scale:

• Sets whether the particles final velocity is scaled based on the direction of the velocity and the direction of the particle spawner.
• affected by orientation
• Optional, default None
• Can be one of:
  • None: No scaling is applied
  • Dot: The velocity is scaled by the dot product between the velocity orientation and the spawner orientation. This means that particles flying in the same direction as the spawner points to will be faster.
  • Inverse Dot: The velocity is scaled by the inverse dot product between the velocity orientation and the spawner orientation. This means that no matter the direction the particle velocity points to, all particles will have the same velocity in the direction of the spawner (assuming that the scalar velocity of all particles is equal).

+Velocity From Position:

• If set, will add the particles relative position to the spawn point multiplied by this random range as velocity. This will make the particles naturally spread outwards from the spawner. This is a random range; see Parsed random range.
• Has no effect if no spawn position volume is tabled.
• Optional. Mututally exclusive with +Absolute Velocity From Position.
• Syntax: See Parsed random range

+Absolute Velocity From Position:

• See #Velocity From Position:, except that the position is normalized before applying the random range.

+Velocity From Orientation:

• If set, will add the spawners orientation multiplied by this random range as velocity. This will make the particles naturally move in the direction the spawner points to. This is a random range; see Parsed random range.
• affected by orientation
• Optional.
• Syntax: See Parsed random range

+Velocity Inherit:

• If set, will add the parent's velocity multiplied by this random range as velocity for the particle. This will make the particles naturally move along with their spawning entity. This is a random range; see Parsed random range.
• Optional. Mututally exclusive with +Absolute Velocity Inherit.
• Syntax: See Parsed random range

+Absolute Velocity Inherit:

• See #+Velocity Inherit:, except that the parent velocity is normalized before applying the random range.

$Particle Lifetime Curve:

• A modular curve set (though currently not fully fledged).
• This modular curve set affects the spawned particle during its lifetime, and not to the spawner of the particles.
• Repeated occurrences of the following:

+Input

• One of the following: Lifetime (representing the lifetime of the particle, not the spawner)

+Output

• One of:
  • Radius: Multiplies the radius of the particle
  • Velocity, Multiplies the velocity of the particle

+Curve Name

• The name of the curve which maps the input to the output
• Syntax: string, the curve name

$Particle Source Curve:

• A modular curve set. Repeated occurrences of the following:

+Input

• One of:
  • Host Radius: The radius of whatever object the particle spawner is attached to (such as the weapon spewing the particles, etc).
  • Host Velocity: The velocity of whatever object the particle spawner is attached to.
  • Effects running: The fraction of sub-effects of this effect that are still emitting particles.
  • Spawntime Left: The remaining time this sub-effect will emit particles for.

+Output

• One of:
  • Particle Number Mult: Multiplies the number of particles created each spawn
  • Particle Frequency Mult: Multiplies the frequency with which particles are spawned
  • Radius Mult: Multiplies the initial radius of spawned particles
  • Length Mult: Multiplies the initial length of spawned particles
  • Lifetime Mult: Multiplies the lifetime of spawned particles
  • Velocity Volume Mult: Multiplies the velocity obtained from the tabled velocity volume
  • Velocity Inherit Mult: Multiplies the velocity obtained from the tabled velocity inherit
  • Velocity Position Inherit Mult: Multiplies the velocity obtained from the tabled velocity from position
  • Velocity Orientation Inherit Mult: Multiplies the velocity obtained from the tabled velocity from orientation

+Curve Name

• The name of the curve which maps the input to the output
• Syntax: string, the curve name

+Random Scaling Factor:

• A random range, which is used to divide the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Random Translation:

• A random range, which is used to offset the input by the sampled value.
• Optional
• Syntax: See Parsed random range

+Wraparound:

• If set, values outside the defined range of the curve will be wrapped around instead of clipped.
• Optional
• Syntax: boolean, default true

$Trail Effect:

• Adds a particle trail to this effect
• Optional, mutually exclusive with $Trail Inline Effect
• Syntax: string, the name of a particle effect (must be defined previously)

$Trail Inline Effect:

• Adds a particle trail to this effect, defined inline
• It is not possible to define inline trails for inline trails due to parsing ambiguity. If you really need trails of trails of particles, use $Trail Effect:
• Optional
• Syntax: Define a new particle just as if $Trail Inline Effect: had been $Effect. It will not need a name to be specified after $Trail Inline Effect:.

$Continue Trail Effect:

• Adds a new sub-effect to the trail
• Optional, can be repeated multiple times

See #$Continue Effect:

$Continue Effect:

• Adds a new sub-effect to this effect.
• This will then spawn multiple different types of particle effect if the parent effect is called. Similar to the legacy composite effect type.
• Optional, can be repeated multiple times
• Syntax: Define a new particle just as if $Continue Effect: had been $Effect. It will not need a name to be specified after $Continue Effect:.