iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKConstraint Class Reference

Options
Deployment Target:

On This Page
Language:

SKConstraint

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.

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

    Declaration

    Swift

    class func positionX(_ range: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)positionX:(SKRange * _Nonnull)range

    Parameters

    range

    The range to restrict the coordinate to.

    Return Value

    A new constraint.

    Discussion

    Each time constraints are applied, the x-coordinate of the node’s position property is clamped so that it lies inside the specified range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    class func positionY(_ range: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)positionY:(SKRange * _Nonnull)range

    Parameters

    range

    The range to restrict the coordinate to.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, the y-coordinate of the node’s position property is clamped so that it lies inside the specified range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    class func positionX(_ xRange: SKRange, y yRange: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)positionX:(SKRange * _Nonnull)xRange Y:(SKRange * _Nonnull)yRange

    Parameters

    xRange

    The range to restrict the x-coordinate to.

    yRange

    The range to restrict the y-coordinate to.

    Return Value

    A new constraint.

    Discussion

    Each time constraints are applied, the node’s position property is clamped so that both coordinates lie inside the specified ranges.

    Availability

    Available in iOS 8.0 and later.

  • Creates a constraint that forces a node to rotate based on the position of another node.

    Declaration

    Swift

    class func orientToNode(_ node: SKNode, offset radians: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)orientToNode:(SKNode * _Nonnull)node offset:(SKRange * _Nonnull)radians

    Parameters

    node

    The node that should be used to orient the node that this constraint is attached to.

    radians

    An offset that is added to the zRotation value after it is calculated.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a new angle is calculated so that a line projected at this angle would point at the other node’s origin. This angle is added to the values specified in the radians property to create a new range. Finally, the node’s zRotation value is clamped to fit inside this range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    class func orientToPoint(_ point: CGPoint, offset radians: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)orientToPoint:(CGPoint)point offset:(SKRange * _Nonnull)radians

    Parameters

    point

    A point in the node’s parent’s coordinate system.

    radians

    An offset that is added to the zRotation value after it is calculated.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a new angle is calculated so that a line projected at this angle would point at the target point. This angle is added to the values specified in the radians property to create a new range. Finally, the node’s zRotation value is clamped to fit inside this range.

    Availability

    Available in iOS 8.0 and later.

    See Also

    referenceNode

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

    Declaration

    Swift

    class func orientToPoint(_ point: CGPoint, inNode node: SKNode, offset radians: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)orientToPoint:(CGPoint)point inNode:(SKNode * _Nonnull)node offset:(SKRange * _Nonnull)radians

    Parameters

    point

    A point in the node parameter’s coordinate system.

    node

    The node whose coordinate system the point is specified in.

    radians

    An offset that is added to the zRotation value after it is calculated.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a new angle is calculated so that a line projected at this angle would point at the target point. This angle is added to the values specified in the radians property to create a new range. Finally, the node’s zRotation value is clamped to fit inside this range.

    Availability

    Available in iOS 8.0 and later.

  • Creates a constraint that limits the orientation of a node.

    Declaration

    Swift

    class func zRotation(_ zRange: SKRange) -> Self

    Objective-C

    + (instancetype _Nonnull)zRotation:(SKRange * _Nonnull)zRange

    Parameters

    zRange

    A range value that specifies the minimum and maximum values of the node’s zRotation property.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, the node’s zRotation property is clamped so that it is within the specified range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    class func distance(_ range: SKRange, toNode node: SKNode) -> Self

    Objective-C

    + (instancetype _Nonnull)distance:(SKRange * _Nonnull)range toNode:(SKNode * _Nonnull)node

    Parameters

    range

    The range of allowed distances between the two nodes.

    node

    The target node used to calculate the distance.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a line is projected between the node’s position and the target node’s position. The distance between the two points is calculated, and if it lies outside the specified range, the node is pushed or pulled along this line until it lies within the range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    class func distance(_ range: SKRange, toPoint point: CGPoint) -> Self

    Objective-C

    + (instancetype _Nonnull)distance:(SKRange * _Nonnull)range toPoint:(CGPoint)point

    Parameters

    range

    The range of allowed distances between the node and the point.

    point

    A point in the coordinate system of the node’s parent that is used to calculate the distance.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a line is projected between the node’s position and the target point. The distance between the two points is calculated, and if it lies outside the specified range, the node is pushed or pulled along this line until it lies within the range.

    Availability

    Available in iOS 8.0 and later.

    See Also

    referenceNode

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

    Declaration

    Swift

    class func distance(_ range: SKRange, toPoint point: CGPoint, inNode node: SKNode) -> Self

    Objective-C

    + (instancetype _Nonnull)distance:(SKRange * _Nonnull)range toPoint:(CGPoint)point inNode:(SKNode * _Nonnull)node

    Parameters

    range

    The range of allowed distances.

    point

    The point to use as the target point.

    node

    The node whose coordinate system the point is specified in.

    Return Value

    A new constraint.

    Discussion

    Each time when constraints are applied, a line is projected between the node’s position and the target point. The distance between the two points is calculated, and if it lies outside the specified range, the node is pushed or pulled along this line until it lies within the range.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var referenceNode: SKNode?

    Objective-C

    @property(retain, nonatomic, nullable) SKNode *referenceNode

    Discussion

    The default value is nil, meaning that the coordinate system of the node’s parent is used to apply the constraint. If another node is specified, all positions are converted into this node’s coordinate system before the constraint is applied.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value that specifies whether the constraint is applied.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property BOOL enabled

    Availability

    Available in iOS 8.0 and later.