<CC3ParticleProtocol> Protocol Reference

#import <CC3Particles.h>

Inheritance diagram for <CC3ParticleProtocol>:
Inheritance graph

Detailed Description

CC3ParticleProtocol represents a single particle emitted by a CC3ParticleEmitter particle emitter.

When creating a particle system, you write application-specific implementation of CC3ParticleProtocol to embody the state and life-cycle behaviour of each particle. You do not always need to create a customized subclass of CC3ParticleEmitter.

To implement a specific particle system, create an implementation of CC3ParticleProtocol, and override the initializeParticle and updateBeforeTransform: methods (and possibly the updateAfterTransform: method) to define the initial state, and life-cycle behaviour of the particle.

Particles can be added to an emitter by the application directly, or can be created and emitted from the emitter automatically, based on configuration within the emitter. In both cases, the interaction on the particle is the same.

When a particle starts its life, the emitter will automatically invoke the initializeParticle method on the particle.

Then, during the life-cycle of a particle, the emitter will periodically update the particle by invoking the updateBeforeTransform: and updateAfterTransform: callback methods. These method invocations include the time interval since the last update, so that the particle can emulate realistic real-time behaviour.

Be aware that, in the interests of performance and memory conservation, expired particles may be cached and reused, and particle emission may not always involve instantiating a new instance of your CC3ParticleProtocol implementation class.

With this in mind, you should not depend on init method being invoked during particle emission. All code that establishes the initial emitted state of a particle should be included in the initializeParticle method.

From within the initializeParticle, updateBeforeTransform: and updateAfterTransform methods, the particle has access to the emitter (and the node hierarchy and scene it sits in) through the emitter property. In addition, the particle can read and manipulate its own drawable content.

Beyond these basic drawable content properties, when you create in implementation of CC3ParticleProtocol, you should add any other content that is needed to determine the behaviour of your particle. For example, you might include a velocity property for particles that are following a path (or even a path object to define that path more explicitly), and a timeToLive property, for particles that have a finite lifespan. There are several protocol extensions, such as CC3MortalParticleProtocol and CC3UniformlyMovingParticleProtocol that provide standard definitions of basic additional functionality in this respect.

It is up to the particle to determine when it expires. Some particles may never expire. Others may keep track of their life or path and expire at a certain time or place.

Once your custom particle has detemined that it has expired, in the updateBeforeTransform: or updateAfterTransform method, you can set the isAlive property of the particle to NO. When either of those methods returns, the emitter will then automatically remove the particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateBeforeTransform: or updateAfterTransform: callback method invocations.

You can also set the isAlive property to NO in the initializeParticle method to cause the emission of the particle to be aborted.

The documentation for this protocol was generated from the following file: