This class provides an easy way to display particle systems.

Particle Systems can be used to create special effects like explosions, smoke, snow, fire, etc. The system is controlled by a configuration file in the format that is created by Particle Designer. While you don't need that tool to create particle systems, it makes designing them much easier.

In the src-directory, you will find 2 classes — the SXParticleSystem and a helper class. Add those classes directly to your game.

The demo-directory contains a sample project. If you have configured your system for Sparrow, the project should compile and run out of the box.

The project contains 4 sample configurations. Switch between configurations in Game.m by changing the init-method:

mParticleSystem = [[SXParticleSystem alloc] initWithContentsOfFile:@"sun.pex"];

The following sample configurations are provided:

• drugs.pex
• fire.pex
• sun.pex
• waterfall.pex

This is all you have to do to create a particle system. The class SXParticleSystem is a subclass of SPDisplayObject and behaves as such. You can add it as a child to the stage or to any other container. As usual, you have to add it to a juggler (or call its advanceTime: method once per frame) to animate it.

// create particle system
SXParticleSystem *ps = [[SXParticleSystem alloc] initWithContentsOfFile:@"sun.pex"];    
ps.x = 160.0f;
ps.y = 240.0f;
 
// add it to the stage and the juggler
[self addChild:ps];
[self.juggler addObject:ps];
// [[SPStage mainStage].juggler addObject:ps];   // Use this if working from a different scene and not SPStage.
[ps release];
 
// change position where particles are emitted
ps.emitterX = 20.0f;
ps.emitterY = 40.0f;
 
// start emitting particles
[ps start];
 
// emit particles for two seconds, then stop
[ps startBurst:2.0];
 
// stop emitting particles
[ps stop];
 
// or get notified when all particles are gone
[ps addEventListenerForType:SP_EVENT_TYPE_COMPLETED block:^(id event)
{
    NSLog(@"completed");
}];

The particle system's bounds are always a zero-sized rectangle, because calculating the real bounds would be very time-consuming. That means that you can't touch a particle system.

On devices with a retina display (iPhone 4), the performance can suffer when there are a lot of particles on the screen. That's because four times as many pixels have to be rendered for each and every particle!

A simple workaround: store the particle texture twice in the same resolution. Once as “particle.png”, once as “particle@2x.png”. On a retina display, Sparrow will load the “@2x” version and will display it unscaled. (This does not work with a texture that is embedded in the XML file, though.)

The emitter location you can set in the Particle Designer is ignored, too. To move the particle system around, change the x- and y-properties of the particle system, or the emitterX- and emitterY-properties. (While the former moves the complete coordinate system around, the latter just changes where new particles appear.)

Furthermore, the movement of particles is upside-down in Sparrow, compared to the Particle Designer. That's because Sparrow uses another coordinate system (with the origin at the top left). To work around that, you can either set the “scaleY” property of the particle system to “-1”, or design the particle system upside down.

• 2011/06/04: First public version
• 2011/06/11:
  • Reacting to changes in scale (scaleX and scaleY properties)
  • Better handling of low framerates
  • Added scaleFactor property to customize retina display output
  • Added startBurst: method
• 2011/07/11: better handling of negative lifespans
• 2011/08/26:
  • removed obsolete field
  • modernized project (Xcode 4.1)
• 2012/03/19:
  • added properties for all settings
  • added copy method
  • added new init method that takes just a texture
• 2012/04/05: Fixed color overflow error (output was different than PD preview)
• 2012/06/02: Fixed application of radial and tangential acceleration variance
• 2012/06/07: Fixed scale factor propagation
• 2013/04/01: Updated for Sparrow 2.0, moved to new repository
• 2013/09/29: Added support for rotated particles

You can browse the source code of the particle system on its GitHub page.

• Can you please give an example or discuss how we could change it from being a Point Sprite as to enable rotations?
  • That requires to create 4 vertices (instead of one) for each particle, and then draw the particle with 2 triangles made up of those vertices. I plan to add that feature to the PS with the release of Sparrow 2.0, though.
• Could you please show how (and why) the copy method works?
  • To copy the Particle System, just call the copy method! It creates a duplicate with the exact same settings.

    SXParticleSystem *psCopy = [ps copy];

• The XCode 5 beta has a particle system editor in it. Are there any plans to use that format with this extension?