| 1 | = Particle file format = |
| 2 | |
| 3 | Particle effects are specified with an XML file, stored in `binaries/data/mods/public/art/particles/`. |
| 4 | |
| 5 | A typical particle effect file looks like: |
| 6 | {{{ |
| 7 | <?xml version="1.0" encoding="utf-8"?> |
| 8 | <particles> |
| 9 | |
| 10 | <texture>art/textures/particles/flame.png</texture> |
| 11 | <blend mode="add"/> |
| 12 | |
| 13 | <!-- Parameters: --> |
| 14 | |
| 15 | <constant name="emissionrate" value="20.0"/> |
| 16 | |
| 17 | <uniform name="lifetime" min="1.0" max="1.5"/> |
| 18 | |
| 19 | <uniform name="position.x" min="-8.0" max="8.0"/> |
| 20 | <uniform name="position.z" min="-8.0" max="8.0"/> |
| 21 | <constant name="position.y" value="0.0"/> |
| 22 | |
| 23 | <uniform name="angle" min="-0.5" max="0.5"/> |
| 24 | |
| 25 | <uniform name="velocity.x" min="-0.3" max="0.3"/> |
| 26 | <uniform name="velocity.y" min="2.0" max="2.5"/> |
| 27 | <uniform name="velocity.z" min="-0.3" max="0.3"/> |
| 28 | <uniform name="velocity.angle" min="-0.5" max="0.5"/> |
| 29 | |
| 30 | <uniform name="size" min="1.0" max="2.0"/> |
| 31 | |
| 32 | <uniform name="color.r" min="0.8" max="1.0"/> |
| 33 | <copy name="color.g" from="color.r"/> |
| 34 | <copy name="color.b" from="color.r"/> |
| 35 | |
| 36 | <!-- Effectors: --> |
| 37 | |
| 38 | <force y="-2.5"/> |
| 39 | |
| 40 | </particles> |
| 41 | }}} |
| 42 | |
| 43 | 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: |
| 44 | '''`add`''':: |
| 45 | The RGB colour of the texture is added to the background. Useful for bright effects e.g. flames. |
| 46 | '''`subtract`''':: |
| 47 | The RGB colour of the texture is subtracted from the background. |
| 48 | '''`multiply`''':: |
| 49 | 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). |
| 50 | '''`over`''':: |
| 51 | 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. |
| 52 | |
| 53 | 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. |
| 54 | |
| 55 | The available parameters are: |
| 56 | * '''`emissionrate`''' - number of particles per second that will be emitted. |
| 57 | * '''`lifetime`''' - number of seconds before the particle disappears. |
| 58 | * '''`position.x`''' - initial position of particle relative to the emitter point. |
| 59 | * '''`position.y`''' - initial position (Y axis is vertical). |
| 60 | * '''`position.z`''' - initial position. |
| 61 | * '''`angle`''' - initial rotation of sprite (they always face the camera but can rotate around one axis), in radians (6.28 radians = 360 degrees). |
| 62 | * '''`velocity.x`''' - initial speed in metres per second. |
| 63 | * '''`velocity.y`''' |
| 64 | * '''`velocity.z`''' |
| 65 | * '''`velocity.angle`''' - rotation speed in radians per second. |
| 66 | * '''`size`''' - size in metres. |
| 67 | * '''`color.r`''' - colour, which will be multiplied by the RGB of the texture. |
| 68 | * '''`color.g`''' |
| 69 | * '''`color.b`''' |