Skip to content

Particles (Effects)

Jump to bottom Edit New page
Eric Mor edited this page May 31, 2023 · 7 revisions

Particles are small, simple images or models that are displayed and moved in great quantities. The particles component represents a particles system.

Each particle has a lifetime, that determines how long the particle will live. During the lifetime of a particle, many of its properties can change: the position, speed, color, alpha,... When the lifetime of a particle is over, the particle disappears (dies)

Particles are emitted from a certain source (e.g. a point, a sphere), and they move towards a certain direction (e.g. they move upwards, they move in random directions, etc).

Particles can be affected by forces like gravity or wind, interact with surfaces, follow predefined paths, etc

Keyword: particles

Attributes

color <colorRGB...> -vary <colorRGB>

The color applied to the particles, a tint applied to the texture; the default color is white. This field is animatable, so multiple colors can be specified to change the color over the lifetime of the particles.

The -vary can be used to give some variety to the color values.

alpha <float...> -vary <float>

The opacity of the particles, with 1.0 being opaque and 0.0 transparent. This field is animatable, so multiple values can be specified to change the opacity over the lifetime of the particles.

The -vary can be used to give some variety to the alpha values.

size <float...> -vary <float>

The scale of the particles, with the default value being 1.0. This field is animatable, so multiple values can be specified to change the size over the lifetime of the particles.

The -vary can be used to give some variety to the size values.

aspect <float...> -vary <float>

The aspect ratio of the particles, with the default value being 1.0; any value different than that makes the particles become rectangles. This value multiplies the width, so 2.0 will make the particles twice as wide as they are tall. This field is animatable, so multiple values can be specified to change the aspect over the lifetime of the particles.

The -vary can be used to give some variety to the aspect values.

rotate <float...> -vary <float> -offset <float>

The rotation of the particles, in the range 0.0 (no rotation) to 1.0 (a complete rotation, which is the same as no rotation at all). Particles are rotated clockwise, around their normal axis (that is, the normal axis of their plane). This field is animatable, so multiple values can be specified to change the rotation the lifetime of the particles.

-offset is the initial rotation, which is 0 by default. The -vary can be used to give some variety to the rotate values.

stretch <float>

Unknown usage, seems to be related to the velocity of the particles.

Emit Source

The source attribute is used to decide where the particles are emitted from; therefore, it is one of the most important attributes. By default, particles are emitted from a single point at the origin (0, 0, 0).

This attribute has no arguments, it's values are decided with options; these options define the shape, which is always centered around the origin (0, 0, 0). There are some general options that can always be applied:

  • -offset <vector3>: Used to move the shape/point to another coordinates.
  • -scaleParticles
  • -resetIncoming

To define the source of the particles, you can use one (and only one!) of these options:

  • -point: A single point in space.

  • -square <float>: A square. The value is half the length of the side of the square.

  • -quad <vector2>: A rectangle. The values are the half of the lengths of the sides of the rectangle (first horizontal and then vertical).

  • -cube <float>: A cube. The value is half the length of the side of the square.

  • -box <float>: Like a cube, but with different sides. The values are the half of the lengths of the sides of the box (x, y, z).

  • -circle <float>: A circle, the value is the radius.

  • -sphere <float>: A float, the value is the radius.

  • -ellipse <vector3>: Like a sphere, but deformed with different radius. The values are the different radius in the X, Y and Z directions.

  • -ring <float> <float>: A 2D ring, that is, a circle but with an inner circle subtracted. The first value is the (external) radius, the second value is in the range [0.0, 1.0] and is the proportion that is used for the inner, subtracted circle. This means that a value of 0.0 is just like using a full circle, and a value of 1.0 is like having no source.

  • -torus <vector3> <float>: Like -ring, but with different radius. The first value are the radius, in the X, Y and Z directions. The second value is the same as for -ring, also in the [0.0, 1.0] range.

For example, to emit the particles from a sphere of radius 2 centered at (0, 0, 1):

source -sphere 2.0 -offset (0, 0, 1)

Emission Direction and Strength

The emit attribute is used to control the emission direction and speed.

emit -speed <float> (<float>) -dir <vector3> (<vector3>) -base -scaleExisting

Both for the speed and direction, the first value is the value itself, and the second is an optional variance value; if that is specified and not 0.0, particles will be emitted with different random speeds/directions. The direction is a point in space; the particles will go towards that point (if not affected by any forces like gravity). But it is only a direction, not a final point; the particles might not ever reach the point (because they die before) or maybe they go past it.

For example:

# The particles will go in the +X+Y direction.
# They will move 3 units per second, with some variance: their real speed will be in the range [2.9, 3.1]
emit -dir (1, 1, 0) -speed 3 0.1

Emission Rate

Another important attribute is to define how many particles are spawned. These can be decided by three different attributes; you can only use one of them:

  • rate <float...>: The most common one, particles are constantly spawned at a certain rate which varies over time. When using this, you must use one of the options explained below as well.
  • inject <float>: All particles are injected once.
  • maintain <float>: Bursts of aprticles are emitted at the same time, and respawned when they die. This means that if all particles die at the same time, they will all be respawned at the same time.

(Note: The definitions aren't precise, they have options that give flexibility; for example, it is possible to obtain the inject effect by using rate and its options) (Note: Using rate without an option might crash the game)

Available options:

  • -loop <float: time> (<int: repetitions>): The emission rate is repeated after time seconds. If rate was used, the different rate values will be used through this time. It is possible to specify a second value, how many times this cycle is repeated; if not specified, it is repeated forever until the effect is manually killed. Cannot be used with maintain.

  • -delay <float: time> (<float>): Delays the initial spawn a certain amount of seconds. If two values are specified, then they are the range of possible times (e.g. 2 4 will mean a random time between 2 and 4 seconds).

  • -trigger <float: time> (<float>): Similar to -delay, but this affects all spawning of particles. If two values are specified, then they are the range of possible times (e.g. 2 4 will mean a random time between 2 and 4 seconds).

Other options, of unknown usage:

  • -single (<float>)
  • -sustain <float> (<int>)
  • -hold <float> (<int>)
  • -kill (<float>)
  • -speedScale <float>
  • -sizeScale
  • -areaScale
  • -volumeScale

Life Time

Particles might only live a limited amount of time, defined as the lifetime. Once that time passes, the particle disappears.

life <float> (<float>) -preroll <float>

The first value is the amount of seconds the particles lives. The second value (optional) is a variance so that particles live different amounts of time within a range.

For example, with this all particles will die between 4.5 and 5.5 seconds after they have spawned:

life 5.0 0.5

Texture/Model/Material

Another vital attribute: what is every particle? Particles can be three things: textures, models, or materials (quads affected by materials, to be precise). Each of these three correspond to one attribute; you can only use one of them.

texture <resourceID> -tile <int> (<int>) -overrideSet <int> -acceptComposite

The -tile option can be used for tiled textures, specifying how many rows and columns the texture has. This is used in animated textures.

All other options from texture slots are also supported.

Tiled textures only work for square tiled textures with the number of tiles on each edge a power of 2. So only 2x2, 4x4, 8x8, 16x16 tiles work.

model <resourceID> -material <resourceID> -overrideSet <int>

The resource ID is the name of the .prop file that defines the model. Optionally, you can specify the name of an effect material that will override the model's material.

material <resourceID> -overrideSet <int>

The particles will be a quad that uses the specified effect material.

All other options from texture slots are also supported.

Animated textures

If you are using the texture attribute, and your texture has tiles (so you are using the -tile option as well), it is possible to animate the texture like a 2D sprite. This is done with the following command:

frames -speed <float> -count <int> -start <int> -random <int>

With -count you specify how many tiles the animation lasts (which is usually number of rows * number of columns); -start can be used to specify which is the first tile (0, the first one, by default).

The tiles are used from left to right, top to bottom.

Additionally, the -speed need to be at least [the number of tiles used]/[life time] in order for all the textures to be loaded: -count/life. For example: if you're using 12 textures of the 16 available slots, and the particle life is 2 seconds, the -speed need to be at least 12/2=6

Forces

It is possible to affect particles with forces like gravity or wind, attraction around a point, etc. For more information, check the Effect Forces page page.

Surfaces

Particles can interact with surfaces, like water or the planet terrain. For more information, check the surface page.

Maps

Particles can have multiple effect maps that affect their behaviour. These features are untested, so the following is just their specification; any indications about what they do is pure speculation.

mapEmit <resourceID> -belowHeight <float> -aboveHeight <float> -heightRange <float: aboveHeight> <float: belowHeight> -pinToSurface -density

Probably used to define from which parts of the source particles are emitted. For example, a galaxy effect can be done by using an emit map with the shape of a galaxy, therefore emitting stars at specific locations.

mapCollide (<resourceID>) -pinToMap -bounce <float> -killOutsideMap -death <float>

This is incompatible with mapRepel, mapAdvect and mapForce.

The -death option is in the [0.0, 1.0] range, it specifies the probabilty of dying that particles have when colliding in the map.

The options -pinToMap and -bounce are exclusive (which is logical, since the particle will not bounce if it gets pinned to the map surface).

mapRepel (<resourceID>) <float: repulseHeight> <float: repulseStrength> -scout <float> -vertical <float> -killHeight <float> -killOutsideMap

This is incompatible with mapCollide, mapAdvect and mapForce.

mapAdvect <resourceID> -strength <float> -killOutsideMap

This is incompatible with mapCollide, mapRepel and mapForce.

mapForce <resourceID> -strength <float> -killOutsideMap

This is incompatible with mapRepel, mapAdvect and mapCollide.

Warp

It seems it applies some deformations to the particles.

warp -screw <float> -spiral <float> -wiggleDir <float: rate> <vector3: wiggleDirection> (<float3: rateDirection>) -bloomAlpha <float> <float> -bloomSize <float> <float>

For the -bloomAlpha and -bloomSize options, the first value is in the [0.0, 1.0] range and the second value is in the [0.0, 16.0] range.

Random/Directed Walk

randomWalk <float...> -delay <float> (<float: vary>) -strength <float> (<float: vary>) -turn <float: range> (<float: offset>) -mix <float> -wait

directedWalk -delay <float> (<float: vary>) -strength <float> (<float: vary>) -randomTurn <float: range> (<float: offset>) -mix <float> -sustain -loop -wait

Paths

It is possible to make particles follow a predefined path. This is done by accumulating one or multiple path attributes; each one represents a keyframe, a specific path point in time; the points in between will be interpolated.

path -p <vector3> -v <vector3> -s <float> -t <time> -dp <vector3> -dt <float>

The options are:

  • -p: The position.
  • -v: The velocity, for X, Y and Z directions. This is in units/second
  • -s: Speed; similar to velocity, but with same value for all directions.
  • -t: The time, in seconds, of this path step.
  • -dp: Delta position, used instead of -p to specify position relative to the last step.
  • -dt: Delta time, used instead of -t to specify time relative to the last step.

Paths are only used if the effect has physics unk2

Other options

align <enum>

How the particles are aligned; by default they are always facing the camera. This values are not tested, so the functionality described here is a guess and might not be the real one. One of the following values:

  • camera: The default one. The particles are always facing the camera.
  • ground: Always facing the ground.
  • source: Always facing the emission source.
  • dirX: Always facing the X direction (so they will be in the YZ plane).
  • dirY: Always facing the Y direction (so they will be in the XZ plane).
  • dirZ: Always facing the Z direction (so they will be in the XY plane).
  • zPole: Always facing the Z pole (i.e. the direction that goes through the south and north pole) of the planet.
  • sunPole: Always facing towards the sun.
  • cameraLocation: Always directed towards the camera location, but not necessarily facing the camera view.

loopBoxColor <colorRGB...>

loopBoxAlpha <float...>

physics <enum>

Sets the type of physics the particle has. One of the following values:

  • user1: ground cover physics
  • user2: ground cover circle physics
  • user3
  • user4
  • normal: Default, uses drag force when it's strong enough, or standard physics otherwise.
  • standard: Only uses standard physics, no path or drag force
  • path: Only uses the path defined in the particles

In planets, user1 is the coriolis effect, only available for cloud effects. user4 is the weather jet stream "writeForce".

Add a custom footer
Add a custom sidebar
Clone this wiki locally