Framework

SceneKit

Create 3D games and add 3D content to apps using high-level scene descriptions. Easily add animations, physics simulation, particle effects, and realistic physically based rendering.

Overview

SceneKit combines a high-performance rendering engine with a descriptive API for import, manipulation, and rendering of 3D assets. Unlike lower-level APIs such as Metal and OpenGL that require you to implement in precise detail the rendering algorithms that display a scene, SceneKit only requires descriptions of your scene’s contents and the actions or animations you want it to perform.

Getting Started with SceneKit

SceneKit implements content as a hierarchical tree structure of nodes, also known as scene graph. A scene consists of a root node, which defines a coordinate space for the world of the scene, and other nodes that populate the world with visible content. SceneKit displays scenes in a view, processing the scene graph and performing animations before efficiently rendering each frame on the GPU.

Before working with SceneKit, you should be familiar with basic graphics concepts such as coordinate systems and the mathematics of three-dimensional geometry. SceneKit uses a right-handed coordinate system where (by default) the direction of view is along the negative z-axis, as illustrated in Figure 1.

Figure 1

SceneKit coordinate system

Animating SceneKit Content

SceneKit animation support is based on the Core Animation framework. (For background on Core Animation, read Core Animation Programming Guide.) Several SceneKit classes define animatable properties—you can create animations that transition smoothly between two values of the property. For example, animating a node’s opacity property fades the node’s visible content in or out. You can create animations implicitly or explicitly.

You create an animation implicitly by changing the value of an animatable property. SceneKit automatically combines all changes you make to a scene during one pass through the run loop into a single atomic operation called a transaction, represented by the SCNTransaction class. The default transaction’s duration is zero, so the changes you make to animatable properties occur immediately. However, if you increase the transaction’s animation duration, all changes to animatable properties automatically animate. Implicit animation is useful when you want to quickly animate a one-time change or animate several property changes together without writing a lot of animation code, as in Listing 1 below. For more details on implicit animation, see SCNTransaction.

Listing 1

Implicit animation that makes a block of text fall out of the scene while fading away

- (IBAction)fallAndFade:(id)sender
{
    [SCNTransaction setAnimationDuration:1.0];
    _textNode.position = SCNVector3Make(0.0, -10.0, 0.0);
    _textNode.opacity = 0.0;
}

For more complex animations, you can explicitly create an animation object and attach it to the scene element being animated. To explicitly create an animation, you choose a CAAnimation subclass for the type of animation you want to create, specify the property to be animated using key-value coding, then set animation parameters. You then set the animation in motion by attaching it to one or more elements of your scene, as shown in Listing 2. Using different Core Animation classes you can combine or sequence several animations or create animations that interpolate a property’s value between several keyframe values. For details on creating animation objects, see Core Animation Programming Guide. For details on attaching animations to SceneKit objects, see SCNAnimatable.

Listing 2

Explicit animation to vary the 3D extrusion depth of a block of text

CABasicAnimation *animation = [CABasicAnimation animationWithKeyPath:@"geometry.extrusionDepth"];
animation.fromValue = @0.0;
animation.toValue = @100.0;
animation.duration = 1.0;
animation.autoreverses = YES;
animation.repeatCount = INFINITY;
[_textNode addAnimation:animation forKey:@"extrude"];

SceneKit also uses CAAnimation objects for animations created using external 3D authoring tools and saved in scene files. For example, an artist might create a game character with animations for walking, jumping, and other actions. You incorporate these animations into your game by loading animation objects from the scene file using the SCNSceneSource class and attaching them to the SCNNode object that represents the game character.

Symbols

Building 3D Scenes

SCNScene

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

SCNNode

A structural element of a scene graph, representing a position and transform in a 3D coordinate space, to which you can attach geometry, lights, cameras, or other displayable content.

SCNReferenceNode

A scene graph node that serves as a placeholder for content to be loaded from a separate scene file.

SCNCamera

A set of camera attributes that can be attached to a node to provide a point of view for displaying the scene.

SCNLight

A light source that can be attached to a node to illuminate the scene.

SCNMaterial

A set of shading attributes that define the appearance of a geometry's surface when rendered.

SCNMaterialProperty

A container for the color or texture of one of a material’s visual properties.

SCNBoundingVolume

Properties for measuring an object's location and size, expressed as either a box or a sphere.

Working with Geometry

SCNGeometry

A three-dimensional shape (also called a model or mesh) that can be displayed in a scene, with attached materials that define its appearance.

SCNGeometrySource

A container for vertex data forming part of the definition for a three-dimensional object, or geometry.

SCNGeometryElement

A container for index data describing how vertices connect to define a three-dimensional object, or geometry.

SCNLevelOfDetail

An object that defines alternate resolutions for a geometry that SceneKit can automatically substitute to improve rendering performance.

SCNMorpher

An object that manages smooth transitions between a node's base geometry and one or more target geometries.

Built-in Geometry Types

SCNText

A geometry based on a string of text, optionally extruded to create a three-dimensional object.

SCNShape

A geometry based on a two-dimensional path, optionally extruded to create a three-dimensional object.

SCNBox

A six-sided polyhedron geometry whose faces are all rectangles, optionally with rounded edges and corners.

SCNCapsule

A right circular cylinder geometry whose ends are capped with hemispheres.

SCNCone

A right circular cone or frustum geometry.

SCNCylinder

A right circular cylinder geometry.

SCNFloor

An infinite plane that can optionally display a reflection of the scene above it.

SCNPlane

A rectangular, one-sided plane geometry of specified width and height.

SCNPyramid

A right rectangular pyramid geometry.

SCNSphere

A sphere (or ball or globe) geometry.

SCNTorus

A torus, or ring-shaped geometry.

SCNTube

A tube or pipe geometry—a right circular cylinder with a circular hole along its central axis.

Displaying 3D Scenes

SCNView

A view for displaying 3D SceneKit content.

SCNLayer

A Core Animation layer that renders a SceneKit scene as its content.

SCNRenderer

A renderer for displaying SceneKit scene in an an existing Metal workflow or OpenGL context.

SCNSceneRenderer

Methods and properties common to the SCNView, SCNLayer and SCNRenderer classes.

SCNSceneRendererDelegate

Methods your app can implement to participate in SceneKit’s animation loop or perform additional rendering.

SCNHitTestResult

Detailed information about a result from searching for elements of a scene located at a specified point, or along a specified line segment (or ray).

Animating 3D Content

SCNTransaction

The SCNTransaction class defines SceneKit’s mechanism for batching scene graph modifications into atomic updates. You use SCNTransaction class methods to control the animation that results from changing animatable properties in the scene graph and to combine sets of changes into nested transactions.

SCNAnimatable

The common interface for attaching animations to nodes, geometries, materials, and other SceneKit objects.

SCNAnimationEvent

A container for a closure to be executed at a specific time during playback of an animation.

SCNAction

A simple, reusable animation that changes attributes of any node you attach it to.

SCNActionable

Methods for running actions on nodes.

SCNSkinner

An object that manages the relationship between skeletal animations and the nodes and geometries they animate.

Simulating Physics

SCNPhysicsWorld

The global simulation of collisions, gravity, joints, and other physics effects in a scene.

SCNPhysicsBody

A set of physics simulation attributes attached to a scene graph node.

SCNPhysicsShape

An abstraction of a physics body’s solid volume for use in tuning or optimizing collision detection.

SCNPhysicsContactDelegate

Methods you can implement to respond when a contact or collision occurs between two physics bodies in a scene.

SCNPhysicsContact

Detailed information about a contact between two physics bodies in a scene’s physics simulation.

SCNPhysicsField

An object that applies forces, such as gravitation, electromagnetism, and turbulence, to physics bodies within a certain area of effect.

SCNPhysicsBehavior

The abstract superclass for joints, vehicle simulations, and other high-level behaviors that incorporate multiple physics bodies.

SCNPhysicsHingeJoint

A physics behavior that connects two bodies and allows them to pivot around each other on a single axis.

SCNPhysicsSliderJoint

A physics behavior that connects two bodies and allows them to slide against each other and rotate around their connecting points.

SCNPhysicsBallSocketJoint

A physics behavior that connects two physics bodies and allows them to pivot around each other in any direction.

SCNPhysicsVehicle

A physics behavior that modifies a physics body to behave like a car, motorcycle, or other wheeled vehicle.

SCNPhysicsVehicleWheel

The appearance and physical characteristics of an individual wheel associated with an physics vehicle behavior.

Particle Systems

SCNParticleSystem

Manages the animation and rendering of a system of small image sprites, or particles, using a high-level simulation whose general behavior you specify.

SCNParticlePropertyController

An animation for a single property of the individual particles rendered by a particle system.

Playing Audio

SCNAudioSource

A simple, reusable audio source—music or sound effects loaded from a file—for use in positional audio playback.

SCNAudioPlayer

A controller for playback of a positional audio source in a SceneKit scene.

Constraints

SCNConstraint

The abstract superclass for objects that automatically adjust the position, rotation, or scale of a node based on rules you define.

SCNBillboardConstraint

A constraint that orients a node to always point toward the current camera.

SCNIKConstraint

A constraint that applies inverse kinematics to make a chain of nodes “reach” toward a target point.

SCNLookAtConstraint

A constraint that orients a node to always point toward a specified other node.

SCNTransformConstraint

A constraint that runs a specified closure to compute a new transform (position, rotation, and scale) for each node that the constraint affects.

Customizing Rendering

SCNShadable

Methods for customizing SceneKit's rendering of geometry and materials using Metal or OpenGL shader programs.

SCNProgram

A complete Metal or OpenGL shader program that replaces SceneKit's rendering of a geometry or material.

SCNProgramDelegate

The interface for tracking errors that occur when compiling shader source code.

SCNBufferStream

An object that manages a Metal buffer used by a custom shader program.

SCNTechnique

A specification for augmenting or postprocessing SceneKit's rendering of a scene using additional drawing passes with custom Metal or OpenGL shaders.

SCNTechniqueSupport

The common interface for SceneKit objects that support multipass rendering using SCNTechnique objects.

SCNNodeRendererDelegate

Methods you can implement to use your own custom Metal or OpenGL drawing code to render content for a node.

Importing and Exporting Scene Content

SCNSceneSource

Manages the data-reading tasks associated with loading scene contents from a file or data.

SCNSceneExportDelegate

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

Extended Types

CAAnimation

The abstract superclass for Core Animation animations.

CATransform3D

Defines the standard transform matrix used throughout Core Animation.

MDLAsset

An indexed container for 3D objects and associated information, such as transform hierarchies, meshes, cameras, and lights.

MDLCamera

A point of view for rendering a 3D scene, along with a set of parameters describing an intended appearance for rendering.

MDLLight

The abstract superclass for objects that describe light sources in a scene.

MDLMaterial

A collection of material properties that together describe the intended surface appearance for rendering a 3D object.

MDLMesh

A container for vertex buffer data to be used in rendering a 3D object.

MDLObject

The base class for objects that are part of a 3D asset, including meshes, cameras, and lights.

MDLSubmesh

A container for index buffer data and material information to be used in rendering all or part of a 3D object.

NSValue

An NSValue object is a simple container for a single C or Objective-C data item. It can hold any of the scalar types such as int, float, and char, as well as pointers, structures, and object id references. Use this class to work with such data types in collections (such as NSArray and NSSet), Key-value coding, and other APIs that require Objective-C objects. NSValue objects are always immutable.

Reference

SceneKit Constants

Constants used throughout the SceneKit framework.

SceneKit Data Types
SceneKit Functions

Functions used throughout the SceneKit framework.

SceneKit Enumerations

Structures

SCNBillboardAxis

Options for locking the orientation of nodes affected by a billboard constraint.

SCNDebugOptions

Options for drawing overlays with SceneKit content that can aid in debugging, used with the debugOptions property.

SCNPhysicsCollisionCategory

Default values for a physics body’s categoryBitMask and collisionBitMask properties.