Creating a simple particle effect using the Stardust Particle Engine

Standard

The Stardust Particle Engine is a great new addition to that long list of open source AS3 projects out there on the web. While Stardust can look like a fairly complex system to get started with, this tutorial will hopefully show you how to setup a simple particle effect using the library and give you enough understanding of how it works to start making your own effects as well.

Stardust has a lot of cool features, and much of its structure and functionality will be familiar to people who have already used the Flint particle effects library or the Box2DFlash physics engine.

What makes this engine different is the way it brings all these features together in a modular and well designed package. It supports 2D and 3D particle effects (via its own internal 3D engine and through plugins for Papervision3D, ZedBox or ND3D), particle masking to help create more complex logic, and even the option to configure your effects using external XML files.

In addition to this great list of features is an excellent set of documentation, a nice introductory user guide, lots of really good code examples and even some FlashDevelop class templates that make it much easier to extend the core classes for your own effects. All of these extras are available from the links on the Stardust project home page.

So anyway, on with the tutorial, what we’re going to do is create a very simple multi-coloured smoke effect that will follow the mouse around the screen. It’s nothing too amazing I guess, but hopefully it will work as an intro on how to get started using the Stardust particle effects engine.

After downloading the Stardust source code from Google Code, start a new project in your favorite Flash / ActionScript IDE, set the background colour to black, the frame rate to 30 fps and make sure the Stardust class package or SWC is added to your new project’s class path.

First off, open your project’s main document class and import the following classes, it may look like a lot of code, but this is mainly due to the object oriented structure that makes Stardust so great at creating complex effects.

import flash.display.Sprite;
import flash.events.Event;
import idv.cjcat.stardust.twoD.initializers.DisplayObjectClass;
import idv.cjcat.stardust.twoD.initializers.Position;
import idv.cjcat.stardust.twoD.initializers.Velocity;
import idv.cjcat.stardust.twoD.renderers.DisplayObjectRenderer;
import idv.cjcat.stardust.twoD.emitters.Emitter2D;
import idv.cjcat.stardust.twoD.actions.Move;
import idv.cjcat.stardust.twoD.zones.CircleZone;
import idv.cjcat.stardust.twoD.zones.SinglePoint;
import idv.cjcat.stardust.common.clocks.SteadyClock;
import idv.cjcat.stardust.common.actions.Age;
import idv.cjcat.stardust.common.actions.DeathLife;
import idv.cjcat.stardust.common.initializers.Life;
import idv.cjcat.stardust.common.math.UniformRandom;

Next we need to add a few class properties to the document class. First is the emitter, this is the part of the particle engine that creates the particles, next is the renderer which actually draws the particles on to the display list, lastly there is an instance of SinglePoint, which is just a reference that we will be using to determine where the particles should appear on screen.

private var emitter:Emitter2D;
private var renderer:DisplayObjectRenderer;
private var point:SinglePoint;

Next in the document class constructor add the following lines of code, we will go through them a couple of lines at a time.

emitter = new Emitter2D(new SteadyClock(4));

This creates a new particle emitter and tells it to add new particles to the system at a steady rate of 4 particles each time the emitter.step() method is called.

emitter.addInitializer(new DisplayObjectClass(DemoParticle));
emitter.addInitializer(new Velocity(new CircleZone(0,0,4)));
emitter.addInitializer(new Life(new UniformRandom(20,60)));

These lines add some initial settings that will be applied to every particle that is created by the  emitter. The first line sets what graphics to use for the particles, in this case it is a class called DemoParticle which we will look at a bit later on towards the end of this tutorial.

The next line sets the starting velocity of each particle and the third line sets the life time that each particle will have. It’s important to note here that the two classes used for the Velocity and Life settings (CircleZone and UniformRandom respectively), are actually ways of describing a range of possible values rather than one specific value. This is a core part of how this particle system works, building up complex effects using random values chosen from within a specified range.

point = new SinglePoint(mouseX, mouseY);
emitter.addInitializer(new Position(point));

Here we create an instance of the SinglePoint class and use it to store a reference to the location of the particle emitter. We will update this value later on every frame to make the particle effect follow the mouse.

Now we add some actions. While the initializers above declared the initial settings that each particle will use when first created, these actions will determine how those initial settings are changed over time.

emitter.addAction(new Age());
emitter.addAction(new Move());
emitter.addAction(new DeathLife());

The Age action reduces the life of the particle over time, the Move action makes the particle move based on its velocity and the DeathLife action tells the engine to remove each particle from the display list after its lifetime has completed.

Next we create a renderer, then add the emitter to it and tell it to draw the graphics for the particle effect into a container DisplayObject. In this case we are using the document class as the container but you could use any Sprite or MovieClip you like.

renderer = new DisplayObjectRenderer(this);
renderer.addEmitter(emitter);

Finally we need to add a listener for the ENTER_FRAME event and create a function to handle the event called renderLoop.

addEventListener(Event.ENTER_FRAME, renderLoop);

Inside the renderLoop function we add the following code.

point.x = mouseX;
point.y = mouseY;
emitter.step();

This code does two things, first it sets the x and y properties of the SinglePoint instance to match the current mouse position, this will automatically update the position of the particle effect. Then it tells the engine to update the particle effect based on all the settings we set up in the code above by calling the step() method.

Now that’s all the code needed for this class, but there is one last thing we need to do, if you remember earlier on we told the particle system to use a class called DemoParticle to draw the graphics of each particle, so now we have to write that class.

Add a new ActionScript file to the same directory as your document class, save it as DemoParticle.as and paste the following code into it. This class simply draws a small blurred circle using a random colour and size. This will be used to provide the graphics for each new particle that is drawn by the particle engine.

package
{
  import flash.display.Sprite;
  import flash.events.Event;
  import flash.filters.BlurFilter;
  public class DemoParticle extends Sprite
  {
    private static const COLOURS:Array = [0x9F67FE, 0x6B6BFE, 0x5BBAFF];
    public function DemoParticle()
    {
      this.filters = [new BlurFilter(32,32,3)];
      graphics.beginFill(COLOURS[Math.floor(Math.random()*COLOURS.length)]);
      graphics.drawCircle(0, 0, 8 + Math.floor(8*Math.random()));
      graphics.endFill();
    }
  }
}

And that’s it, this is all that is needed to make a simple particle effect using the Stardust engine. Sure this is a very simple effect, but the aim of this tutorial is to understand the basics of how the engine works, from there you can start to create more complex effects using the whole range of complex actions and initializers available in Stardust combined with the built in filters and effects of the Flash Player.

To see the finished particle effect click on the link below, it doesn’t look all that much in the static screen shot below (these kind of effects rarely do), but it is actually a pretty cool smoke effect when you see it in motion. The full source code for this tutorial is also available to download from the demo page at the link below.

demo7-stardust-particle-effect

Click here to view the demo and download source code.

Advertisements

4 thoughts on “Creating a simple particle effect using the Stardust Particle Engine

  1. Wow, Matt. It’s so hard to describe how much I appreciate you for writing a tutorial for Stardust. Thank you so much for writing this step-by-step tutorial in details. I’m glad you’ve tried Stardust and shared your experience with others. Cheers 🙂

    Oh, and if you wonder how I found this post, I just randomly google for Stardust every once in a while, simply to find out if there’s any new site, demo, articles, or tutorials for Stardust :p

    • Matt

      Hi CJ, that’s great to hear, glad you liked the tutorial. Thanks for writing such a cool particle effect library, Stardust is great to code with and the documentation is excellent. Sorry I didn’t reply earlier, have been working on a couple more demos using Stardust, will post them shortly 🙂

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s