Editing XML/Unit particle

Uunit particles are particles, emitted from the unit itself. [[Particles]] have a lifecycle. They are born with <tt>energy-max</tt> and they die with when <tt>energy</tt> is zero. With every step their energy is lowered by one. A unit particle system currently can control 200 particles. If the particle system has a high emission rate and you would get more than 200 alive particles the ones with the lowest energy are recycled and used as new ones.


==XML==
<syntaxhighlight lang="xml">
<?xml version="1.0" standalone="yes"?>
<unit-particle-system>
	<texture value="true" path="images/particle.bmp" luminance="true" />
	<primitive value="quad" />
	<mode value="normal" />
	<offset x="0" y="-0.4" z="0.0" />
	<direction x="0" y="1" z="0" />
	<color red="1.0" green="0.0" blue="0.0" alpha="0.8" />
	<color-no-energy red="1.0" green="1.0" blue="0.3" alpha="0.6" />
	<size value="0.6" />
	<size-no-energy value="0.3" />
	<radius value="0.7" />
	<speed value="3.0" />
	<gravity value="0"/>
	<emission-rate value="10" />
	<energy-max value="30" />
	<energy-var value="0" />
	<fixed value="false" />
	<relativeDirection value="false" />
	<relative value="true" />
	<teamcolorEnergy value="false" />
	<teamcolorNoEnergy value="false" />
	<static-particle-count value="4" />
        <alternations value="1" />
	<isVisibleAtNight value="false" />
	<isVisibleAtDay value="true" />
	<radiusBasedStartenergy value="false" />
	<isDaylightAffected value="false" />
	<particleSystemStartDelay value="0" />
    <meshName value="plane.001"/>
	<shape value="conical">
		<angle value="30"/>
	</shape>
</unit-particle-system>
</syntaxhighlight>

==Documentation==
[[File:Luminance.png|thumb|Comparison of luminance on and off, using the texture at the top-right corner.]]
===textures===
Particles can use textures to shape how the particles should look. If luminance is turned on, the image file used as a texture will simply work to define the intensity of the colors. If luminance is turned off, the colors in the image file will be used in the particle.

===primitive===
Particles have two methods of creation: either quad (renders a set of four particles in a dot style) or line (creates solid lines). Quad is the most commonly used, as it creates the fuzzy style of particles that would be used for flames, explosions, smoke, etc, while lines are generally only used for projectiles such as an arrow. Note that you cannot have more than one particle effect linked to a projectile or splash (though you can for unit particle effects) yet, so it is not possible to mix particles (such as a line and flaming particles for a flaming arrow).

===mode===
Particles have two modes of rendering, either normal which uses colors, or as black which allows the usage of black particles.

===offset===
The offset from the center of the unit to where the center of the particle system will be, in Glest units.<br>
Since MegaGlest 3.1.10 you can give positions based on the ground ( which is highly recommanded ) and not the units center.
{{See|XML/Faction#flat-particle-positions}}

===direction===
The direction for particles to move in, in Glest units. Y, for example, would be straight up, while X and Z would be the ground, as a grid.

===color and colorNoEnergy===
If luminance is off, the colors of the texture will be used to color the particles. If luminance is on, the colors defined in the XML are used, though the intensity and shape will be defined by the texture. There are two colors values, the first which is the color at the start of the particle's life, and the second which defines the color when the particle is dead. Thus, the particles can transition in color.

===size and sizeNoEnergy===
While the shape - and thus some degree of the size - is defined by the texture, the size is also affected by the size parameter passed into the XML, which will define the size in game units. Like the color, there are two size values that define the starting and ending sizes. As a result, the particles can seem to shrink or grow over their life.

===radius===
Whereas size affects the particle's individual size, radius affects the area filled with particles.

===speed===
Speed the particles will travel at. Used in combination with direction to cover that much distance over the life of the particle.

===gravity===
Glest has a simple gravity system which can also cause particles to sink downwards - or float upwards - over their life.

===emission-rate===
The number of individual particles that are emitted per frame. Its a float value (decimals are allowed). If the number is a float, say, 0.1, that would mean it would be emitting one particle per ten frames.

===energy-max===
The starting energy of the particles.

===energy-var===
A variance to add or subtract from energy-max to make particles more random.

===fixed===
If true, the position of the particle system moves with the unit. If false, it could be left "behind" until it dies, such as with dust or smoke.

===relativeDirection===
If true, the direction changes with the unit too. Some things like smoke blowing in the wind would want this to be false, to ensure the particles always go in the same direction.

===relative===
If true, the position of the particles (but not the direction) will rotate with the unit. This prevents problems like smoke that comes from a chimney no longer being over the chimney when rotating buildings.

===teamcolorEnergy and teamcolorNoEnergy===
If true, color or color-no-energy will be replaced with the unit's team color.

===static-particle-count===
If this optional tag appears, the specified number of static particles will be used. A static particle is a particle that does not move or die. Instead, they alternate between their size and their size-no-energy and their color and color-no-energy. Because they do not move, direction, gravity, etc won't have any affect on the particles. These are mostly used for a glow effect. To "hide" the alternation of the regular and the no-energy variations, simply make the regular and no-energy values the same.

===alternations===
If this optional tag appears, the particles alternates n times from low energy to high energy. So it starts and ends with its low energy values.

===isVisibleAtNight===
With this optional Tag you can tell a particle system to be shown at night. If true, will be visible at during the night, and if false, will not be visible at night. Defaults to true. Useful for making artificial lights at night.

===isVisibleAtDay===
With this optional Tag you can tell a particle system to be shown at day. If true, will be visible at during the day, and if false, will not be visible at day. Defaults to true.

===radiusBasedStartenergy===
If this is enabled the particles in the center start with higher energy then those which are more on the outside. This is typically used for fire effects.

===isDaylightAffected===
If set to true, the tilesets day/night light coloring of the current moment affects the particle colors (meant to be used with mode "black"). By this the coloring of the particles fits to the daytime. Defaults to false. 

===particleSystemStartDelay===
This delays the start by the given number of particle system update cycles (integer). Default is 0.

===shape===
Let the Particles form a cone, sphere or line (spherical,conical,linear). If you use "conical" the shape needs a child named angle. This means how wide the cone is open. It can be greater than 90. Sadly the direction does not work for the cone.

===meshName===
Bind the particle system to a mesh with this name in the model. More details see here: [[MeshBoundUnitParticles]]

==See Also==
*[[Particles]]
*[[MegaGlest]]
*[[XMLs]]
*[[GAE]]
[[Category:XMLs]]