Class

SKPhysicsJoint

The abstract superclass for objects that connect physics bodies.

Declaration

class SKPhysicsJoint : NSObject

Overview

An SKPhysicsJoint object connects two physics bodies so that they are simulated together by the physics world. You never instantiate objects of this class directly; instead, you instantiate one of the subclasses that defines the kind of joint you want to make.

Connecting Physics Bodies

Although you can make a lot of interesting games that use the physics systems that have already been described, you can take your designs further by connecting physics bodies using joints. When the scene simulates the physics, it takes these joints into account when calculating how forces affect the bodies.

Figure 1

Physics joints

Physics joints

You add or remove joints using the physics world. When you create a joint, the points that connect the joint are always specified in the scene’s coordinate system. This may require you to first convert from node coordinates to scene coordinates before creating a joint.

To use a physics joint in your game, follow these steps:

  • Create two physics bodies.

  • Attach the physics bodies to a pair of SKNode objects in the scene.

  • Create a joint object using one of the subclasses listed in the table above.

  • If necessary, configure the joint object’s properties to define how the joint should operate.

  • Retrieve the scene’s SKPhysicsWorld object.

  • Call the physics world’s add(_:) method.

The following code pins two nodes, pin and piston, together using a SKPhysicsJointPin joint. In this example, the node pin is a child of connectingRod. Because it is not an immediate child of the scene, its coordinates are converted to scene coordinates for use initializing the joint:

Listing 1

Creating a pin joint

let pinPosition = connectingRod.convert(pin.position,
                                         to: scene)
let pinJoint = SKPhysicsJointPin.joint(withBodyA: pin.physicsBody!,
                                        bodyB: piston.physicsBody!,
                                        anchor: pinPosition)
scene.physicsWorld.add(pinJoint)

Disconnecting Physics Bodies

You can use the SKPhysicsWorld method remove(_:) to remove joints from a simulation. By making use of the update(_:for:) method of the SKSceneDelegate, you can interrogate the properties of joints — such as the distance between the two connected bodies.

The following code shows an example of this. Each time a new spring joint is created, it is also added to an array named springs of type [SKPhysicsJointSpring]. With each simulation step, every spring is evaluated and if the distance between the two connected bodies is greater than maxSpringDistance, the spring is removed from both the physics world and the array:

Listing 2

Removing springs when they stretch too far

var springs = [SKPhysicsJointSpring]()
let maxSpringDistance: CGFloat = 31

// Each `scene.physicsWorld.add(spring)` is accompanied with `springs.append(spring)`

func update(_ currentTime: TimeInterval, for scene: SKScene) {
    
    for spring in springs {
        if let bodyAPosition = spring.bodyA.node?.position,
            let bodyBPosition = spring.bodyB.node?.position {
            let distance = hypot(bodyAPosition.x  - bodyBPosition.x,
                                 bodyAPosition.y - bodyBPosition.y)
            
            if distance > maxSpringDistance {
                scene.physicsWorld.remove(spring)
                if let index = springs.index(of: spring) {
                    springs.remove(at: index)
                }
            }
        }
    }}

Topics

Inspecting Joint Properties

var bodyA: SKPhysicsBody

The first body connected by the joint.

var bodyB: SKPhysicsBody

The second body connected by the joint.

Measuring Force Effects Against the Anchor Point

var reactionForce: CGVector

The instantaneous reaction force currently being directed at the anchor point, in Newtons.

var reactionTorque: CGFloat

Instantaneous reaction torque currently being directed at the anchor point, in Newton-meters.

Relationships

Inherits From

See Also

Simulating Physics

class SKPhysicsWorld

An object which encapsulates a scene's physics simulation.

class SKPhysicsBody

An object which adds physics simulation to a node.

class SKPhysicsContact

A description of the contact between two physics bodies.

protocol SKPhysicsContactDelegate

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

class SKPhysicsJointFixed

A joint that fixes two physics bodies together.

class SKPhysicsJointLimit

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

class SKPhysicsJointPin

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

class SKPhysicsJointSliding

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

class SKPhysicsJointSpring

A joint that simulates a spring connecting two physics bodies.

class SKFieldNode

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

class SKRegion

A definition of an arbitrary area.