particle city

Before coming to libgdx, I had been working on my own similar project, Skorpios. One of the unique things I had was a particle editor that allowed for particle effects to be easily designed. I’ve ported it to libgdx, and you can check it out via JWS by clicking this image:

Particle Editor

Real quick, 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 right of the particle editor. In code, the effect is represented by the ParticleEffect class, which has a list of ParticleEmitters. Most of emitter properties are self explanatory, but I will run through them quickly.

Delay: When an effect starts, this emitter will do nothing for this many milliseconds. This can be used to synchronize multiple emitters.

Note the delay property has an “Active” button. Some properties can be turned off, which can minimize some of the work that needs to be done at runtime.

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.

Emission is the first property with a little chart, but all properties with a chart work the same way. Click on the chart to add nodes, click and drag to move nodes, and double click to delete nodes. The chart allows you to vary the value of the property over time. Note that the chart says “Duration” in the center. This means the x-axis represents the duration of the emitter (which of course is set with the duration property). Other charts may say “Life”, which means the x-axis represents the life of a single particle. The top of the y-axis represents the value specified for “High” and the bottom of the y-axis represents the value specified for “Low”. The chart can be expanded with the “+” button for a larger view.

The “High” and “Low” values each have a button marked “>”. When clicked, this will expand to show a second text box. A random number (float) is chosen between the text box on the left and the one on the right. The number is chosen when the effect starts for a “Duration” chart, and when a particle is spawned for a “Life” chart.

Finally, the last piece of functionality for charts is the “Relative” checkbox. When unchecked, the value at any one point in time for the property will be what the chart shows. When checked, the value shown on the chart 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.

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.

Options, Additive: For additive blending.
Options, Attached: Means existing particles will move when the emitter moves.
Options, 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.
Options, Aligned: The angle of a particle is added to the rotation. This allows you to align the particle image to the direction of travel.

In the upper left of the particle editor, “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 SpriteSheet. Of course, a SpriteSheet is recommended and can easily be made with the SpriteSheetPacker.

Most effects can be simplified to use just a few images. My most complex effects that use 4 or more emitters typically only need 15 or so total particles alive at once. My crappy Droid can render 250 32×32 blended particles at 46 fos, 500 particles at 36 fps, and 1000 particles at 26 fps (see ParticleEmitterTest in gdx-tests). However, the performance varies greatly with the particle image size.


Libgdx Roadmap for the coming weeks

I just had a little convo with Nate, now the second project owner overlord. Here’s our plan of attack for the coming weeks:

libgdx 0.81, tbr this weekend if all goes well

  • includes bug fixes for the bugs we kindly introduced while doing our huge refactoring run for 0.8. All is stable and working nicely again.
  • includes the extensions (twl backend, lwjgl backend). The later is still marked as experimental but should work without problems. Nate uses it exclusively as he hates Jogl. Silly Nate. Note that textures are not premultiplied with alpha and mipmaps look bad at the moment.
  • integration of extensions in nightlies

things planned for post 0.81 nightlies this weekend

  • Fix the licensing issues with the content on the Wiki as well as the content of the assets used in the tests
  • Fix the license headers of the new files we added. Should add that to the formater :/
  • Fix a mysterious bug related to vertex arrays on the desktop in Nate’s game. Couldn’t reproduce this so far. It’s probably Nate’s shitty code :p
  • Replace the Java Sound backend with an OpenAL backend on the desktop
  • Look into 64-bit support on windows. Gonna need to write makefiles as mingw64 doesn’t work with cdt :/
  • Get back to pirato and make him a contributor so he can build the MacOS natives for us. I’m afraid i will never buy a Mac and get a “developer license” just to build a single native. (Sponsorship welcome though. Send me your old crappy Mac minis :p)
  • Add fullscreen support for the Jogl and Lwjgl backend. It’s just a couple of lines…

things planned until the end of this year

  • Add a silly animated Sprite class so we can let Super Mario move over the screen animated…
  • Wait for the guys over at the forums to come up with the best tile map rendering solution 🙂
  • Rewrite the OBJ loader, it sucks
  • Write loaders for other common formats
  • Write tools to bake skeletal animation to keyframed animation. More memory overhead but better performance
  • Introduce a material system that works with fixed function and shader pipelines. I’m aware that this is no easy task and need a lot of consideration. We’ll try to accumulate all the knowledge stored in engines such as Ogre3D and Ardor3d. That’s gonna take a while
  • Rework the math package, rewrite some methods in native code (triangle soup vs ray/segment/bbox/sphere
  • Maybe add a couple of spatial partitioning schemes
  • Add a lightweight 3D scene graph in the spirit of the 2D scene graph. No bells and whistles. This will not be JME or Ardor3D (which i start to like a lot reading the sources)

Oh my, that list is bigger than i thought :/ But i think we have a pretty nice package already and the above addition will make it even more valuable. I have a good idea to get an instant boost for our 3D stuff. Involves some collaboration. We’ll see how that works out.

I’ll be on vacation for half of december so i think i can get most of the above working within the time frame. I also have to write that silly book which takes considerable time, so we’ll see how that works out.

Word Zen, an awesome puzzler written with libgdx!

I just got word from Lih-Hern aka Lf3T-Hn4D that he and his team released their first game called Word Zen. It’s an awesome word puzzler were you have to swipe paths through an alphabet soup to create words. The game is insanenly polished and works exceptionally well on all my devices, except for the hero as that’s still on 1.5 for testing. Oh, and did i mention it is fun too? This is the second game on the market that not just uses the Box2D wrapper but all of libgdx. Maybe i can talk Lih-Hern into writting up a small technical post mortem for us. Here’s a screen shot which doesn’t do the game justice. There’s a lot of things going on during game play so check it out on the market!

And here’s the obligatory clickable QR code:

You can find out more about Word Zen on the Liquid Rock Games website. Keep up the great work guys and get out more games!