Contents

SCNParticleSystem

An object that animates and renders a system of small image sprites using a high-level simulation whose general behavior you specify.

Declaration

class SCNParticleSystem

Overview

Use particle systems to create effects such as smoke, rain, confetti, and fireworks.

How Particle Systems Work

Unlike SceneKit nodes and geometries, individual particles are not objects in a scene graph. Because a particle system can involve dozens or hundreds of particles, SceneKit uses a more efficient internal representation that stores and processes the data for all of a system’s particles in bulk.

Instead of accessing each particle to control its behavior or to make it interact with other scene content, you typically use properties of a particle system to control the aggregate behavior of particles. These properties cover several key aspects of the system’s behavior, as summarized below.

  • Appearance. SceneKit renders a texture image for each particle. Define the appearance of the particle system by specifying an image, its tint color, and rendering parameters such as blending mode. You can even specify an animated image sequence, creating effects like swarms of insects or multi-stage explosions.

  • Life span. SceneKit creates each particle at a location in the scene (also called an emitter), varies its position and appearance over a specified life span, then removes it from the scene. (Particle creation is also called birth or spawning, and particle removal is also called death.) The total count of particles on screen at any time is the product of the system’s birthRate and particleLifeSpan properties. Larger numbers of particles have a greater cost to rendering performance and power usage.

  • Emitter behavior. Use the emitterShape property to specify whether particles spawn from a single point in space or in the region defined by an SCNGeometry object. Use the emissionDuration property and related properties to vary particle birth over time, so that the system alternates between periods of spawning particles and periods of idle time.

  • Variation. Particle systems simulate realistic effects by randomly varying particle properties both at birth and over the lifetime of a particle. You can also add random variation to the life span of particles. Several particle system properties have an associated variation property that controls this randomization. For example, the particleSizeVariation property defines the width of an interval for randomizing the particleSize property.

  • Movement. Particles move according to a simple physics simulation—each has an initial direction, speed, angular velocity and acceleration, which SceneKit uses to animate the particle until it dies. You can create many realistic effects using these attributes alone. You can also add more complex behaviors by allowing particles to interact with scene geometry (colliderNodes), the scene’s physicsWorld simulation, or SCNPhysicsField objects.

In addition, you can also use the following features to add dynamic behaviors to a particle system, changing its appearance over time or making it interact with its environment.

  • Animations and property controllers. Like many SceneKit objects, the SCNParticleSystem class conforms to the SCNAnimatable protocol, so you can implicitly or explicitly animate changes to its properties. (For general background on animation, see Animating SceneKit Content.) When you animate changes to a particle system’s properties, these changes affect all particles in the system simultaneously.

To apply animations independently for individual particles, use an SCNParticlePropertyController object, which associates a CAAnimation object with a particle system property. With a property controller, you can use features of the Core Animation framework to create time-varying effects that apply to each particle in the system. Typically a Core Animation object varies a property with respect to time, but with a property controller you can also create animations that vary a property based on other input values, such as a particle’s distance from its initial location.

For example, consider a CAKeyframeAnimation object that animates a series of colors from white to yellow to red, and a particle system that simulates a flame. If you attach this animation to a particle system’s particleColor property, the resulting flame effect has a single color at any given moment, but that color changes over time. If you instead attach a property controller for the color property, the flame varies in color from its base to its tip—each particle starts out white, then fades to yellow and red as it rises.

  • Spawned particle systems. When you assign another SCNParticleSystem instance to one of the properties listed in Spawning Additional Particle Systems, SceneKit adds more particle systems to the scene based on the behavior of the original particle system. For example, if you have a particle system that simulates falling rain, you can use the systemSpawnedOnCollision property to add splashes where each raindrop strikes a surface.

  • Event handlers and particle modifiers. Because they specify behavior declaratively, animations, property controllers, and spawned systems provide easy configuration and high performance for most dynamic behaviors. To create behaviors not possible with these features, you can register event handler or particle modifier blocks that work directly with the bulk particle data SceneKit uses to animate a particle system.

Use the handle(_:forProperties:handler:) method to modify particle data in response to an event—particle birth, death, or collision. For example, you can use this option to make particles that change color after colliding with another object in the scene.

Use the methods listed in Modifying Particles Over Time to manage blocks that SceneKit calls for every rendered frame. Your block can modify particle properties in bulk, allowing you to change particle behavior precisely, but at a high risk to rendering performance.

Use the Xcode Particle System Editor to Experiment with Particle Systems

In most cases, you don’t need to configure a particle system directly in your app or game. Instead, you use Xcode to configure a particle system’s properties. As you change the behavior of the particle system, Xcode immediately provides an updated visual effect. When complete, Xcode archives the configured system into a file, which you can then include with your project’s bundle resources. Then, at runtime, your game uses this archive to instantiate a new particle system.

Using Xcode to create your particle systems has a few important advantages:

  • You can easily learn the capabilities of the particle system class.

  • You can experiment quickly 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.

  • You can attach a particle system to a node in the Xcode scene editor to preview the particle system in your scene.

To load a particle system from a file you created with Xcode, use the init(named:inDirectory:) method.

Topics

Creating a Particle System

Managing Particle Emission Timing

Managing Particle Emission Locations

Managing Particle Motion

Specifying Particle Appearance

Animating Particle Images

Simulating Physics for Particles

Spawning Additional Particle Systems

Managing Particle Rendering

Controlling Particle Simulation

Modifying Particles in Response to Particle System Events

Modifying Particles Over Time

Sample Code

Initializers

Instance Properties

See Also

Particle Systems