Meta Particles (Effects) - emd4600/SporeModder-FX GitHub Wiki

Meta particles are very similar to particles, but instead of emitting images they emit entire effect components. Most attributes are the same, but there are some significant differences:

• Instead of using texture, model, or material, meta particles use effect to reference the effect component that will be emitted.
• Rotation is 3D, so instead of rotate meta particles have yaw, roll, pitch
• There is no aspect, stretch, frames, physics attributes.
• There can be two randomWalk/directedWalk attributes.
• There are some extra attributes: flags, globalForcesSum, randomWalkPreferredDir, field_12C, tractorResetSpeed, damping.

Note: if you want to move your effects properly, especially with the yaw/roll/pitch 3D rotation, you need to assign -flags 0x40 to it. -flags 0x40 is used very widely in effects to lock the frame of reference to another object/effect.

Keyword: metaParticles

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

The color applied to the particles, a tint applied to the effect; 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.

pitch <float...> -vary <float> -offset <float> roll <float...> -vary <float> -offset <float> yaw <float...> -vary <float> -offset <float>

The 3D 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; pitch, roll and yaw rotate around the X, Y and Z axes, respectively. 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.

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)

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

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
• -sizeScale
• -areaScale
• -volumeScale

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

Another vital attribute: what is every meta particle? Unlike particles, meta particles can only emit effect components. Optionally, they can also spawn an effect for when the particle dies.

effect <effect> -death <effect>

The component must have been declared before the meta particles, in the same .pfx file; it does not need to be exported.

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.

Additionally, meta particles have this property, of unknown usage:

globalForcesSum <vector3>

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

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.

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.

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

randomWalkPreferredDir <vector3>

Unlike particles, meta particles can have two randomWalk/directedWalk attributes.

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.

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

flags <bitfield>

field_12C <int>

tractorResetSpeed <float>

damping -align <float> -bank <float: amount> <float: damping>