SKScene Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SpriteKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
SKScene.h

Overview

An SKScene object represents a scene of content in Sprite Kit. A scene is the root node in a tree of Sprite Kit nodes (SKNode). These nodes provide content that the scene animates and renders for display. To display a scene, you present it from an SKView object.

A scene calculates the contents of a new frame by processing the following actions in order:

  1. The scene calls its update: method.

  2. The scene executes actions on its children.

  3. The scene calls its didEvaluateActions method.

  4. The scene executes any physics simulations on physics bodies in the scene.

  5. The scene calls its didSimulatePhysics method.

Subclassing Notes

Creating scene subclasses is expected as the primary way to deliver gameplay. Your subclass usually:

For more information, see Sprite Kit Programming Guide.

Tasks

Initializing a Scene

Determining What Portion of the Scene Is Visible in the View

Setting the Background Color of a Scene

Converting Between View and Scene Coordinates

Presenting a Scene

Executing the Animation Loop

Working With Physics in the Scene

Properties

anchorPoint

The point in the view’s frame that corresponds to the scene’s origin.

@property(nonatomic) CGPoint anchorPoint
Discussion

When a scene is presented, the size and anchorPoint properties determine the portion of the scene’s coordinate space that is visible in the view.

You specify the value using the unit coordinate space. The default value is (0,0), which corresponds to the lower-left corner of the view’s frame rectangle.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

backgroundColor

The background color of the scene.

@property(retain, nonatomic) SKColor *backgroundColor
Discussion

The default value is a gray color (RGBA 0.15, 0.15, 0.15, 1.0).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

physicsWorld

The physics simulation associated with the scene. (read-only)

@property(readonly, nonatomic) SKPhysicsWorld *physicsWorld
Discussion

Every scene automatically creates a physics world object to simulate physics on nodes in the scene. You use this property to access the scene’s global physics properties, such as gravity. To add physics to a particular node, see physicsBody.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

scaleMode

Defines how the scene is mapped to the view that presents it.

@property(nonatomic) SKSceneScaleMode scaleMode
Discussion

It is possible for a scene’s size to differ from the size of the view it is presented in. The scale mode determines how the scene is mapped to the view. The possible values are listed in “Scene Scaling Modes”. The default value is SKSceneScaleModeFill.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

size

The dimensions of the scene in points.

@property(nonatomic) CGSize size
Discussion

When a scene is presented, the size and anchorPoint properties determine the portion of the scene’s coordinate space that is visible in the view.

If you set the size property to a new value, the scene’s didChangeSize: method is called. This property can also change if the scaleMode property is set to SKSceneScaleModeResizeFill and the presenting view is resized. After the scene’s size changes, future updates are rendered immediately at the new size.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

view

The view that is currently presenting the scene. (read-only)

@property(weak, readonly, nonatomic) SKView *view
Discussion

To present a scene, you call the presentScene: method or presentScene:transition: method on the SKView class. If the scene is not currently presented, this property holds nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

Class Methods

sceneWithSize:

Creates and returns a new scene object.

+ (instancetype)sceneWithSize:(CGSize)size
Parameters
size

The size of the scene in points.

Return Value

A new scene object.

Discussion

This class method allocates a new scene object and calls its initWithSize: initializer method.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

Instance Methods

convertPointFromView:

Converts a point from view coordinates to scene coordinates.

- (CGPoint)convertPointFromView:(CGPoint)point
Parameters
point

A point in view coordinates.

Return Value

The same point in the scene’s coordinate system.

Discussion

The scene must be presented in a view before calling this method.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

convertPointToView:

Converts a point from scene coordinates to view coordinates.

- (CGPoint)convertPointToView:(CGPoint)point
Parameters
point

A point in scene coordinates.

Return Value

The same point in the view’s coordinate system.

Discussion

The scene must be presented in a view before calling this method.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

didChangeSize:

Called whenever the scene’s size changes.

- (void)didChangeSize:(CGSize)oldSize
Parameters
oldSize

The old size of the scene, in points.

Discussion

This method is intended to be overridden in a subclass. Typically, you use this method to adjust the positions of nodes in the scene.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
SKScene.h

didEvaluateActions

Performs any scene-specific updates that need to occur after scene actions are evaluated.

- (void)didEvaluateActions
Discussion

Do not call this method directly; it is called exactly once per frame, so long as the scene is presented in a view and is not paused. By default, this method does nothing. Your scene subclass should override this method and perform any necessary updates to the scene.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

didMoveToView:

Called immediately after a scene is presented by a view.

- (void)didMoveToView:(SKView *)view
Parameters
view

The view that is presenting the scene.

Discussion

This method is intended to be overridden in a subclass. You can use this method to implement any custom behavior for your scene when it is about to be presented by a view. For example, you might use this method to create the scene’s contents.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

didSimulatePhysics

Performs any scene-specific updates that need to occur after physics simulations are performed.

- (void)didSimulatePhysics
Discussion

Do not call this method directly; it is called exactly once per frame, so long as the scene is presented in a view and is not paused. By default, this method does nothing. Your scene subclass should override this method and perform any necessary updates to the scene.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

initWithSize:

Initializes a new scene object.

- (instancetype)initWithSize:(CGSize)size
Parameters
size

The size of the scene in points.

Return Value

A newly initialized scene object.

Discussion

This is the class’s designated initializer method.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

update:

Performs any scene-specific updates that need to occur before scene actions are evaluated.

- (void)update:(NSTimeInterval)currentTime
Parameters
currentTime

The current system time.

Discussion

Do not call this method directly; it is called exactly once per frame, so long as the scene is presented in a view and is not paused. By default, this method does nothing. Your scene subclass should override this method and perform any necessary updates to the scene.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

willMoveFromView:

Called immediately before a scene is removed from a view.

- (void)willMoveFromView:(SKView *)view
Parameters
view

The view that is presenting the scene.

Discussion

This method is intended to be overridden in a subclass. You can use this method to implement any custom behavior for your scene when it is about to be removed from the view.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKScene.h

Constants

Scene Scaling Modes

The modes that determine how the scene’s area is mapped to the view that presents it.

typedef NS_ENUM(NSInteger,
   SKSceneScaleMode) {
   SKSceneScaleModeFill,
   SKSceneScaleModeAspectFill,
   SKSceneScaleModeAspectFit,
   SKSceneScaleModeResizeFill
}
Constants
SKSceneScaleModeFill

Each axis of the scene is scaled independently so that each axis in the scene exactly maps to the length of that axis in the view.

Available in iOS 7.0 and later.

Declared in SKScene.h.

SKSceneScaleModeAspectFill

The scaling factor of each dimension is calculated and the larger of the two is chosen. Each axis of the scene is scaled by the same scaling factor. This guarantees that the entire area of the view is filled, but may cause parts of the scene to be cropped.

Available in iOS 7.0 and later.

Declared in SKScene.h.

SKSceneScaleModeAspectFit

The scaling factor of each dimension is calculated and the smaller of the two is chosen. Each axis of the scene is scaled by the same scaling factor. This guarantees that the entire scene is visible, but may require letterboxing in the view.

Available in iOS 7.0 and later.

Declared in SKScene.h.

SKSceneScaleModeResizeFill

The scene is not scaled to match the view. Instead, the scene is automatically resized so that its dimensions always matches those of the view.

Available in iOS 7.0 and later.

Declared in SKScene.h.