Class

SKConstraint

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

Overview

An SKConstraint object describes a mathematical constraint on a node’s position or orientation. Constraints are attached to nodes; after a scene processes any actions and physics interactions, it applies constraints attached to nodes in its node tree. Use constraints to ensure that certain relationships are true before a scene is rendered. For example, you might use a constraint to:

  • Change a node’s zRotation property so that it always points at another node or a position in the scene.

  • Keep a node within a specified distance of another node or a point in the scene.

  • Keep a node inside a specified rectangle.

  • Restrict the zRotation property of a node so that it has a more limited rotation range of motion.

To use constraints, create an NSArray object that contains one or more constraint objects and assign the array to a node’s constraints property. When the scene is evaluated, the constraints on a node are executed in the order they appear in the constraints array.

Once created, a constraint can’t be changed. However, you can selectively disable or enable a constraint by setting its enabled property. You can also use the referenceNode property to convert positions to the referenced coordinate system before applying the constraint.

Symbols

Creating Position Constraints

Position constraints allow you to constrain nodes so that they are locked in place (positionX(_:y:)), are only able to move vertically (positionX(_:)), or are only able to move vertically (positionY(_:)).

Listing 1 shows how you can create a node with an attached physics body that is affected by a noise field. The node moves with the noise but is constrained to a rectangular region between 300 and 340 points on both the horizontal and vertical axes.

scene.physicsWorld.gravity = CGVector(dx: 0, dy: 0)
   
let noiseField = SKFieldNode.noiseField(withSmoothness: 1, animationSpeed: 0.1)
scene.addChild(noiseField)
     
let node = SKShapeNode(circleOfRadius: 10)
node.physicsBody = SKPhysicsBody(circleOfRadius: 10)
scene.addChild(node)
     
let range = SKRange(lowerLimit: 300, upperLimit: 340)

let lockToCenter = SKConstraint.positionX(range, y: range)

node.constraints = [ lockToCenter ]

class func positionX(SKRange)

Creates a constraint that restricts the x-coordinate of a node’s position.

class func positionY(SKRange)

Creates a constraint that restricts the y-coordinate of a node’s position.

class func positionX(SKRange, y: SKRange)

Creates a constraint that restricts both coordinates of a node’s position.

Creating Orientation Constraints

A common use for orientation constraints is to make a look-at constraint. For example, you may create a look-at constraint to make a pair of eyes follow a moving object or to have a rocket point in the direction of its target.

Listing 2 shows how to create a constraint to make a sprite node named pointer always points towards a circular shape node named target. The texture assigned to pointer is an upwards pointing arrow and, because SpriteKit's angular coordinates have their origin at the 3 o'clock position, the orient constraint has an offset of 90° (pi / 2 radians) so that the arrow is correctly oriented towards the target.

Listing 2

Creating a look at constraint

let target = SKShapeNode(circleOfRadius: 10)
target.position = CGPoint(x: 100, y: 100)
scene.addChild(target)
    
let pointer = SKSpriteNode(imageNamed: "arrowUp.png")
pointer.position = CGPoint(x: 200, y: 200)
scene.addChild(pointer)
    
let lookAtConstraint = SKConstraint.orient(to: target,
                                           offset: SKRange(constantValue: -CGFloat.pi / 2))
pointer.constraints = [ lookAtConstraint ]

A further orientation constraint, zRotation(_:), can be used in combination with the look-at constraint shown above to limit rotation. By adding the code from Listing 3, the arrow's rotation is limited so that it will never point downwards:

let limitLookAt = SKConstraint.zRotation(SKRange(lowerLimit: -CGFloat.pi / 2,
                                                 upperLimit: CGFloat.pi / 2))
      
pointer.constraints = [ lookAtConstraint, limitLookAt ]

class func orient(to: SKNode, offset: SKRange)

Creates a constraint that forces a node to rotate to face another node.

class func orient(to: CGPoint, offset: SKRange)

Creates a constraint that forces a node to rotate to face a fixed point.

class func orient(to: CGPoint, in: SKNode, offset: SKRange)

Creates a constraint that forces a node to rotate to face a point in another node’s coordinate system.

class func zRotation(SKRange)

Creates a constraint that limits the orientation of a node.

Creating Distance Constraints

Distance constraints constrain a node to a specified distance range of another node or a point and can be used for effects such a simulating flocking around a node, repulsive fields and trails. Supplying a distance constraint with a range with a lower limit, an upper limit or both results in very different behaviors:

Example initialization

Behavior

SKConstraint.distance(SKRange(lowerLimit: 20), to: targetNode)

If targetNode is moving and constrained objects are static, gives an effect similar to a repulsive magnetic field

SKConstraint.distance(SKRange(upperLimit: 10), to: targetNode)

All constrained nodes are immediately attracted to targetNode. Multiple constrained nodes can converge to a single point if targetNode is moved.

SKConstraint.distance(SKRange(lowerLimit: 40, upperLimit: 50), to: targetNode)

All constrained nodes are immediately attracted to targetNode. Multiple constrained nodes can form a ring around targetNode if it is moved.

class func distance(SKRange, to: SKNode)

Creates a constraint that keeps a node within a certain distance of another node.

class func distance(SKRange, to: CGPoint)

Creates a constraint that keeps a node within a certain distance of a point.

class func distance(SKRange, to: CGPoint, in: SKNode)

Creates a constraint that keeps a node within a certain distance of a point in another node’s coordinate system.

Determining the Coordinate System That a Constraint Is Applied In

var referenceNode: SKNode?

The node whose coordinate system should be used to apply the constraint.

Enabling a Constraint

var enabled: Bool

A Boolean value that specifies whether the constraint is applied.

Relationships

Inherits From