SKNode Class Reference

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

Overview

The SKNode class is the fundamental building block of most Sprite Kit content. All visual elements in a Sprite Kit-based game are drawn using predefined SKNode subclasses.

Table 1 describes the node subclasses provided in Sprite Kit.

Table 1  Node subclasses

Class

Description

SKSpriteNode

A node that draws a textured sprite.

SKVideoNode

A node that plays video content.

SKLabelNode

A node that renders a text string.

SKShapeNode

A node that renders a shape based on a Core Graphics path.

SKEmitterNode

A node that creates and renders particles.

SKCropNode

A node that crops its child nodes using a mask.

SKEffectNode

A node that applies a Core Image filter to its child nodes.

Characteristics of Nodes

Nodes are organized hierarchically into node trees, similar to how views and subviews work. Most commonly, a node tree is defined with a scene node (SKScene) as the root node and other content nodes as descendants. The scene node runs an animation loop that processes actions on the nodes, simulates physics, and then renders the contents of the node tree for display.

Every node in a node tree provides a coordinate system to its children. After a child is added to the node tree, it is positioned inside its parent’s coordinate system by setting its position properties. A node’s coordinate system can be scaled and rotated by changing its xScale, yScale, and zRotation properties. When a node’s coordinate system is scaled or rotated, this transformation is applied both to the node’s own content and to that of its descendants.

The SKNode class does not perform any drawing of its own. However, many SKNode subclasses render visual content and so the SKNode class understands some visual concepts:

  • The frame property provides the bounding rectangle for a node’s visual content, modified by the scale and rotation properties. The frame is non-empty if the node’s class draws content. Each node subclass determines the size of this content differently. In some subclasses, the size of the node’s content is declared explicitly, such as in the SKSpriteNode class. In other subclasses, the content size is calculated implicitly by the class using other object properties. For example, a SKLabelNode object determines its content size using the label’s message text and font characteristics.

  • A node’s accumulated frame, retrieved by calling the calculateAccumulatedFrame method, is the largest rectangle that includes the frame of the node and the frames of all its descendants.

  • Other properties, such as the alpha and hidden properties, affect how the node and its descendants are drawn.

All nodes are responder objects that can respond directly to user interaction with the node onscreen. You can also convert between coordinate systems and perform hit testing to determine which nodes a point lies in. You can also perform intersections between nodes in the tree to determine if their physical areas overlap.

Any node in the tree may run actions, which are used to animate the properties of a node, add or remove nodes, play sounds or other custom tasks. Actions are the heart of the animation system in Sprite Kit.

A node can support a physics body, which is an object that simulates the physical properties of the object. When a node has a physics body, the physics simulation automatically computes a new position for the physics body and then moves and rotates the node to match that position.

Subclassing Notes

When you subclass SKNode or any of its subclasses, if you add properties to the class that need to be archived, you must implement the NSCoding protocol on your subclasses. See Archives and Serializations Programming Guide.

Unlike views, you cannot create SKNode subclasses that perform custom drawing.

Tasks

Creating a New Node

Inspecting the Node’s Position

Setting a Node’s Scaling and Rotation

Inspecting a Node’s Visibility

Determining Whether a Node Supports User Interaction

Working with Node Trees

Naming Nodes

Running Actions

Adding Physics to a Node

Converting To and From the Node’s Coordinate System

Determining If a Point Lies in a Node

Performing Node Intersections

Storing Custom Node Data

Properties

alpha

The transparency value applied to the node’s contents.

@property(nonatomic) CGFloat alpha
Discussion

The default value is 1.0.

The SKNode class does not perform drawing, but many of its subclasses do. When a node or any of its descendants are drawn, the alpha component of each pixel is multiplied by the node’s alpha property and then clamped to the range 0.0-1.0. This modified alpha value is used to blend the pixel into the framebuffer. Subclasses that render content define properties that determine the blending operations used in conjunction with the alpha value to blend pixels into the parent’s framebuffer.

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

children

The node’s children. (read-only)

@property(readonly, nonatomic) NSArray *children
Discussion

The objects in this array are all SKNode objects.

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

frame

A rectangle in the parent’s coordinate system that contains the node’s content, ignoring the node’s children. (read-only)

@property(readonly, nonatomic) CGRect frame
Discussion

The frame is the smallest rectangle that contains the node’s content, taking into account the node’s xScale, yScale, and zRotation properties. Not all nodes contain content of their own.

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

hidden

A Boolean value that determines whether a node and its descendants are rendered.

@property(getter=isHidden, nonatomic) BOOL hidden
Discussion

When hidden, a node and its descendants are not rendered. However, they still exist in the scene and continue to interact in other ways. For example, the node’s actions still run and the node can still be intersected with other nodes. The default value is NO.

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

name

The node’s assignable name.

@property(copy, nonatomic) NSString *name
Discussion

Used to assign a name to a node for later reference. When choosing a name for a node, you should decide whether each node gets a unique name or whether some nodes will share a common name. If you give the node a unique name, you can find the node later by calling the childNodeWithName: method. If a name is shared by multiple nodes, the name usually means that these are all a similar object type in your game. In this case, you can iterate over those objects by calling the enumerateChildNodesWithName:usingBlock: method.

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

parent

The node’s parent node. (read-only)

@property(readonly, nonatomic) SKNode *parent
Discussion

If the node is not in a node tree, the value is nil.

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

paused

A Boolean value that determines whether actions on the node and its descendants are processed.

@property(getter=isPaused, nonatomic) BOOL paused
Discussion

If the value is YES, the node (and all of its descendants) are skipped when a scene processes actions.

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

physicsBody

The physics body associated with the node.

@property(retain, nonatomic) SKPhysicsBody *physicsBody
Discussion

The default value is nil, which indicates that the node does not participate in the physics simulation at all. If a physics body is provided, then when the scene’s physics are simulated, the physics body updates the node’s position and rotates the node.

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

position

The position of the node in its parent's coordinate system.

@property(nonatomic) CGPoint position
Discussion

The default value is (0.0,0.0).

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

scene

The scene node that contains the node. (read-only)

@property(readonly, nonatomic) SKScene *scene
Discussion

If the node is not embedded in a scene, the value is nil.

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

speed

A speed modifier applied to all actions executed by a node and its descendants.

@property(nonatomic) CGFloat speed
Discussion

The default value is 1.0, which means that all actions run at their normal speed. If you set a different speed, time appears to run faster or slower for all actions executed on the node and its descendants. For example, if you set a speed value of 2.0, actions run twice as fast.

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

userData

A dictionary containing arbitrary data.

@property(retain, nonatomic) NSMutableDictionary *userData
Discussion

You use this property to store your own data in a node. For example, you might store game-specific data about each node to use inside your game logic. This can be a useful alternative to creating your own node subclasses to hold game data.

Sprite Kit does not do anything with the data stored in the node. However, the data is archived when the node is archived.

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

userInteractionEnabled

A Boolean value that indicates whether the node receives touch events.

@property(getter=isUserInteractionEnabled) BOOL userInteractionEnabled
Discussion

The default value is NO.

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

xScale

A scaling factor that multiplies the width of a node and its children.

@property(nonatomic) CGFloat xScale
Discussion

The xScale property scales the width of the node and all of its descendants. The scale value affects how a node’s frame is calculated, its hit test area, how it is drawn, and other similar characteristics. The default value is 1.0.

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

yScale

A scaling factor that multiplies the height of a node and its children.

@property(nonatomic) CGFloat yScale
Discussion

The yScale property scales the height of the node and all of its descendants. The scale value affects how a node’s frame is calculated, its hit test area, how it is drawn, and other similar characteristics. The default value is 1.0.

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

zPosition

The height of the node relative to its parent.

@property(nonatomic) CGFloat zPosition
Discussion

The default value is 0.0. The positive z axis is projected toward the viewer so that nodes with larger z values are closer to the viewer. When a node tree is rendered, the height of each node (in absolute coordinates) is calculated and then all nodes in the tree are rendered from smallest z value to largest z value. If multiple nodes share the same z position, those nodes are sorted so that parent nodes are drawn before their children, and siblings are rendered in the order that they appear in their parent’s children array. Hit-testing is processed in the opposite order.

The SKView class’s ignoresSiblingOrder property controls whether node sorting is enabled for nodes at the same z position.

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

zRotation

The Euler rotation about the z axis (in radians).

@property(nonatomic) CGFloat zRotation
Discussion

The default value is 0.0, which indicates no rotation. A positive value indicates a counterclockwise rotation. When the coordinate system is rotated, it affects the node and its descendants. The rotation affects the node’s frame property, hit testing, rendering, and other similar characteristics.

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

Class Methods

node

Creates a new node.

+ (instancetype)node
Return Value

A newly initialized node.

Discussion

The SKNode class does not draw or perform any tasks directly, so it is more common to instantiate a node subclass instead. However, you might create an SKNode object to organize other related nodes in the node tree.

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

Instance Methods

actionForKey:

Returns an action associated with a specific key.

- (SKAction *)actionForKey:(NSString *)key
Parameters
key

A string that uniquely identifies a action.

Return Value

If an action exists that matches the key, the action object is returned. Otherwise, nil is returned.

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

addChild:

Adds a node to the end of the receiver’s list of child nodes.

- (void)addChild:(SKNode *)node
Parameters
node

The node to add.

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

calculateAccumulatedFrame

Calculates a rectangle in the parent’s coordinate system that contains the content of the node and all of its descendants.

- (CGRect)calculateAccumulatedFrame
Discussion

The frame takes into the account the cumulative effect of the xScale, yScale, and zRotation properties of each node in the subtree.

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

childNodeWithName:

Searches the children of the receiving node for a node with a specific name.

- (SKNode *)childNodeWithName:(NSString *)name
Parameters
name

The name to search for.

Return Value

If a node object with that name is found, the method returns the node object. Otherwise, it returns nil.

Discussion

If more than one child share the same name, the earliest node in the child array is returned.

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

containsPoint:

Returns a Boolean value that indicates whether a point lies inside the node’s bounding box.

- (BOOL)containsPoint:(CGPoint)p
Parameters
p

A point in the node’s coordinate system.

Return Value

YES if the point lies inside the node’s bounding box; otherwise NO.

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

convertPoint:fromNode:

Converts a point from the coordinate system of another node in the node tree to the coordinate system of this node.

- (CGPoint)convertPoint:(CGPoint)point fromNode:(SKNode *)node
Parameters
point

A point in the other node’s coordinate system.

node

Another node in the same node tree as this node.

Return Value

The same point converted to this node’s coordinate system.

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

convertPoint:toNode:

Converts a point in this node’s coordinate system to the coordinate system of another node in the node tree.

- (CGPoint)convertPoint:(CGPoint)point toNode:(SKNode *)node
Parameters
point

A point in this node’s coordinate system.

node

Another node in the same node tree as this node.

Return Value

The same point converted to the other node’s coordinate system.

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

enumerateChildNodesWithName:usingBlock:

Search the children of the receiving node to perform processing for nodes which share a name.

- (void)enumerateChildNodesWithName:(NSString *)name usingBlock:(void (^)(SKNode *node, BOOL *stop))block
Parameters
name

The name to search for.

block

A block to execute on nodes that match the name parameter. The block takes the following arguments:

node

A node that matches the name.

stop

A pointer to a Boolean variable. Your block can set this to YES to terminate the enumeration.

Discussion

This method enumerates the child array in order, searching for nodes whose name matches the search parameter. The block is called once for each node that matches the name parameter.

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

hasActions

Returns a Boolean value that indicates whether the node is executing actions.

- (BOOL)hasActions
Return Value

YES if the node has any executing actions, otherwise NO.

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

inParentHierarchy:

Returns a Boolean value that indicates whether the node is a descendant of the target node.

- (BOOL)inParentHierarchy:(SKNode *)parent
Parameters
parent

An SKNode object to test against.

Return Value

YES if the node is a descendant of the parent node, otherwise NO.

Discussion

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

insertChild:atIndex:

Inserts a child into a specific position in the receiver’s list of child nodes.

- (void)insertChild:(SKNode *)node atIndex:(NSInteger)index
Parameters
node

The node to add.

index

The position in the array to insert the node.

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

intersectsNode:

Returns a Boolean value that indicates whether this node intersects the specified node.

- (BOOL)intersectsNode:(SKNode *)node
Parameters
node

Another node in the same node tree.

Return Value

YES if the two nodes intersect; otherwise NO.

Discussion

The two nodes are considered to intersect if their frames intersect. The children of both nodes are ignored in this test.

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

nodeAtPoint:

Returns the deepest descendant that intersects a point.

- (SKNode *)nodeAtPoint:(CGPoint)p
Parameters
p

A point in the node’s coordinate system.

Return Value

A descendant in the subtree that intersects the point, or the receiver if no nodes intersect the point. If multiple descendants intersect the point, then the deepest node in the tree is returned. If multiple nodes are at the same level, the intersecting node with the smallest z position is returned.

Discussion

A point is considered to be in a node if it lies inside the rectangle returned by the calculateAccumulatedFrame method.

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

nodesAtPoint:

Returns an array of all descendants that intersect a point.

- (NSArray *)nodesAtPoint:(CGPoint)p
Parameters
p

A point in the node’s coordinate system.

Return Value

An array of all SKNode objects in the subtree that intersect the point. If no nodes intersect the point, an empty array is returned.

Discussion

A point is considered to be in a node if it lies inside the rectangle returned by the calculateAccumulatedFrame method.

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

removeActionForKey:

Removes an action associated with a specific key.

- (void)removeActionForKey:(NSString *)key
Parameters
key

A string that uniquely identifies an action.

Discussion

If an action is found that matches the key, it is removed from the node.

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

removeAllActions

Ends and removes all actions from the node.

- (void)removeAllActions
Discussion

When an action is removed from the node, any remaining animation the action would perform is skipped; however, previous changes are not reverted. It is possible that an action may make a final change to the scene when removed; if so, it is documented for the specific action in SKAction Class Reference.

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

removeAllChildren

Removes all of the node’s children.

- (void)removeAllChildren
Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
SKNode.h

removeChildrenInArray:

Removes a list of children from the receiving node.

- (void)removeChildrenInArray:(NSArray *)nodes
Parameters
nodes

An array of SKNode objects that are all children of the receiving node.

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

removeFromParent

Removes the receiving node from its parent.

- (void)removeFromParent
Availability
  • Available in iOS 7.0 and later.
Declared In
SKNode.h

runAction:

Adds an action to the list of actions executed by the node.

- (void)runAction:(SKAction *)action
Parameters
action

The action to perform.

Discussion

The new action is processed the next time the scene’s animation loop is processed.

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

runAction:completion:

Adds an action to the list of actions executed by the node. Your block is called when the action completes.

- (void)runAction:(SKAction *)action completion:(void (^)(void))block
Parameters
action

The action to perform.

block

A completion block called when the action completes.

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

runAction:withKey:

Adds an identifiable action to the list of actions executed by the node.

- (void)runAction:(SKAction *)action withKey:(NSString *)key
Parameters
action

The action to perform.

key

A unique key used to identify the action.

Discussion

This method is identical to runAction:, but the action is stored so that it can be retrieved later. If an action using the same key is already running, it is removed before the new action is added.

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

setScale:

Sets the xScale and yScale properties of the node.

- (void)setScale:(CGFloat)scale
Parameters
scale

The new value to use for the node’s xScale and yScale properties.

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

Constants

Node Blending Modes

The modes that describe how the source and destination pixel colors are used to calculate the new destination color.

typedef NS_ENUM(NSInteger,
   SKBlendMode) {
   SKBlendModeAlpha        = 0,
   SKBlendModeAdd          = 1,
   SKBlendModeSubtract     = 2,
   SKBlendModeMultiply     = 3,
   SKBlendModeMultiplyX2   = 4,
   SKBlendModeScreen       = 5,
   SKBlendModeReplace      = 6,
}
Constants
SKBlendModeAlpha

The source and destination colors are blended by multiplying the source alpha value.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeAdd

The source and destination colors are added together.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeSubtract

The source color is subtracted from the destination color.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeMultiply

The source color is multiplied by the destination color.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeMultiplyX2

The source color is multiplied by the destination color and then doubled.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeScreen

The source color is added to the destination color times the inverted source color.

Available in iOS 7.0 and later.

Declared in SKNode.h.

SKBlendModeReplace

The source color replaces the destination color.

Available in iOS 7.0 and later.

Declared in SKNode.h.