~~NOTOC~~

====== SXParticleSystem ======

---- dataentry extension ----
type          : extension #or 'mod' if it requires changing the Sparrow source
author_mail   : daniel@gamua.com Daniel Sperl
description   : Particle System for special effects
lastupdate_dt : 2011-08-26 #the date you created the extension
compatible    : v2.0 #the Sparrow version you tested the extension with
depends       :  #if the ext. depends on others, list them here
tags          : particle, particle-system, 71squared
homepage_url  : https://github.com/Gamua/Sparrow-Extension-Particle-System
download_url  : https://github.com/Gamua/Sparrow-Extension-Particle-System/zipball/master
----

===== Overview =====

{{ :extensions:particle-designer.png?300|}}

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 [[http://particledesigner.71squared.com|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.

<note info>
If you're looking for a version of the particle system \\
that runs with Sparrow 1.x, you can still get it [[https://github.com/PrimaryFeather/Sparrow-Extension-Particle-System|here]].
</note>
===== Sample Project =====

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:

<code objc>
mParticleSystem = [[SXParticleSystem alloc] initWithContentsOfFile:@"sun.pex"];
</code>
    
The following sample configurations are provided:

  * drugs.pex
  * fire.pex
  * sun.pex
  * waterfall.pex

===== Usage =====

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.

<code objc>
// 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");
}];
</code>

===== Remarks =====

=== Not touchable ===

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.

=== Performance on Retina displays ===

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.)

=== Particle Designer: emitter location ignored ===

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.)

=== Particle Designer: systems are upside-down ===

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.

===== Changelog =====

  * //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 [[https://github.com/Gamua/Sparrow-Extension-Particle-System|new repository]]
  * //2013/09/29//: Added support for rotated particles
===== Source Code =====

You can browse the source code of the particle system on its [[https://github.com/Gamua/Sparrow-Extension-Particle-System/tree/master/src|GitHub page]].

===== Discussion =====

  * 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. <code objc>
SXParticleSystem *psCopy = [ps copy];
</code>
  * The XCode 5 beta has a particle system editor in it. Are there any plans to use that format with this extension?