Particles

WikiPedia: Particle System

There are two types of particle system in cocos2d: Quad and Point particle system

• CCParticleSystemQuad
• CCParticleSystemPoint

The CCParticleSystemQuad has these additional features that CCParticleSystemPoint doesn't support:

• Spinning particles: particles can rotate around its axis. CCParticleSystemPoint ignores this property.
• Particles can have any size. In CCParticleSystemPoint if the size is bigger than 64, it will be treated as 64.
• The whole system can be scaled using the scale property.

From the API docs:

• On 1st and 2nd gen iPhones: CCParticleSystemQuad is only a bit slower than CCParticleSystemPoint.
• On 3rd gen iPhone and iPads: CCParticleSystemQuad is MUCH faster than CCParticleSystemPoint.
• CCParticleSystemQuad consumes more RAM and more GPU memory than CCParticleSystemPoint

To create a Point Particle System:

	id particleSystem = [[CCParticleSystemPoint alloc] initWithTotalParticles:numberOfParticles];

To create a Quad Particle System:

	id particleSystem = [[CCParticleSystemQuad alloc] initWithTotalParticles:numberOfParticles];

Since v0.99.3, a new mode was added: Radius Mode. The old behavior is called Gravity mode.

These properties are only valid in Gravity Mode:

• gravity (a CGPoint). The gravity of the particle system
• speed (a float). The speed at which the particles are emitted
• speedVar (a float). The speed variance.
• tangencialAccel (a float). The tangential acceleration of the particles.
• tangencialAccelVar (a float). The tangential acceleration variance.
• radialAccel (a float). The radial acceleration of the particles.
• radialAccelVar (a float). The radial acceleration variance.

To set the particle in 'Gravity mode' (default one), you need to do these:

	id particleSystem = [[CCParticleSystemQuad alloc] initWithTotalParticles:numberOfParticles];
	[particleSystem setEmitterMode: kCCParticleModeGravity];

This mode is only available since v0.99.3

These properties are only valid in Radius Mode:

• startRadius (a float). The starting radius of the particles
• startRadiusVar (a float). The starting radius variance
• endRadius (a float). The ending radius of the particles. Use kCCParticleStartRadiusEqualToEndRadius if you want that the start radius == end radius.
• endRadiusVar (a float). The ending radius variance
• rotatePerSecond (a float). Number of degress to rotate a particle around the source pos per second.
• rotatePerSecondVar (a float). Number of degrees variance.

To set the particle in 'Radius mode', you need to do these:

	id particleSystem = [[CCParticleSystemQuad alloc] initWithTotalParticles:numberOfParticles];
	[particleSystem setEmitterMode: kCCParticleModeRadius];

Common properties of the particles:

• startSize: Start size of the particles in pixels
• startSizeVar
• endSize: Use kCCParticleStartSizeEqualToEndSize if you want that the start size == end size.
• endSizeVar
• startColor (a ccColor4F)
• startColorVar (a ccColor4F)
• endColor (a ccColor4F)
• endColorVar (a ccColor4F)
• startSpin. Only used in CCParticleSystemQuad
• startSpinVar. Only used in CCParticleSystemQuad
• endSpin. Only used in CCParticleSystemQuad
• endSpinVar. Only used in CCParticleSystemQuad
• life: time to live of the particles in seconds
• lifeVar:
• angle: (a float). Starting degrees of the particle
• angleVar
• positon: (a CGPoint)
• posVar
• centerOfGravity (a CGPoint)

Common properties of the system:

• emissionRate (a float). How many particle are emitted per second
• duration (a float). How many seconds does the particle system (different than the life property) lives. Use kCCParticleDurationInfinity for infity.
• blendFunc (a ccBlendFunc). The OpenGL blending function used for the system
• positionType (a tCCPositionType). Use kCCPositionTypeFree (default one) for moving particles freely. Or use kCCPositionTypeGrouped to move them in a group.
• texture (a CCTexture2D). The texture used for the particles

cocos2d comes with some predefined particles that can be customized in runtime. List of predefined particles:

• CCParticleFire: Point particle system. Uses Gravity mode.
• CCParticleFireworks: Point particle system. Uses Gravity mode.
• CCParticleSun: Point particle system. Uses Gravity mode.
• CCParticleGalaxy: Point particle system. Uses Gravity mode.
• CCParticleFlower: Point particle system. Uses Gravity mode.
• CCParticleMeteor: Point particle system. Uses Gravity mode.
• CCParticleSpiral: Point particle system. Uses Gravity mode.
• CCParticleExplosion: Point particle system. Uses Gravity mode.
• CCParticleSmoke: Point particle system. Uses Gravity mode.
• CCParticleSnow: Point particle system. Uses Gravity mode.
• CCParticleRain: Point particle system. Uses Gravity mode.

Particle Designer is a tool that lets you create particles visually.

In order to use the particles created with it you should:

1. Download & Register Particle Designer (you need to register it in order to save the particles)
2. Use the “cocos2d (plist)” format when saving the texture (you can embed the texture or not. cocos2d supports both format)

To load a particle created with Particle Designer you should do:

	// Either you can create a Quad particle system
	id particleSystem = [CCParticleSystemQuad particleWithFile:@"MyParticle.plist"];
 
	// ...or a Point particle system.
	id particleSystem = [CCParticleSystemQuad particleWithFile:@"MyParticle.plist"];

cocos2d supports all the Particle Designer features, but not all the cocos2d features are supported by Particle Designer.

• startSpin / startSpinVar: only when using Quads
• endSpin / endSpinVar: only when using Quads

• tangentiallAccel / tangentialAccelVar: only supported in cocos2d
• radialAccel / radialAccelVar: only supported in cocos2d

cocos2d copied the the Radius Mode from Particle Designer, and also extended it a little bit.

Particle Designer uses these 3 properties:

• maxRadius
• maxRadiusVariance
• minRaidus

And cocos2d uses these other variables:

• startRadius
• startRadiusVar
• endRadius
• endRadiusVar

cocos2d emulates the Particle Designer behavior, and also offers a few more possibilities like:

• Radius variance could be 0 or positive (grows from inside to outside)

There is a “feature request” already open at 71squared to support the missing features.

Particle Mint is an another tool that lets you create particles visually using your iPad or iPhone. It is available on App Store

In order to use the particles created with it you should:

1. Download & Buy In App ability to save and send particle systems.
2. Email yourself created particle system, and follow instructions in e-mail. Actually you will need to add to your Xcode project Particle Factory class, and insert there static method which will generate your particle system.

To load a particle created with Particle Mint you should do:

• Import Particle Factory class and textures to your project.
• Use code:

	CCParticleSystemQuad *effect = [[CCParticleSystemQuad alloc] initWithDictionary:[ParticleFactory makeEffect]];

Particle Mint is based on cocos2d-1.0-rc3, so it supports all particle system futures and show real performance on devices.