Framework

SpriteKit

Create 2D sprite-based games using an optimized animation system, physics simulation, and event-handling support.

Overview

SpriteKit is a graphics rendering and animation infrastructure that you can use to animate arbitrary textured images, otherwise known as sprites. SpriteKit provides a traditional rendering loop that alternates between determining the contents of and rendering frames. You determine the contents of the frame and how those contents change. SpriteKit does the work to render that frame efficiently using graphics hardware. SpriteKit is optimized for applying arbitrary animations or changes to your content. This design makes SpriteKit more suitable for games and apps that require flexibility in how animations are handled.

Sprite Content is Drawn by Presenting Scenes Inside a Sprite View

Animation and rendering is performed by an SKView object. You place this view inside a window, then render content to it. Because it is a view, its contents can be combined with other views in the view hierarchy.

Content in your game is organized into scenes, which are represented by SKScene objects. A scene holds sprites and other content to be rendered. A scene also implements per-frame logic and content processing. At any given time, the view presents one scene. As long as a scene is presented, its animation and per-frame logic are automatically executed.

To create a game or app using SpriteKit, you either subclasses the SKScene class or create a scene delegate to perform major game-related tasks. For example, you might create separate scene classes to display a main menu, the gameplay screen, and content displayed after the game ends. You can easily use a single SKView object in your window and switch between different scenes. When you switch scenes, you can use the SKTransition class to animate between the two scenes.

A Node Tree Defines What Appears in a Scene

The SKScene class is a descendant of the SKNode class. When using SpriteKit, nodes are the fundamental building blocks for all content, with the scene object acting as the root node for a tree of node objects. The scene and its descendants determine which content is drawn and how it is rendered.

Each node’s position is specified in the coordinate system defined by its parent. A node also applies other properties to its content and the content of its descendants. For example, when a node is rotated, all of its descendants are rotated also. You can build a complex image using a tree of nodes and then rotate, scale, and blend the entire image by adjusting the topmost node’s properties.

The SKNode class does not draw anything, but it applies its properties to its descendants. Each kind of drawable content is represented by a distinct subclass in SpriteKit. Some other node subclasses do not draw content of their own, but modify the behavior of their descendants. For example, you can use an SKEffectNode object to apply a Core Image filter to an entire subtree in the scene. By precisely controlling the structure of the node tree, you determine the order in which nodes are rendered.

All node objects are responder objects, descending either from UIResponder or NSResponder, so you can subclass any node class and create new classes that accept user input. The view class automatically extends the responder chain to include the scene’s node tree.

See SKNode reference for more information.

Textures Hold Reusable Graphical Data

Textures, represented as SKTexture objects, are shared images used to render sprites. Always use textures whenever you need to apply the same image to multiple sprites. Usually you create textures by loading image files stored in your app bundle. However, SpriteKit can also create textures for you at runtime from other sources, including Core Graphics images or even by rendering a node tree into a texture.

SpriteKit simplifies texture management by handling the lower-level code required to load textures and make them available to the graphics hardware. Texture management is automatically managed by SpriteKit. However, if your game uses a large number of images, you can improve its performance by taking control of parts of the process. Primarily, you do this by telling SpriteKit explicitly to load a texture.

A texture atlas is a group of related textures that are used together in your game. For example, you might use a texture atlas to store all of the textures needed to animate a character or all of the tiles needed to render the background of a gameplay level. SpriteKit uses texture atlases to improve rendering performance.

See SKTexture and SKTextureAtlas class references for more information.

Nodes Execute Actions to Animate Content

A scene’s contents are animated using actions. Every action is an object, defined by the SKAction class. You tell nodes to execute actions. Then, when the scene processes frames of animation, the actions are executed. Some actions are completed in a single frame of animation, while other actions apply changes over multiple frames of animation before completing. The most common use for actions is to animate changes to the node’s properties. For example, you can create actions that move a node, scale or rotate it, or make it transparent. However, actions can also change the node tree, play sounds, or even execute custom code.

Actions are very useful, but you can also combine actions to create more complex effects. You can create groups of actions that run simultaneously or sequences where actions run sequentially. You can cause actions to automatically repeat.

Scenes can also perform custom per-frame processing. You override the methods of your scene subclass to perform additional game tasks. For example, if a node needs to be moved every frame, you might adjust its properties directly every frame instead of using an action to do so.

See SKAction reference for more information.

Add Physics Bodies and Joints to Simulate Physics in Your Scene

Although you can control the exact position of every node in the scene, often you want these nodes to interact with each other, colliding with each other and imparting velocity changes in the process. You might also want to do things that are not handled by the action system, such as simulating gravity and other forces. To do this, you create physics bodies (SKPhysicsBody) and attach them to nodes in your scene. Each physics body is defined by shape, size, mass, and other physical characteristics. The scene defines global characteristics for the physics simulation in an attached SKPhysicsWorld object. You use the physics world to define gravity for the entire simulation, and to define the speed of the simulation.

When physics bodies are included in the scene, the scene simulates physics on those bodies. Some forces, such as friction and gravity, are applied automatically. Other forces can be applied automatically to multiple physics bodies by adding SKFieldNode objects to the scene. You can also directly affect a specific field body by modifying its velocity directly or by applying forces or impulses directly to it. The acceleration and velocity of each body is computed and the bodies collide with each other. Then, after the simulation is complete, the positions and rotations of the corresponding nodes are updated.

You have precise control over which physics effects interact with each other. For example, you can specify that a particular physics field node only affects a subset of the physics bodies in the scene. You also decide which physics bodies can collide with each other and separately decide which interactions cause your app to be called. You use these callbacks to add game logic. For example, your game might destroy a node when its physics body is struck by another physics body.

You can also use the physics world to find physics bodies in the scene and to connect physical bodies together using a joint (SKPhysicsJoint). Connected bodies are simulated together based on the kind of joint.

See Simulating Physics for more information.

Getting Started with SpriteKit

SpriteKit implements content as a hierarchical tree structure of nodes. A node tree consists of a scene node as the root node and other nodes that provide content. Each frame of a scene is processed and rendered to a view. The scene executes actions and simulates physics, both of which change the contents of the tree. Then the scene is rendered efficiently using SpriteKit.

To start learning SpriteKit, you should look at these classes in the following order, before moving on to other classes in the framework:

Creating Your First Scene

SpriteKit content is placed in a window, just like other visual content. SpriteKit content is rendered by the SKView class. The content that an SKView object renders is called a scene, which is an SKScene object. Scenes participate in the responder chain and have other features that make them appropriate for games.

Because SpriteKit content is rendered by a view object, you can combine this view with other views in the view hierarchy. For example, you can use standard button controls and place them above your SpriteKit view. Or, you can add interactivity to sprites to implement your own buttons; the choice is up to you. Later in this example, you’ll see how to implement interactivity on the scene.

An SKView can be added as a child to a UIView, or you can explicitly cast your view controller’s view to to a SceneKit view either through storyboards, using Custom Class, or in code. The following listing shows how you can override a view controller’s viewDidLoad() method to cast its view to an SKView:

Listing 1

Casting a view controller’s view to an SKView

override func viewDidLoad() {
    super.viewDidLoad()
    view = SKView()
}
var skView: SKView {
    return view as! SKView
}

With the SpriteKit view created, the next step in displaying content is to create a scene. Typically, you would subclass SKScene for each scene you require, but simplicity, the following code simply instantiates a new scene object that is presented by the view:

Listing 2

Creating and presenting a scene

let scene = SKScene(size: CGSize(width: 1024, height: 768))
override func viewWillAppear(_ animated: Bool) {
    skView.presentScene(scene)
}

To display content in SpriteKit, the relevant node is added to the scene, or a child of the scene. The final step in this example to display a label is to create an SKLabelNode and add it to the scene:

Listing 3

Add a label to the scene

let label = SKLabelNode(text: "SpriteKit")
label.position = CGPoint(x: scene.size.width / 2,
                         y: scene.size.height / 2)
scene.addChild(label)

Symbols

Displaying SpriteKit Content in Your App

Create the fundamental objects SpriteKit uses for representing and displaying content.

SKView

An object that displays SpriteKit content. This content is provided by an SKScene object.

SKScene

The root node for all Sprite Kit objects displayed in a view.

SKNode

The SKNode class is the fundamental building block of most SpriteKit content.

SKViewDelegate

Methods that allow dynamic control of an SKView object's render rate.

SKSceneDelegate

Methods your app can implement to participate in SpriteKit's animation loop.

Nodes That Draw Content

Generate visual nodes that can display shapes, textures, images and video.

SKSpriteNode

A node that draws a rectangular texture, image or color.

SKShapeNode

A node that renders a shape defined by a Core Graphics path.

SKLabelNode

A node that displays a text label.

SKVideoNode

A node that displays video content.

SKCropNode

A node that masks pixels drawn by its children so that only some are rendered to the parent’s frame buffer.

SKReferenceNode

A node that creates its children from an archived collection of other nodes.

Working with Textures

Use these classes to generate textures from image assets that can be used in a SpriteKit game or app.

SKTexture

A representation of an image for use in SpriteKit.

SKTextureAtlas

A collection of textures.

SKMutableTexture

A texture whose contents can be dynamically updated.

Building Content with Tiles

Use these classes to create large, detailed scenes with tiles. Tile maps offer better manageability and a lower memory overhead than using a single, large image as a background or manually adding individual images. SpriteKit’s tiles can be arranged in rectangular, hexagonal or isometric grids.

SKTileMapNode

A node used to render a 2D array of textured sprites.

SKTileDefinition

A class that describes a single type of tile that is used within a tile map.

SKTileGroupRule

A class that defines how tiles should be placed in a map.

SKTileGroup

A class that encapsulates a collection of related tile definitions that are designed to be pieced together within a tile map.

SKTileSet

A class that contains all the tile definitions available for use in a tile map.

Animating Content

SpriteKit includes a rich selection of objects that animate nodes and transition between scenes. Node animations can change the visual appearance of nodes, such position or orientation, or apply audio effects, such as changing the stereo position or applying reverb. These objects can also run inverse kinematic solvers and apply physics forces.

SKAction

An object that is executed by an SKNode to change its structure or content.

SKTransition

An SKTransition object is used to perform an animated transition between a SKScene object already presented by an SKView object and a new incoming scene.

Constraining Nodes

Constrain the position or orientation of nodes.

SKConstraint

A specification for constraining a node's position or rotation.

SKRange

The definition of a range of CGFloat values.

SKReachConstraints

A specification of the degree of freedom when solving inverse kinematics.

Warping Nodes

Distort nodes to achieve effects such as stretching and squashing with warp geometry.

SKWarpGeometry

A definition for a deformation of nodes that conform to SKWarpable.

SKWarpGeometryGrid

A definition for a grid based deformation of nodes that conform to SKWarpable.

SKWarpable

A protocol for objects that can be warped and animated by an SKWarpGeometry.

Cameras and Lighting

Control which parts of a scene are rendered and add lighting and shadows to scenes.

SKCameraNode

A node that controls camera movement, zoom and rotation.

SKLightNode

A node that adds lighting into a scene.

Playing Audio

Add positional audio with effects such as occlusion and reverb.

SKAudioNode

A node which adds positional audio to a scene.

Simulating Physics

Simulate physics in a scene. Use these objects to respond to collision and contact events, build systems of nodes with joints, such as pins and springs, and apply forces, such as gravity and magnetism.

The physics simulation in SpriteKit is performed by adding physics bodies to nodes in the scene. A physics body uses its node’s position and orientation to place itself in the simulation. It uses the node’s position and orientation to place itself in the simulation. Every physics body has other characteristics that define how the simulation operates on it. These include innate properties of the physical object, such as its mass and density, and also properties imposed on it, such as its velocity. These characteristics define how a body moves, how it is affected by forces in the simulation, and how it responds to collisions with other physics bodies.

Each time a scene computes a new frame of animation, it simulates the effects of forces and collisions on physics bodies connected to the node tree. It computes a final position, orientation, and velocity for each physics body. Then, the scene updates the position and rotation of each corresponding node.

To use physics in your game, you need to:

  • Attach physics bodies to nodes in the node tree and configure their physical properties. See SKPhysicsBody.

  • Define global characteristics of the scene’s physics simulation, such as gravity. See SKPhysicsWorld.

  • Where necessary to support your gameplay, set the velocity of physics bodies in the scene or apply forces or impulses to them. See SKFieldNode and SKPhysicsBody.

  • Decide whether physics bodies in the scene should be connected with each other. See SKPhysicsJoint and pinned property on SKPhysicsBody.

  • Define how the physics bodies in the scene interact when they come in contact with each other. See SKPhysicsContactDelegate.

  • Optimize your physics simulation to limit the number of calculations it must perform.

SpriteKit uses the International System of Units, also known as SI, or the meter-kilogram-second system. Where necessary, you may need to consult other reference materials online to learn more about the physics equations used by SpriteKit.

SKPhysicsWorld

An object which encapsulates a scene's physics simulation.

SKPhysicsBody

An object which adds physics simulation to a node.

SKPhysicsContact

A description of the contact between two physics bodies.

SKPhysicsContactDelegate

Methods your app can implement to respond when physics bodies come into contact.

SKPhysicsJoint

The abstract superclass for objects that connect physics bodies.

SKPhysicsJointFixed

A joint that fixes two physics bodies together.

SKPhysicsJointLimit

A joint that imposes a maximum distance between two physics bodies, as if they were connected by a rope.

SKPhysicsJointPin

A joint that pins together two physics bodies, allowing independent rotation.

SKPhysicsJointSliding

A joint that allows two physics bodies to slide along an axis.

SKPhysicsJointSpring

A joint that simulates a spring connecting two physics bodies.

SKFieldNode

A node that applies physics effects to a portion of the scene.

SKRegion

A definition of an arbitrary area.

Particle Systems

Create high performance particle systems to simulate fluids, smoke and fire.

SKEmitterNode

A node that creates and renders particles.

SKKeyframeSequence

An object which performs interpolation between values specified at different times (keyframes).

Working with Shaders

Leverage the power of shaders to add custom effects to nodes and particle systems.

SKShader

An object that allows nodes to be rendered or filtered with a custom OpenGL ES fragment shader.

SKAttribute

A specification for dynamic per-node data used with a custom shader.

SKAttributeValue

A container for dynamic shader data associated with a node.

SKUniform

A container for uniform shader data.

Integrating with Other Frameworks

Integrate SpriteKit with other frameworks such as SceneKit and Core Image.

SKEffectNode

A node that can apply Core Image filters or SKWarpGeometry distortions to its children.

SK3DNode

A node that renders a Scene Kit scene as a 2D image.

Other Reference

Structures

SKTileAdjacencyMask

An enumeration defining how neighboring tiles are automatically placed next to each other.