Particle file format

Particle effects are specified with an XML file, stored in binaries/data/mods/public/art/particles/.

A typical particle effect file looks like:

<?xml version="1.0" encoding="utf-8"?>
<particles>

    <texture>art/textures/particles/flame.png</texture>
    <blend mode="add"/>

    <!-- Parameters: -->

    <constant name="emissionrate" value="20.0"/>

    <uniform name="lifetime" min="1.0" max="1.5"/>

    <uniform name="position.x" min="-8.0" max="8.0"/>
    <uniform name="position.z" min="-8.0" max="8.0"/>
    <constant name="position.y" value="0.0"/>

    <uniform name="angle" min="-0.5" max="0.5"/>

    <uniform name="velocity.x" min="-0.3" max="0.3"/>
    <uniform name="velocity.y" min="2.0" max="2.5"/>
    <uniform name="velocity.z" min="-0.3" max="0.3"/>
    <uniform name="velocity.angle" min="-0.5" max="0.5"/>

    <uniform name="size" min="1.0" max="2.0"/>

    <uniform name="color.r" min="0.8" max="1.0"/>
    <copy name="color.g" from="color.r"/>
    <copy name="color.b" from="color.r"/>

    <!-- Effectors: -->

    <force y="-2.5"/>

</particles>

All effect files must specify a texture and blend mode. The blend mode controls how each particle is drawn on top of the background, and is one of the following:

add

The RGB colour of the texture is added to the background. Useful for bright effects e.g. flames.

subtract

The RGB colour of the texture is subtracted from the background.

multiply

The RGB colour of the texture is multiplied from the background. (Colours are interpreted as fractions in the range 0 to 1, so this will always make things darker).

over

The RGB colour of the texture is drawn over the background, with transparency determined by the alpha channel. This is useful for more solid-looking particles, but may introduce visible glitches when particles are drawn over nearer particles, so it should be tested carefully from all angles.

The main part of the effect file is specifying initial particle parameters. Every time a new particle is created by the particle emitter, its state is determined by these parameters.

The available parameters are:

• emissionrate - number of particles per second that will be emitted.
• lifetime - number of seconds before the particle disappears.
• position.x - initial position of particle relative to the emitter point.
• position.y - initial position (Y axis is vertical).
• position.z - initial position.
• angle - initial rotation of sprite (they always face the camera but can rotate around one axis), in radians (6.28 radians = 360 degrees).
• velocity.x - initial speed in metres per second.
• velocity.y
• velocity.z
• velocity.angle - rotation speed in radians per second.
• size - size in metres.
• color.r - colour, which will be multiplied by the RGB of the texture.
• color.g
• color.b