Conforms to CC3Object
Declared in CC3Particles.h

Overview

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.

Tasks

Properties

emitter

The emitter that emitted this particle.

@property (nonatomic, assign) CC3ParticleEmitter *emitter

Discussion

This property is set automatically when the particle is added to the emitter, or emitted automatically by the emitter. The application should not set this property directly. Doing so will cause the particle to abort emission.

Declared In

CC3Particles.h

isAlive

Indicates whether this particle is alive or not. When a particle is added to the emitter, or emitted automatically by the emitter, the value of this property is automatically set to YES by the emitter before the initializeParticle method is invoked.

@property (nonatomic, assign) BOOL isAlive

Discussion

You can set this property to NO from within the updateBeforeTransform: or updateAfterTransform: method to indicate that this particle has expired. 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: 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.

Declared In

CC3Particles.h

Instance Methods

finalizeParticle

This template callback method is invoked automatically at the end of the particle’s lifecycle, when this particle has expired and been removed from active use.

- (void)finalizeParticle

Discussion

Since the emitter may hold onto the particle in an inactive state for future reuse, this method provides the particle with the opportunity to release any content that depends on the particle being alive and in use.

Declared In

CC3Particles.h

fullDescription

Returns a string containing a more complete description of this particle.

- (NSString *)fullDescription

Declared In

CC3Particles.h

init

The standard object initialization method that is invoked when this instance is instantiated.

- (id)init

Discussion

In the interests of performance and memory conservation, expired particles may be cached and reused by the emitter. Your particle should not rely on any state set in this method. Most initialization should be performed in the initializeParticle method, which is invoked each time the particle is used or reused by the emitter.

Declared In

CC3Particles.h

initializeParticle

This template callback method is invoked automatically at the beginning of the particle’s life-cycle, when this particle is added to the emitter manually by the application, or when the particle is emitted automatically by the emitter.

- (void)initializeParticle

Discussion

You should implement this method to establish any initial state of the particle.

During execution of this method, you can access and set the initial values of the particle properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D scene.

This method is invoked after the the isAlive property has been set to YES, and after the emitter and its navigator have set any particle state that they want to initialize. In this method, you can change any of the particle state prior to it being emitted. You can also set the isAlive property of the particle to NO to cause the addition or emission of the particle to be aborted.

When this method is invoked, the particle may have just been instantiated, or it may be an older expired particle that is being reused. With this in mind, this method should include all code that establishes the initial state of a particle. You should not rely on any state set in the init method of the particle.

If you have subclassed another class that implements the CC3ParticleProtocol protocol, you should be sure to invoke this method on the superclass as part of your implementation, to give the superclass an opportunity to initialize the state it manages. You should also check the state of the isAlive property as set by the superclass before performing further initialization.

Declared In

CC3Particles.h

updateAfterTransform:

This template callback method is invoked automatically whenever the emitter is updated during a scheduled 3D scene update. This method is invoked on the particles after the emitter and particles have been transformed, and before the updateAfterTransform: method is invoked on the emitter.

- (void)updateAfterTransform:(CC3NodeUpdatingVisitor *)visitor

Discussion

Because this method is invoked after the emitter has been transformed, you can access global transform properties of the particle and emitter from within this method.

The specified visitor includes a deltaTime property, which is the time interval since the last update, so that the particle can emulate realistic real-time behaviour

This method will only be invoked on the particles if the shouldUpdateParticlesAfterTransform property of the emitter is set to YES. As an optimization, for particles that do not need to be updated after they are transformed, that property can be set to NO to avoid an unnecessary iteration of the particles.

Although it is recommended that you determine whether a particle should expire in the updateBeforeTransform: method to avoid transforming a particle you no longer need, you can also set the isAlive property of the particle to NO in this method to cause the emitter to remove this particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateAfterTransform: method invocations.

Declared In

CC3Particles.h

updateBeforeTransform:

This template callback method is invoked automatically whenever the emitter is updated during a scheduled 3D scene update. This method is invoked on the particles after the updateBeforeTransform: method is invoked on the emitter, and before the emitter and particles are transformed.

- (void)updateBeforeTransform:(CC3NodeUpdatingVisitor *)visitor

Discussion

This method will only be invoked on the particles if the shouldUpdateParticlesBeforeTransform property of the emitter is set to YES. As an optimization, for particles that do not need to be updated before they are transformed, that property can be set to NO to avoid an unnecessary iteration of the particles.

You can override this method to control the behaviour and motion of the particle during its lifetime.

The specified visitor includes a deltaTime property, which is the time interval since the last update, so that the particle can emulate realistic real-time behaviour

It is up to the particle to determine when it expires. Some particles may never expire. Particles that do have a finite lifespan will keep track of their lifecycle, and accumulate the deltaTime property of the specified visitor to keep track of the passing of time.

Once the particle has detemined that it has expired, you can set the isAlive property of the particle to NO in this method. When this method returns, if the isAlive property has been set to NO, the emitter will automatically remove this particle (and set it aside for possible reuse). Expired particles are not drawn and do not receive further updateBeforeTransform: method invocations.

During execution of this method, you can access and set the particle’s properties. The emitter property can be used to access further information in the emitter or other aspects of the 3D scene.

Declared In

CC3Particles.h