Class

SCNScene

A scene graph—a hierarchy of nodes with attached geometries, lights, cameras and other attributes that together form a displayable 3D scene.

Overview

An SCNScene object represents a three-dimensional scene and its contents. To render a scene for display, see the SCNView, SCNLayer (macOS only), or SCNRenderer class, and the SCNSceneRenderer protocol, which defines properties and methods shared by those classes. The SCNScene class also provides an interface for reading and writing scene files.

Obtaining or Creating a Scene

Typically, you obtain a scene from a file created using external 3D authoring tools. If you include scene files in your app’s bundle resources directory, Xcode compresses them for optimal SceneKit loading performance. To load a scene file, use the init(named:), init(named:inDirectory:options:), or init(url:options:) method or an instance of the SCNSceneSource class.

Alternatively, you can create an empty scene with the scene method and populate it with content by creating a hierarchy of nodes and their contents and adding them as children of the scene’s rootNode object.

Saving a Scene

Use the the write(to:options:delegate:progressHandler:) method to save a scene to a file. The format of the file created depends on OS version and on the filename extension you specify:

  • In iOS 10.0, tvOS 10.0, watchOS 3.0, OS X v10.11, and later versions, specify the .scn extension to save a file in SceneKit’s native format. This format supports all features of SceneKit (including physics, constraints, and particle systems), and reading files in this format is faster than importing from other scene file formats.

  • In macOS only, specify the .dae extension to export in Digital Asset Exchange (DAE) format for use by other apps. Exported DAE files do not contain scene elements specific to SceneKit, such as physics bodies and fields, constraints, and particle systems.

  • Older versions of iOS and tvOS don’t include the write(to:options:delegate:progressHandler:) method, but you can still produce a file in .scn format through SceneKit’s support for the NSSecureCoding protocol. Use the NSKeyedArchiver class to serialize a scene and all its contents, and the NSKeyedUnarchiver class to load an archived scene.

Working with Animations in a Scene

A scene object determines the time base for any animations contained in its scene graph. You control scene timing attributes using the methods in Managing Scene Attributes and the constants listed in Scene Attributes.

Topics

Creating or Loading a Scene

init?(named: String)

Loads a scene from a file with the specified name in the app’s main bundle.

init?(named: String, inDirectory: String?, options: [SCNSceneSource.LoadingOption : Any]? = nil)

Loads a scene from a file with the specified name in a specific subdirectory of the app’s main bundle.

init(mdlAsset: MDLAsset)

Creates a scene from the specified Model I/O asset.

Managing Animated Effects in a Scene

var isPaused: Bool

A Boolean value that determines whether to run actions, animations, particle systems, and physics simulations in the scene graph.

Accessing Scene Contents

var rootNode: SCNNode

The root node of the scene graph.

var background: SCNMaterialProperty

A background to be rendered before the rest of the scene.

var lightingEnvironment: SCNMaterialProperty

A cube map texture that depicts the environment surrounding the scene’s contents, used for advanced lighting effects.

Managing Scene Attributes

func attribute(forKey: String)

Returns the scene attribute for the specified key.

func setAttribute(Any?, forKey: String)

Sets a scene attribute for the specified key.

Exporting a Scene File

protocol SCNSceneExportDelegate

Methods you can implement to participate in the process of exporting a scene to a file.

Adding Fog to a Scene

var fogStartDistance: CGFloat

The distance from a point of view at which the scene’s contents begin to be obscured by fog. Animatable.

var fogEndDistance: CGFloat

The distance from a point of view at which the scene’s contents are completely obscured by fog. Animatable.

var fogDensityExponent: CGFloat

The transition curve for the fog’s intensity between its start and end distances. Animatable.

var fogColor: Any

The color of the fog effect to be rendered with the scene. Animatable.

Working With Physics in the Scene

var physicsWorld: SCNPhysicsWorld

The physics simulation associated with the scene.

Working with Particle Systems in the Scene

func addParticleSystem(SCNParticleSystem, transform: SCNMatrix4)

Attaches a particle system to the scene, using the specified transform.

var particleSystems: [SCNParticleSystem]?

The particle systems attached to the scene.

func removeParticleSystem(SCNParticleSystem)

Removes a particle system attached to the scene.

func removeAllParticleSystems()

Removes any particle systems directly attached to the scene.

Constants

Scene Attributes

Attribute keys available in the options dictionary for the methods attribute(forKey:) and setAttribute(_:forKey:)

typealias SCNSceneExportProgressHandler

The signature for the block that SceneKit calls during scene export.

See Also

First Steps

class SCNView

A view for displaying 3D SceneKit content.