Class

SKEmitterNode

A source of various particle effects.

Declaration

@interface SKEmitterNode : SKNode

Overview

A SKEmitterNode object is a node that automatically creates and renders small particle sprites. Particles are privately owned by SpriteKit—your game cannot access the generated sprites. For example, you cannot add physics shapes to particles. Emitter nodes are often used to create smoke, fire, sparks, and other particle effects. A particle is similar to an SKSpriteNode object; it renders a textured or untextured image that is sized, colorized, and blended into the scene. However, particles differ from sprites in two important ways:

  • A particle’s texture is always stretched uniformly.

  • Particles are not represented by objects in SpriteKit. This means you cannot perform node-related tasks on particles, nor can you associate physics bodies with particles to make them interact with other content. 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.

Particles are purely visual objects, and their behavior is entirely defined by the emitter node that created them. The emitter node contains many properties to control the behavior of the particles it generates, including:

  • The birth rate and lifetime of the particle. You can also specify the order in which the particles are rendered and the maximum number of particles that are created before the emitter turns itself off.

  • The starting values of the particle, including its position, orientation, color, and size. You can choose to have these starting values randomized.

  • The changes to apply to the particle over its lifetime. Typically, these are specified as a rate of change over time. For example, you might specify that a particle rotates at a particular rate, in radians per second. The emitter automatically updates the particle data for each frame. In most cases, you can also create more sophisticated behaviors using keyframe sequences. For example, you might specify a keyframe sequence for a particle so that it starts out small, scales up to a larger size, then shrinks before dying.

Topics

First Steps

Creating Particle Effects

Add particle effects to your app by creating repeatable particles in Xcode's editor, or in code.

Choosing Which Node in the Scene Emits Particles

Choose which node in the scene emits particles.

Changing the Location of Particles in Your Scene

Set a target node from which SpriteKit creates particles.

targetNode

The target node that renders the emitter’s particles.

Controlling When Particles Are Created

- advanceSimulationTime:

Advances the emitter particle simulation.

- resetSimulation

Removes all existing particles and restarts the simulation.

particleBirthRate

The rate at which new particles are created.

numParticlesToEmit

The number of particles the emitter should emit before stopping.

Controlling the Rendering Order of an Emitter's Particles

particleRenderOrder

The order in which the emitter’s particles are rendered.

SKParticleRenderOrder

The order to use when the emitter’s particles are rendered.

Controlling Particle Lifetime

particleLifetime

The average lifetime of a particle, in seconds.

particleLifetimeRange

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

Controlling Particle Position

particlePosition

The average starting position for a particle.

particlePositionRange

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

particleZPosition

The average starting depth of a particle.

particleZPositionRange

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

Deprecated

Controlling Particle Velocity and Acceleration

particleSpeed

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

particleSpeedRange

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

emissionAngle

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

emissionAngleRange

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

xAcceleration

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

yAcceleration

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

particleZPositionSpeed

The speed at which the particle’s depth changes.

Deprecated

Adjusting a Particle’s Rotation

particleRotation

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

particleRotationRange

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

particleRotationSpeed

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

Scaling Particles by a Factor

particleScale

The average initial scale factor of a particle.

particleScaleRange

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

particleScaleSpeed

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

particleScaleSequence

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

Changing a Particle's Source Image and Size

particleTexture

The texture to use to render a particle.

particleSize

The starting size of each particle.

Configuring Particle Color

particleColorSequence

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

particleColor

The average initial color for a particle.

particleColorAlphaRange

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

particleColorBlueRange

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

particleColorGreenRange

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

particleColorRedRange

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

particleColorAlphaSpeed

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

particleColorBlueSpeed

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

particleColorGreenSpeed

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

particleColorRedSpeed

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

Controlling How the Texture is Blended with Particle Color

particleColorBlendFactorSequence

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

particleColorBlendFactor

The average starting value for the color blend factor.

particleColorBlendFactorRange

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

particleColorBlendFactorSpeed

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

Blending Particles with the Framebuffer

Change how an emitter uses an alpha value, such as additive blending, that results in the emitter being brighter than it was before.

particleBlendMode

The blending mode used to blend particles into the framebuffer.

particleAlphaSequence

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

particleAlpha

The average starting alpha value for a particle.

particleAlphaRange

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

particleAlphaSpeed

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

Animating Particles

Change particles over time using actions or keyframe sequences.

Animating Particle Properties Across Disparate Values

Supply keyframe sequences to do linear or nonlinear particle animations.

particleAction

An action executed by new particles.

Applying Physics Fields to the Particles

fieldBitMask

A mask that defines which categories of physics fields can exert forces on the particles.

Taking Full Control of Particle Drawing with a Shader

Getting Started with Particle Shaders

Provide custom shader code to alter a particle's look.

shader

A custom shader used to determine how particles are rendered.

attributeValues

The values of each attribute associated with the node's attached shader.

- setValue:forAttributeNamed:

Sets an attribute value for an attached shader.

- valueForAttributeNamed:

Gets the value of a shader attribute.

Maximizing Particle Run-Time Performance

Optimizing Emitter Node Performance

Use proven methods to rapidly create and play back performant particle effects.

Relationships

Inherits From

See Also

Nodes that Draw

Maximizing Node Drawing Performance

Structure your nodes for maximum performance.

SKSpriteNode

An image or solid color.

SKShapeNode

A mathematical shape that can be stroked or filled.

SKLabelNode

A graphical element that draws text.

SKVideoNode

A graphical element that plays video content.

SKTileMapNode

A two-dimensional array of images.

SK3DNode

3D SceneKit content drawn as a flattened sprite.