SKEmitterNode Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SpriteKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
SKEmitterNode.h

Overview

A SKEmitterNode object is a node that automatically creates and renders small particle sprites. Particle sprites are privately owned by Sprite Kit—your game cannot access the generated sprites. For example, this means you cannot add physics shapes to particles. Emitter nodes are often used to create smoke, fire, sparks, and other particle effects.

A particle is a textured and colored node whose contents are blended into the framebuffer. Although there is no visible class representing particles added by the emitter node, you can think of a particle as having properties like any other object. When you configure the emitter, you set the birth rate of new particles and provide starting values for a particle’s properties. These properties include:

For each property, you configure the average starting value and a range of acceptable values. The emitter node chooses a random value that lies within this range.

Some properties also allow you to specify a speed or acceleration property that modifies the value of that property over a particle’s lifetime. For example, if the emitter creates particles with an initial alpha of 1.0 and an alpha speed of -0.2, then a particle’s alpha decreases from 1.0 to 0.0 over a period of five seconds, creating a particle that fades from view. You can also use keyframe sequence objects to specify more complex changes over the lifetime of the particle.

Tasks

Determining When Particles Are Created

Defining Which Node Emits Particles

Determining a Particle Lifetime

Determining a Particle’s Initial Position

Determining a Particle’s Velocity and Acceleration

Determining a Particle’s Rotation

Determining a Particle’s Scale Factor

Setting a Particle’s Texture and Size

Configuring Particle Color

Determining How the Particle Texture Is Blended with the Particle Color

Blending Particles with the Framebuffer

Adding an Action to Particles

Properties

emissionAngle

The average initial direction of a particle, expressed as an angle in radians.

@property(nonatomic) CGFloat emissionAngle
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

emissionAngleRange

The range of allowed random values for a particle’s initial speed, expressed as an angle in radians.

@property(nonatomic) CGFloat emissionAngleRange
Discussion

The default value is 0.0. If non-zero, the emission angle of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

numParticlesToEmit

The number of particles the emitter should emit before stopping.

@property(nonatomic) NSUInteger numParticlesToEmit
Discussion

The default value is 0, which indicates that emitter creates an endless stream of particles. If a non-zero value is provided, then the emitter stops generating particles after it has created the specified number of particles.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleAction

Specifies an action executed by new particles.

@property(copy, nonatomic) SKAction *particleAction
Discussion

Adding complex actions to particles can severely impact the performance of the particle emitter. Also, because the particles do not exist as an explicit node that you can manipulate, you cannot remove the actions from existing particles.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleAlpha

The average starting alpha value for a particle.

@property(nonatomic) CGFloat particleAlpha
Discussion

The particle alpha value is equivalent to the alpha property of the SKNode class. The alpha component of the color that results from the texture and color blending state is multiplied by a particle’s alpha value. The resulting particle color is then blended with the parent’s framebuffer. The default value is 1.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleAlphaRange

The range of allowed random values for a particle’s starting alpha value.

@property(nonatomic) CGFloat particleAlphaRange
Discussion

The default value is 0.0. If non-zero, the initial alpha value of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleAlphaSequence

The sequence used to specify the alpha value of a particle over its lifetime.

@property(retain, nonatomic) SKKeyframeSequence *particleAlphaSequence
Discussion

The default value is nil. If a non-nil value is specified, then the particleAlpha, particleAlphaRange, and particleAlphaSpeed properties are ignored. Instead, the sequence is used to specify the alpha value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleAlphaSpeed

The rate at which the alpha value of a particle changes per second.

@property(nonatomic) CGFloat particleAlphaSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleBirthRate

The rate at which new particles are created.

@property(nonatomic) CGFloat particleBirthRate
Discussion

The number of particles generated by the emitter every second. The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleBlendMode

The blending mode used to blend particles into the framebuffer.

@property(nonatomic) SKBlendMode particleBlendMode
Discussion

The default value is SKBlendModeAlpha.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColor

The average initial color for a particle.

@property(retain, nonatomic) SKColor *particleColor
Discussion

The default value is [SKColor clearColor].

A particle’s color is blended with the texture using its blend color factor. See “Determining How the Particle Texture Is Blended with the Particle Color.”

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorAlphaRange

The range of allowed random values for the alpha component of a particle’s initial color.

@property(nonatomic) CGFloat particleColorAlphaRange
Discussion

The default value is 0.0. If non-zero, the starting alpha component of a particle’s color is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorAlphaSpeed

The rate at which the alpha component of a particle’s color changes per second.

@property(nonatomic) CGFloat particleColorAlphaSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlendFactor

The average starting value for the color blend factor.

@property(nonatomic) CGFloat particleColorBlendFactor
Discussion

The default value is 0.0, which means that the texture is used as is, ignoring the particle’s color. Otherwise, the texture is blended with the color.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlendFactorRange

The range of allowed random values for a particle’s starting color blend factor.

@property(nonatomic) CGFloat particleColorBlendFactorRange
Discussion

The default value is 0.0. If non-zero, the initial color blend factor of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlendFactorSequence

The sequence used to specify the color blend factor of a particle over its lifetime.

@property(retain, nonatomic) SKKeyframeSequence *particleColorBlendFactorSequence
Discussion

The default value is nil. If a non-nil value is specified, then the particleColorBlendFactor, particleColorBlendFactorRange, and particleColorBlendFactorSpeed properties are ignored. Instead, the sequence is used to specify the color blend factor.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlendFactorSpeed

The rate at which the color blend factor changes per second.

@property(nonatomic) CGFloat particleColorBlendFactorSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlueRange

The range of allowed random values for the blue component of a particle’s initial color.

@property(nonatomic) CGFloat particleColorBlueRange
Discussion

The default value is 0.0. If non-zero, the starting blue component of a particle’s color is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorBlueSpeed

The rate at which the blue component of a particle’s color changes per second.

@property(nonatomic) CGFloat particleColorBlueSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorGreenRange

The range of allowed random values for the green component of a particle’s initial color.

@property(nonatomic) CGFloat particleColorGreenRange
Discussion

The default value is 0.0. If non-zero, the starting green component of a particle’s color is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorGreenSpeed

The rate at which the green component of a particle’s color changes per second.

@property(nonatomic) CGFloat particleColorGreenSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorRedRange

The range of allowed random values for the red component of a particle’s initial color.

@property(nonatomic) CGFloat particleColorRedRange
Discussion

The default value is 0.0. If non-zero, the starting red component of a particle’s color is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorRedSpeed

The rate at which the red component of a particle’s color changes per second.

@property(nonatomic) CGFloat particleColorRedSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleColorSequence

The sequence used to specify the color components of a particle over its lifetime.

@property(retain, nonatomic) SKKeyframeSequence *particleColorSequence
Discussion

The default value is nil. If a non-nil value is specified, then the particleColor, particleColorAlphaRange, particleColorRedRange, particleColorGreenRange, particleColorBlueRange, particleColorAlphaSpeed, particleColorRedSpeed, particleColorGreenSpeed, and particleColorBlueSpeed properties are ignored. Instead, the sequence is used to specify the particle color.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleLifetime

The average lifetime of a particle, in seconds.

@property(nonatomic) CGFloat particleLifetime
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleLifetimeRange

The range of allowed random values for a particle’s lifetime.

@property(nonatomic) CGFloat particleLifetimeRange
Discussion

The default value is 0.0. If non-zero, the lifetime of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particlePosition

The average starting position for a particle.

@property(nonatomic) CGPoint particlePosition
Discussion

The default value is (0.0,0.0).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particlePositionRange

The range of allowed random values for a particle’s position.

@property(nonatomic) CGVector particlePositionRange
Discussion

The default value is (0.0,0.0). If a component is non-zero, the same component of a particle’s position is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleRotation

The average initial rotation of a particle, expressed as an angle in radians.

@property(nonatomic) CGFloat particleRotation
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleRotationRange

The range of allowed random values for a particle’s initial rotation, expressed as an angle in radians.

@property(nonatomic) CGFloat particleRotationRange
Discussion

The default value is 0.0. If non-zero, the initial rotation of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleRotationSpeed

The speed at which a particle rotates, expressed in radians per second.

@property(nonatomic) CGFloat particleRotationSpeed
Discussion

This is uniform for all particles generated by the emitter. The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleScale

The average initial scale factor of a particle.

@property(nonatomic) CGFloat particleScale
Discussion

The default value is 1.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleScaleRange

The range of allowed random values for a particle’s initial scale.

@property(nonatomic) CGFloat particleScaleRange
Discussion

The default value is 0.0. If non-zero, the initial scale of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleScaleSequence

The sequence used to specify the scale factor of a particle over its lifetime.

@property(retain, nonatomic) SKKeyframeSequence *particleScaleSequence
Discussion

The default value is nil. If a non-nil value is specified, then the particleScale, particleScaleRange, and particleScaleSpeed properties are ignored. Instead, the sequence is used to specify the scale factor.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleScaleSpeed

The rate at which a particle’s scale factor changes per second.

@property(nonatomic) CGFloat particleScaleSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleSize

The starting size of each particle.

@property(nonatomic) CGSize particleSize
Discussion

The default value is CGSizeZero. If set to the default, the size of the texture stored in the particleTexture property is used to determine the size of a particle. If a texture has not been assigned, you must set this property to a non-empty size.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleSpeed

The average initial speed of a new particle in points per second.

@property(nonatomic) CGFloat particleSpeed
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleSpeedRange

The range of allowed random values for a particle’s initial speed.

@property(nonatomic) CGFloat particleSpeedRange
Discussion

The default value is 0.0. If non-zero, the speed of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleTexture

The texture to use to render a particle.

@property(retain, nonatomic) SKTexture *particleTexture
Discussion

A particle is rendered as if it were a SKSpriteNode object. The default value is nil, which means a colored rectangle is used to draw the particle. If a non-nil value is specified, then the texture is colorized and used to draw particles.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleZPosition

The average starting depth of a particle.

@property(nonatomic) CGFloat particleZPosition
Discussion

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

particleZPositionRange

The range of allowed random values for a particle’s depth.

@property(nonatomic) CGFloat particleZPositionRange
Discussion

The default value is 0.0. If non-zero, the z position of each particle is randomly determined and may vary by plus or minus half of the range value.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

targetNode

The target node which renders the emitter’s particles.

@property(weak, nonatomic) SKNode *targetNode
Discussion

The default value is nil, which means that particles are treated as if they were children of the emitter node. In future frames of animation, the particle positions are affected by the emitter node’s properties. If you specify a different target node, the initial properties of new particles are calculated based on the emitter node’s properties, but in future frames of animation the particles are treated as if they were children of the target node.

For example, assume you have an emitter node as a child of the scene node and the node is being rotated by changing its zRotation property. The behavior of the emitter node changes based on the value of the target node:

  • If the targetNode property is nil, then the positions of both previously generated and new particles are rotated.

  • If the targetNode property points to the scene node, then new particles are adjusted when the emitter node rotates, but previously generated particles are not.

By spawning the particles inside the scene node, they have behavior independent of the emitter’s properties.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

xAcceleration

The acceleration to apply to a particle’s horizontal velocity.

@property(nonatomic) CGFloat xAcceleration
Discussion

This property is useful for simulating wind, gravity and other effects. It is uniformly applied to all particles generated by the emitter.

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

yAcceleration

The acceleration to apply to a particle’s vertical velocity.

@property(nonatomic) CGFloat yAcceleration
Discussion

This property is useful for simulating wind, gravity and other effects. It is uniformly applied to all particles generated by the emitter.

The default value is 0.0.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

Instance Methods

advanceSimulationTime:

Advances the emitter particle simulation.

- (void)advanceSimulationTime:(NSTimeInterval)sec
Parameters
sec

The number of seconds to simulate.

Discussion

Once added to a scene, an emitter node automatically creates new particles in new animation frames. This method allows you to artificially advance an emitter’s simulation, causing it to generate new particles and advance any existing particles. The most common use for this method is to prepopulate an emitter node with particles after it is first added to a scene.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h

resetSimulation

Removes all existing particles and restarts the simulation.

- (void)resetSimulation
Discussion

Resetting the simulation clears the internal state of the simulation.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKEmitterNode.h