GDX Particle Editor is the new tool for creating particle effects. This replaces the classic editor which is now deprecated. See the video and documentation below.
Running GDX Particle Editor
Download the JAR release of GDX Particle Editor here
Consult the GDX Particle Editor wiki on how to run the JAR file if you are having difficulty. This may be important for M1 Mac users who have security restrictions that block the editor from opening files.
Using the Particle Editor
See GDX Particle Editor on YouTube:
The in-depth documentation is also available in text on the wiki as well.
Briefly, a particle effect consists of some images that are moved around. The images usually use additive blending and some pretty stunning results can be produced with only a few images. Particle effects are good for fire, explosions, smoke, etc. Each particle has many properties that control how it behaves: life, velocity, rotation, scale, etc. The particle editor allows you to manipulate these properties and observe the result in real time. You can also create effects programmatically, but it is much more difficult and time consuming to create great effects.
The first step to creating an effect is to choose an image. The default image is just a simple round gradient. Experiment with different images to create a wide variety of effects. Images will often combine for some surprising and sometimes very cool looking results.
When you are configuring properties, you are actually configuring the particle emitter that will create and manage the particles. In code, the emitter is represented by the ParticleEmitter class. A particle effect is made up of one or more emitters, which is managed in the lower left of the particle editor. In code, the effect is represented by the ParticleEffect class, which has a list of ParticleEmitters.
Properties Panel Elements
There are some common elements that appear in several of the properties panels.
Active button
Properties with an “Active” toggle button can be turned off, which can minimize some of the work that needs to be done at run-time.
Number / number range
Some of the number fields have a > button beside them. Clicking this button changes the number into a number range, where at runtime, a random value is selected from between the two specified values, every time the number is referenced. For example, if a range of 1-2 is selected for the Life property, each new particle will have some random length life between 1 and 2 seconds.
Graph
A graph is used to control the value of a property over time. The word “Duration” or “Life” in the middle of the graph indicates whether the horizontal timeline of the graph is relative to the duration of the emitter, or the lifetime of each single particle.
The “High” and “Low” number fields indicate the values that correspond with the top and bottom of the graph. Like other number fields, they can be expanded into a range with the > button. The random number in the range is chosen when the effect starts for a “Duration” graph, and when a particle is spawned for a “Life” graph.
Within the graph itself:
- To add nodes, click anywhere in the graph.
- To move nodes, click and drag an existing node.
- To delete a node, right-click or double-click it.
The + button expands the graph for fine-tuning.
The “Relative” checkbox. When unchecked, the value at any one point in time for the property will be what the graph shows. When checked, the value shown on the graph is added to the initial value of the property. Why? Imagine you have rotation set to start at 0 and go to 360 degrees over the life of a particle. This is nice, but all the particles start at the same zero rotation, so you change the “Low” value to start between 0 and 360. Now your particles will start between 0 and 360, and rotate to exactly 360 degrees. If a particle spawns at 330 degrees, it will only rotate 30 degrees. Now, if you check “Relative”, a particle that spawns at 330 degrees will rotate to 330 + 360 degrees, which is probably what you want in this case.
Finally, the “Independent” checkbox. Some properties allow switching how the graph controls the property over time from emitter to single/independent particle. Let’s imagine that we have a graph with ranged values defined on the “Life” property. By default the graph affects the emitter as a whole. Each time the emitter generates particles, a random value within the appropriate range for that time will be chosen and all emited particles will have that value set as life. On the other hand, if “Independent” is checked, a new random value will be calculated per emitted particle and set as life to each of them independently.
Properties
Delay: When an effect starts, this emitter will do nothing for this many milliseconds. This can be used to synchronize multiple emitters.
Duration: How long the emitter will emit particles. Note this is not the same as how long particles will live.
Count: Controls the minimum number of particles that must always exist, and the maximum number of particles that can possibly exist. The minimum is nice for making sure particles are always visible, and the maximum lets the emitter know how much memory to allocate.
Emission: How many particles will be emitted per second.
Life: How long a single particle will live.
Life Offset: How much life is used up when a particle spawns. The particle is still moved/rotated/etc for the portion of its life that is used up. This allows particles to spawn, eg, halfway through their life.
X Offset and Y Offset: The amount in pixels to offset where particles spawn.
Spawn: The shape used to spawn particles: point, line, square, or ellipse. Ellipse has additional settings.
Spawn Width and Spawn Height: Controls the size of the spawn shape.
Size: The size of the particle.
Velocity: The speed of the particle.
Angle: The direction the particle travels. Not very useful if velocity is not active.
Rotation: The rotation of the particle.
Wind and Gravity: The x-axis or y-axis force to apply to particles, in pixels per second.
Tint: The particle color. Click the little triangle and then use the sliders to change the color. Click in the bar above the triangle to add more triangles. This allows you to make particles change to any number of colors over their lifetime. Click and drag to move a triangle (if it isn’t at the start or end). Double-click to delete.
Transparency: Controls the alpha of the particle. This graph is different than the others because you cannot modify its vertical range. It is always from 0 to 1.
Options
- Additive: For additive blending.
- Pre-multiplied alpha: For pre-multiplied alpha blending, which enables a mixture of alpha and additive blending. If this is selected, the Additive option is ignored.
- Attached: Means existing particles will move when the emitter moves.
- Continuous: Means the emitter restarts as soon as its duration expires. Note that this means an effect will never end, so other emitters in the effect that are not continuous will never restart.
- Aligned: The angle of a particle is added to the rotation. This allows you to align the particle image to the direction of travel.
You can activate the statistics label by clicking the settings button in the preview area and choosing “Statistics enabled”. “Count” shows how many particles exist for the currently selected emitter. “Max” shows how many particles exist for all emitters over the past few seconds. Below that is a percentage that represents the duration percent of the currently selected emitter.
Effect settings saved with the particle editor are written to a text file, which can be loaded into a ParticleEffect instance in your game. The ParticleEffect can load images from a directory, or a TextureAtlas. Of course, a TextureAtlas is recommended and can easily be made with the TexturePacker.
Most effects can be simplified to use just a few images. Most complex effects that use 4 or more emitters typically only need 15 or so total particles alive at once. See ParticleEmitterTest in gdx-tests if you’d like to test how many particles your device can handle. However, the performance varies greatly with the particle image size.