This article contains information for Programmers working or interested in working for The Mana World

This article contains information for Artists working or interested in working for The Mana World

This article is for reference purpose

The features described in this article are already implemented in the game. The article should describe how a certain aspect of the game currently works. You may of course edit this article to improve the description of the circumstances. Your opinions or improvement suggestions about the described aspects themself are of course appreciated, too. But please put these on the discussion page of this article to keep facts and fiction separated.

What is the particle engine?

The particle engine is a system that allows to create beautiful dynamic special effects based on creating and managing a large number of small, independent, moving sprites. For more information about particle engines see the Wikipedia article about particle systems.

The particle engine allows us to create a large variety of beautiful special effects with minimal effort that could outclass those of most other sprite based rpgs. The areas where particle effects could be used include but are not limited to:

• Environmental effects like waterfalls, fires, fountains or smoke comming out of chimneys
• Visualisation of mystical phenomenons like teleporters or other points of interest
• Graphic effects for spells
• Visualisation of status effects

Implementation

The basic element of the particle engine is a special particle named "particleEngine". It maintains a tree of particle effects. Each particle has a position in three dimensional space (in this case the two dimensional game world is treated as a flat plane in a three dimensional space). Based on the type of particle it might or might not have:

• Movement based on physical properties
• A visual representation (a single image or an animation)
• A list of emitters that create additional particles.

The Particles are derived class from the "Sprite" class so that they can be added to the maps sprite list to be drawn together with the other sprites by the "map" class.

Creation of effects

Effects are created by calling particleEngine->addEffect(). The arguments are a particle effect definition file, the map coordinates (pixel-based) and the map on which the effect should be created. This creates a host particle that can have any number of emitters. The host particle is returned so it can be manipulated further. It is possible to create multiple host particles in one particle effect file. In that case only the last particle is returned.

Effects that follow beings

Beings can gain control of a particle. This happens by calling the controlParticle() member function of the Being class.

The usual method to create a particle that follows a being is by calling particleEngine->addEffect() and pass the returned particle to controlParticle().

Note that when a Being takes control of a particle it disables the automatic deletion of the particle. The being is now responsible for requesting the deletion of the particle by calling Particle::kill(). When it does the particle will be deleted after its next update.

Homing particles

A particle will be attracted by another particle when its acceleration is greater than 0. When a particle is created by an emitter the attracting particle is the host particle of the effect but it can be changed by calling Particle::setDestination(). I would always recommend to use a parent particle of the particle as a target because a segfault will occur when the target particle is deleted.

The effect definition file

The effect definition files are xml documents describing one or more single particles or particle emitters.

<effect>

Is the root element of the XML document.

<particle>

Every effect is based on at least one particle. Often but not always these root particles function only as emitters that spawn new particles and have no appearance of their own. They have the following three required properties:

position-x

(initial) position on map relative to the position where the effect is created (pixel-based)

position-y

(initial) position on map relative to the position where the effect is created (pixel-based)

position-z

(initial) position on map relative to the position where the effect is created (pixel-based)

The following properties are optional:

lifetime

Lifetime in game-ticks. (default: unlimited)

In addition they can have any number of emitters and a visual representation in form of an <animation> or an <image>.

<image>

Root particles can have an <image> childtag that contains the path to an image in its content. In that case this image is used as the visual representation of the root particle.

<emitter>

Emitters are always child-elements of a particle or another emitter. They create new particles themself which can also include emitters and so on. They also include a number of <property> child elements that define the initial properties of the created particles. When one of the following propertiy elements is missing the default value is used. The property elements have two or three properties. Either name and value or name, min and max.

They can also have any number of <emitter> childtags (when these exist all child-particles will be equipped with these emitters) and an <animation> childtag that replaces the image with an animation.

position-x

(initial) position on map relative to the parent particle (pixel-based) (default: 0)

position-y

(initial) position on map relative to the parent particle (pixel-based) (default: 0)

position-z

(initial) position on map relative to the parent particle (pixel-based) (default: 0)

image

path to the image that should be drawn at the position of the particles (default: no image)

horizontal-angle

clockwise angle of initial vector on horizontal plane in degree. 0° means straight right. (default: 0)

vertical-angle

angle between ground and initial vector in degree. 0° means parallel to the ground. Positive values are upwards, negative downwards. (default: 0 = parallel to ground)

power

Initial speed of the particles in pixels/ game-tick (default: 0)

gravity

Downward acceleration of particles in pixels/game-tick² (default: 0)

randomnes

Random changes in the X, Y and Z vector. The unit is maximum pixels/game-tick/1000. (default: 0)

lifetime

lifetime in game ticks (default: -1 = unlimited)

fade-out

Number of game ticks of lifetime left when the particle starts to disappear by fading into alpha. (default: 0 = disabled)

fade-in

Number of game ticks while the particles fade in to their full opacity. (default: 0 = spawned with full opacity)

output

Numbers of particles created per tick (default: 1)

acceleration

acceleration of particles towards the target in pixels/game-tick² (default: 0)

momentum

Momentum of the particles. Before adding the acceleration the old vectors are multiplied by this. A momentum of 1 creates a perfect newtonian object. A slightly lower momentum gives the impression that the particles are breaked. A higher momentum makes the particles accelerate forward. This looks rather weird but could be useful for some effects. A negative momentum looks really ugly. (default: 1)

die-distance

Only used together with acceleration. Distance in pixels to the target that causes the destruction of the particles when reached. (Default: 0 = not destroyed on contact)

bounce

When higher than 0 particles don't disappear when they touch the ground. Instead they bounce off with a vector equal to their old vector multiplied with this property. It is recommended to add a limited lifetime to bouncing particles because otherwise they are immortal. (Default: 0)

<animation>

The animation tag can be used as a childtag of the <particle> tag to make the root particle appear as an animated image or it can be used as a childtag for an emitter. In that case the emitter cspawn animated particles instead of a static ones.

The usage is similar like the animation tag described in Animations#.3Canimation.3E. You can use the same child elements with the same syntax. The only difference are the properties of the animation tag itself. There is no direction property. Instead the used imageset is described in the animation tag with the properties imageset, width and height. All three properties are required.

Particle engine related config setting

particleFastPhysics

Replaces the cpu intense squareroot calculations for calculating the vectors of target-based particles by less intense but less accurate calculations. 0 uses the slow but accurate and reliable function from the C standard library. Setting it to 1 uses a squareroot approximation function that is much faster while being only slightly less accurate but doesn't work on some architectures. 2 is an even faster method that shouldn't have any portability problems but it is very inaccurate. Default: 0

particleMaxCount

Maximum number of particles in the game world. When this limit is reached no new particles will be spawned by emitters until some particles disappeared. This limit is only respected by emitters and not when spawning new effects to make sure that they are spawned when the particle limit is maxed out.

When the limit is maxed out the result is a quite unregular output of the particle emitters that looks quite ugly. So this situation should be avoided. The main reason this setting exists is to encourage the particle effect creators to keep the particle output of their emitters on a reasonable level and to keep the game playable in unusual particle-intense situations by accepting a glitchy appearance of the particle effects in this cases.

Please note that a few very large particles can reduce the framerate more than a lot of very small particles.

Default: 3000

particleEmitterSkip

The number of game ticks each emitter is inactive between two particle spawns. Setting this to a higher value keeps the numbers of particles down by reducing the output of the emitters.

This is a more useful way for the user to reduce the particle count than reducing particleMaxCount because it doesn't change the look of particle effects that much.

Default: 0

Current problems and limitations

Crush, I see the particles surrounding the player got across the wall because those tiles aren't marked as above the player. This happens in every map, I think. The solution would be to put the problematic a level up. This is not a limitation on the engine actually, but something that has to be fixed before committing to trunk. Unless you had something better in mind.

This can't be fixed that easily. The particles have to be drawn on the object layer so that they can be sorted with the other objects. Also note that it is usually the desired behavior that objects on the over layer are drawn over particles on the sprite layer. As a workaround i would suggest to use more thorough mapping in the future. That means to fill "empty" areas with black tiles on layer 2 instead of black tiles on the ground layer and to map cliffs that are clearly on the upper layer on layer 2.--Crush 21:58, 9 February 2007 (CET)

I know. But it's still a problem. My intention was to bring it to light before the engine is merged to trunk and used extensively. --Pajarico 13:23, 10 February 2007 (CET)

Second, the snow makes a weird effect when it goes beyond the tiles. I guess we won't have snow inside a cave in the final version :P but particles that got to far will get to the no-tiles area. What do you suggest? covering everything with black tiles? --Pajarico 21:22, 9 February 2007 (CET)

The area outside of the map appears buggy in any case. That has nothing to do with the particle engine. --Crush 21:58, 9 February 2007 (CET)

The end-of-map bug has been fixed in the 0.0.22.2 version. --Crush 19:30, 10 February 2007 (CET)