Inherits from NSObject
Conforms to NSCopying
Declared in CC3Particles.h

Overview

A particle navigator is assigned to a single particle emitter, and is responsible for configuring the life cycle and emission path of the particle on behalf of the emitter.

When creating your own particle system, customization is accomplished primarily by creating your own implementation of the CC3ParticleProtocol, and your own CC3ParticleNavigator subclass. You are encouraged to create subclasses of CC3ParticleNavigator (perhaps starting from one of the existing provided subclasses).

During particle initialization, the emitter, the navigator, and the particle itself are given a chance to participate in the initialization of the particle. The navigator is distinct from the emitter itself in that the navigator is primarily designed to direct the shape of the emission, by setting particle properties such as the location, direction, and speed of the particle. This separation of responsibilities often means that a single navigator class can be used to direct any type of particle.

For example, a particle navigator designed to emit partiles in the the shape of a fountain could be used to create a fountain of point particles, a fountain of mesh particles, or a fountain of some other class of particles that supported the protocol required by the navigator.

Similarly, a navigator designed to lay particles out on a grid, or sprinkle stars across the sky could do so with point particles or mesh particles.

The particle navigator is only involved in the initialization of the particle. It does not interact with the particle once it has been emitted.

Different particle navigators will have different requirements for configuring particles. The requiredParticleProtocol property of this navigator indicates the protocol that the particles must support in order to be prepared by this navigator during initialization.

Tasks

Properties

emitter

The emitter whose particles are prepared by this navigator.

@property (nonatomic, assign) CC3ParticleEmitter *emitter

Discussion

This property is set automatically when the navigator is attached to the emitter. Usually the application never needs to set this property directly.

Declared In

CC3Particles.h

requiredParticleProtocol

The protocol required by this particle navigator on the particles, in order for this navigator to configure the particles.

@property (nonatomic, retain, readonly) Protocol *requiredParticleProtocol

Discussion

This implementation returns @protocol(CC3ParticleProtocol), permitting all particles to be initialized. In a subclass, you may override to support more specific protocols, based on your needs for configuring particles. When doing so, your protocol must also conform to the base CC3ParticleProtocol protocol.

Because each configuration is unique, this library contains a number of building-block configuration protocols that may be applied to a particle. And you will often want to create your own particle configuration protocols. Since this property may contain only a single protocol, you can create a custom protocol that wraps all of the protocols that you want to use to configure your particle, and assign that custom protocol to this property.

For example, you may want to use both the CC3UniformlyFadingParticleProtocol and CC3MortalParticleProtocol protocols to configure a fading particle that has a finite life. To encompass both requirements, you should create another custom protocol that wraps (conforms to) both of those protocols, and assign it to this requiredParticleProtocol property.

Declared In

CC3Particles.h

Class Methods

navigator

Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value. The tag value is generated using a call to nextTag.

+ (id)navigator

Declared In

CC3Particles.h

Instance Methods

initializeParticle:

Template method that initializes the particle. For particles that follow a planned life-cycle and trajectory, this navigator configures that life-cycle and trajectory for the particle prior to the particle being emitted.

- (void)initializeParticle:(id<CC3ParticleProtocol>)aParticle

Discussion

This method is invoked automatically from the emitter after the emitter has initialized the particle and before the initializeParticle method is invoked on the particle itself.

Subclasses will override this method to configure the particle. Subclasses should always invoke the superclass implementation to ensure the superclass initialization behaviour is performed.

In this method, you can set the isAlive property of the particle to NO to cause the 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 emitted state of a particle that is to be set by the navigator. You should not rely on any state set in the instance initializer of the particle class.

This method is invoked automatically by the emitter when a particle is emitted. Usually the application never has need to invoke this method directly.

Declared In

CC3Particles.h

populateFrom:

Template method that populates this instance from the specified other instance.

- (void)populateFrom:(CC3ParticleNavigator *)another

Discussion

This method is invoked automatically during object copying via the copy or copyWithZone: method. In most situations, the application should use the copy method, and should never need to invoke this method directly.

Subclasses that add additional instance state (instance variables) should extend copying by overriding this method to copy that additional state. Superclass that override this method should be sure to invoke the superclass implementation to ensure that superclass state is copied as well.

Declared In

CC3Particles.h