iOS Developer Library

Developer

SpriteKit Framework Reference SKEmitterNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKEmitterNode

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 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 Sprite Kit. 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 spawns, including:

  • The birth rate and lifetime the particle. You can also specify the maximum number of particles that are spawned 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 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.

Use the Particle Emitter Editor to Experiment with Emitters

In most cases, you never need to configure an emitter node directly in your game. Instead, you use Xcode to configure an emitter node’s properties. As you change the behavior of the emitter node, Xcode immediately provides you an updated visual effect. When complete, Xcode archives the configured emitter. Then, at runtime, your game uses this archive to instantiate a new emitter node.

Using Xcode to create your emitter nodes has a few important advantages:

  • It is the best way to learn the capabilities of the emitter class.

  • You can more quickly experiment with new particle effects and see the results immediately.

  • You separate the task of designing a particle effect from the programming task of using it. Your artists can work on new particle effects independent of your game code.

For more information on using Xcode to create particle effects, see Particle Emitter Editor Guide.

Loading a particle effect from a file shows how to load a particle effect that was created by Xcode. All particle effects are saved using Cocoa’s standard archiving mechanisms, so the code first creates a path to the smoke effect, and then loads the archive.

Listing 1Loading a particle effect from a file
  • - (SKEmitterNode *) newSmokeEmitter
  • {
  • NSString *smokePath = [[NSBundle mainBundle] pathForResource:@"smoke" ofType:@"sks"];
  • SKEmitterNode *smoke = [NSKeyedUnarchiver unarchiveObjectWithFile:smokePath];
  • return smoke;
  • }

Manually Configuring Particle Creation

The SKEmitterNode class provides many properties for configuring an emitter node’s behavior. The Xcode inspector sets the same property values. You can also create and configure your own emitter, or you can take an emitter node created in the Particle Emitter Editor, load it, and change its property values. For example, assume for a moment that you are using the smoke effect in Loading a particle effect from a file to show damage to a rocket ship. As the ship takes more damage, you could increase the birth rate of the emitter to add more smoke.

When the emitter node is in a scene, it emits new particles. You use the following properties to define how many particles it creates:

  • The particleBirthRate property specifies the number of particles that the emitter creates every second.

  • The numParticlesToEmit property specifies how many particles are created before the emitter turns itself off. You can also configure the node to emit an unlimited number of particles.

When a particle is created, its initial property values are determined by the properties of the emitter. For each of the particle’s properties, the emitter class declares up to four properties:

  • The average starting value for the property.

  • A random range for values of the property. Each time a new particle is emitted, a new random value is calculated within that range.

  • The rate at which the value changes over time, also known as the property’s speed. Not all properties have a speed property.

  • An optional keyframe sequence.

The complete list of properties used to configure an emitter node is described in SKEmitterNode Class Reference.

Using a sequence to change a particle’s scale property shows how you might configure an emitter’s scale property. This is a simplified version of a node’s xScale and yScale properties, and determines how large the particle is.

Listing 2Configuring a particle’s scale properties
  • myEmitter.particleScale = 0.3;
  • myEmitter.particleScaleRange = 0.2;
  • myEmitter.particleScaleSpeed = -0.1;

When a new particle is created, its scale value is a random number from 0.2 to 0.4. The scale value then decreases at a rate of 0.1 per second. So, if a particular particle started at the average value, 0.3, it would decrease from 0.3 to 0 over a period of 3 seconds.

Using Keyframe Sequences to Configure Custom Ramps for a Particle Property

Keyframe sequences provide more sophisticated behaviors for a particle property. A keyframe sequence specifies multiple points in a particle’s lifetime and specifies the value for a property at each point. The keyframe sequence then interpolates values between those points and uses them to simulate the particle’s property value.

You can use keyframe sequences to implement many custom behaviors, including:

  • Changing a property value until it reaches a specific value.

  • Using multiple different property values over the lifetime of a particle. For example, you might increase the value of the property in one part of the sequence and decrease it in another. Or, when specifying colors, you might specify multiple colors that the particle cycles through during its lifetime.

  • Changing a property value using a nonlinear curve or a stepping function.

Using a sequence to change a particle’s scale property shows how you might replace the code in Configuring a particle’s scale properties to use a sequence. When you use a sequence, the values are not randomized. Instead, the sequence specifies all of the values of the property. Each keyframe value includes a value object and a timestamp. The timestamps are specified in a range from 0 to 1.0, where 0 represents the birth of the particle and 1.0 represents its death. So, for this sequence, the particle starts out with a scale of 0.2 and increases to 0.7 one quarter of the way through the sequence. Three quarters of the way through the sequence, it reaches its minimum size, 0.1. It remains at this size until it dies.

Listing 3Using a sequence to change a particle’s scale property
  • SKKeyframeSequence *scaleSequence = [[SKKeyframeSequence alloc] initWithKeyframeValues:@[@0.2,@0.7,@0.1] times:@[@0.0,@0.250,@0.75]];
  • myEmitter.particleScaleSequence = scaleSequence;

Adding Actions to Particles

Although you do not have direct access to the particles created by Sprite Kit, you can specify an action that all particles execute. Whenever a new particle is created, the emitter tells the particle to run that action. You can use actions to create very sophisticated behaviors.

For the purpose of using actions on particles, you can treat the particle as if it were a sprite. This means you can perform other interesting tricks, such as animating the particle’s textures.

Using Target Nodes to Change the Destination of Particles

When the emitter creates particles, they are rendered as children of the emitter node. This means that they inherit the characteristics of the emitter node, just like nodes do. For example, if you rotate the emitter node, the positions of all of the spawned particles are rotated also. Depending on what effect you are simulating with the emitter, this may not be the correct behavior. For example, assume that you are using the emitter node to create the exhaust from a rocket. When the engines are at full burn, a cone of flame should come out the back of the ship. This is easily simulated using particles. But if the particles are rendered relative to the ship, when the ship turns, the exhaust is going to rotate as well. That doesn’t look right. What you really want is for the particles to be spawned, but thereafter be independent of the emitter node. When the emitter node is rotated, new particles get the new orientation, and old particles maintain their old orientation. You make particles independent of the emitter by specifying a target node.

Using a target node to redirect where particles are spawned shows how to configure a rocket exhaust effect to use a target node. When the custom sprite node class instantiates the exhaust node, it makes the node its child. However, it redirects the particles to the scene.

Listing 4Using a target node to redirect where particles are spawned
  • - (void) newExhaustNode
  • {
  • SKEmitterNode *emitter = [NSKeyedUnarchiver unarchiveObjectWithFile:[[NSBundle mainBundle] pathForResource:@"exhaust" ofType:@"sks"]];
  • // Place the emitter at the rear of the ship.
  • emitter.position = CGPointMake(0,-40);
  • emitter.name = @"exhaust";
  • // Send the particles to the scene.
  • emitter.targetNode = self.scene;
  • [self addChild:emitter];
  • }

When an emitter has a target node, it calculates the position, velocity, and orientation of the particle, exactly as if it were a child of the sprite node. This means that if the ship sprite is rotated, the exhaust orientation is automatically rotated also. However, at the moment a new particle’s starting values are calculated, the values are transformed into the target node’s coordinate system. Thereafter, they would only be affected by changes to the target node.

Particle Emitter Tips

Particle emitters in Sprite Kit are one of the most powerful tools for building visual effects. However, used incorrectly, particle emitters can be a bottleneck in the design and implementation of your app. Consider the following tips:

  • Use Xcode to create and test your particle effects, then load the archives in your game.

  • Adjust emitter properties sparingly inside your game code. Typically, you do this to specify properties that cannot be specified in the Xcode inspector or to control properties inside your game logic.

  • Particles are cheaper than a sprite node, but they still have overhead! Try to keep the number of particles onscreen to a minimum by creating particle emitters with a low birth rate, and specifying a short lifetime for particles. For example, instead of creating hundreds or thousands of particles per second, reduce the birth rate and increase the size of the particles slightly. Often, you can create effects with fewer particles but the same net visual appearance.

  • Use actions on particles only when there isn’t another solution. Executing actions on individual particles is potentially very expensive, especially if the particle emitter also has a high birth rate.

  • Assign a target node whenever the particles should be independent of the emitter node after they are spawned. For examples, particles should be independent if the emitter node moves or rotates in the scene.

  • Consider removing a particle emitter from the scene when it is not visible onscreen. Add it just before it becomes visible.

Inheritance


Conforms To


Import Statement


Swift

import SpriteKit

Objective-C

@import SpriteKit;

Availability


Available in iOS 7.0 and later.
  • The rate at which new particles are created.

    Declaration

    Swift

    var particleBirthRate: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleBirthRate

    Discussion

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

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Advances the emitter particle simulation.

    Declaration

    Swift

    func advanceSimulationTime(_ sec: NSTimeInterval)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The number of particles the emitter should emit before stopping.

    Declaration

    Swift

    var numParticlesToEmit: Int

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Removes all existing particles and restarts the simulation.

    Declaration

    Swift

    func resetSimulation()

    Objective-C

    - (void)resetSimulation

    Discussion

    Resetting the simulation clears the internal state of the simulation.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The target node which renders the emitter’s particles.

    Declaration

    Swift

    weak var targetNode: SKNode?

    Objective-C

    @property(nonatomic, weak) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The average lifetime of a particle, in seconds.

    Declaration

    Swift

    var particleLifetime: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleLifetime

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleLifetimeRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleLifetime

  • The average starting position for a particle.

    Declaration

    Swift

    var particlePosition: CGPoint

    Objective-C

    @property(nonatomic) CGPoint particlePosition

    Discussion

    The default value is (0.0,0.0).

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particlePositionRange: CGVector

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particlePosition

  • The average starting depth of a particle.

    Declaration

    Swift

    var particleZPosition: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleZPosition

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleZPositionRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particlePosition

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

    Declaration

    Swift

    var particleSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleSpeedRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleSpeed

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

    Declaration

    Swift

    var emissionAngle: CGFloat

    Objective-C

    @property(nonatomic) CGFloat emissionAngle

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var emissionAngleRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    emissionAngle

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

    Declaration

    Swift

    var xAcceleration: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var yAcceleration: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The speed at which the particle’s depth changes.

    Declaration

    Swift

    var particleZPositionSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleZPositionSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var particleRotation: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleRotation

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleRotationRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleRotation

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

    Declaration

    Swift

    var particleRotationSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleRotationSpeed

    Discussion

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

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleScaleSequence: SKKeyframeSequence?

    Objective-C

    @property(nonatomic, retain) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The average initial scale factor of a particle.

    Declaration

    Swift

    var particleScale: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleScale

    Discussion

    The default value is 1.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleScaleRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleScale

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

    Declaration

    Swift

    var particleScaleSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleScaleSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The texture to use to render a particle.

    Declaration

    Swift

    var particleTexture: SKTexture?

    Objective-C

    @property(nonatomic, retain) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleSize

  • The starting size of each particle.

    Declaration

    Swift

    var particleSize: CGSize

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleTexture

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

    Declaration

    Swift

    var particleColorSequence: SKKeyframeSequence?

    Objective-C

    @property(nonatomic, retain) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The average initial color for a particle.

    Declaration

    Swift

    var particleColor: UIColor!

    Objective-C

    @property(nonatomic, retain) UIColor *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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorAlphaRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleColor

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

    Declaration

    Swift

    var particleColorBlueRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleColor

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

    Declaration

    Swift

    var particleColorGreenRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleColor

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

    Declaration

    Swift

    var particleColorRedRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleColor

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

    Declaration

    Swift

    var particleColorAlphaSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleColorAlphaSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorBlueSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleColorBlueSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorGreenSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleColorGreenSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorRedSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleColorRedSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorBlendFactorSequence: SKKeyframeSequence?

    Objective-C

    @property(nonatomic, retain) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The average starting value for the color blend factor.

    Declaration

    Swift

    var particleColorBlendFactor: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorBlendFactorRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleColorBlendFactorSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleColorBlendFactorSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The blending mode used to blend particles into the framebuffer.

    Declaration

    Swift

    var particleBlendMode: SKBlendMode

    Objective-C

    @property(nonatomic) SKBlendMode particleBlendMode

    Discussion

    The default value is SKBlendModeAlpha.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleAlphaSequence: SKKeyframeSequence?

    Objective-C

    @property(nonatomic, retain) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The average starting alpha value for a particle.

    Declaration

    Swift

    var particleAlpha: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var particleAlphaRange: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    particleAlpha

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

    Declaration

    Swift

    var particleAlphaSpeed: CGFloat

    Objective-C

    @property(nonatomic) CGFloat particleAlphaSpeed

    Discussion

    The default value is 0.0.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Specifies an action executed by new particles.

    Declaration

    Swift

    @NSCopying var particleAction: SKAction?

    Objective-C

    @property(nonatomic, copy) 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.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var fieldBitMask: UInt32

    Objective-C

    @property(nonatomic, assign) uint32_t fieldBitMask

    Discussion

    When a particle is inside the region of a SKFieldNode object, that field node’s categoryBitMask property is compared to the emitter’s fieldBitMask property by performing a logical AND operation. If the result is a non-zero value, then the field node’s effect is applied to the particle as if it had a physics body. The physics body is assumed to have a mass of 1.0 and a charge of 1.0

    The default value is 0x00000000 (all bits cleared).

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • shader shader Property

    A custom shader used to determine how particles are rendered.

    Declaration

    Swift

    var shader: SKShader?

    Objective-C

    @property(nonatomic, retain) SKShader *shader

    Discussion

    The default value is nil. If a shader is specified, then the shader is used to determine the output colors for any of the emitter’s particles.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.