Class

SKPhysicsWorld

An object which encapsulates a scene's physics simulation.

Overview

An SKPhysicsWorld object simulates collisions and other physical properties. You do not create SKPhysicsWorld objects directly; instead, read the physicsWorld property of an SKScene object.The physics world object allows you to perform the following tasks:

  • Set global properties for the simulation, such as gravity

  • Create joints between two physics bodies in the scene

  • Set a delegate to receive notifications when two physics bodies are in contact with each other

  • Determine which physics bodies within the scene intersect with points, rectangles, or rays

Configuring the Physics World

All physics bodies in a scene are part of the physics world, which is represented in SpriteKit by an SKPhysicsWorld object attached to the scene. The physics world defines two important characteristics of the simulation:

  • The gravity property applies an acceleration to volume-based bodies in the simulation. Static volumes and physics bodies that have set the affectedByGravity property to false are unaffected.

  • The speed property determines the rate at which the simulation runs.

Searching for Physics Bodies

Sometimes, it is necessary to find physics bodies in the scene. For example, you might need to:

  • Discover whether a physics body is located in a region of the scene.

  • Detect when a physics body (such as the one controlled by the player) crosses a particular line.

  • Trace the line of sight between two physics bodies, to see whether another physics body, such as a wall, is interposed between the two objects.

  • Occlude an audio node if a body is between it and a scene’s listener node.

In some cases, you can implement these interactions using the collisions and contacts system. For example, to discover when a physics body enters a region, you could create a physics body and attach it to an invisible node in the scene. Then, configure the physics body’s collision mask so that it never collides with anything, and its contact mask to detect the physics bodies you are interested in. Your contact delegate is called when the desired interactions occur.

However, it’s not easy to implement concepts such as line of sight using this design. To implement these, you use the scene’s physics world. With the physics world, you can search for all physics bodies along a ray or physics bodies that intersect a particular point or rectangle.

An example illustrates the basic technique. The following code shows one possible implementation of a line-of-sight detection system. It casts a ray from the origin of the scene in a particular direction, searching for the nearest physics body along the ray. If it finds a physics body, then it tests the category mask to see whether this is a target it should attack. If it sees a target designated for attack, it shoots the cannon.

Listing 1

Casting a ray from the center of the scene

func isTargetVisibleAtAngle(angle: CGFloat, distance: CGFloat) -> Bool {
    let rayStart = CGPoint.zero
    let rayEnd = CGPoint(x: distance * cos(angle),
                         y: distance * sin(angle))
    
    let body = scene.physicsWorld.body(alongRayStart: rayStart, end: rayEnd)
    
    return body?.categoryBitMask == targetCategory
}
func attackTargetIfVisible() {
    if isTargetVisibleAtAngle(angle: cannon.zRotation, distance: 512) {
        shootCannon()
    }
}

Another way to implement the same behavior is to set the starting and ending positions of the ray to those of two physics bodies in your scene. For example, you might use the location of the player’s game object as one position and the position of an enemy unit as the other position.

You can also perform searches for physics bodies that intersect a point or rectangle using the body(at:) and body(in:) methods.

Sometimes you can’t make a simple determination based on the closest physics body within the scene. For example, in the logic of your game, you might decide that not all physics bodies block the line of sight. In this case, you need to enumerate all of the physics bodies along the ray using the enumerateBodies(alongRayStart:end:using:) method. You supply a block that is called once for each body along the ray. You can then use this information to make a more informed decision about whether the line of sight exists to a target.

Topics

Configuring the Physics World Simulation

var gravity: CGVector

A vector that specifies the gravitational acceleration applied to physics bodies in the physics world.

var speed: CGFloat

The rate at which the simulation executes.

Joining Physics Bodies Together

func add(SKPhysicsJoint)

Adds a joint to the physics world.

func removeAllJoints()

Removes all joints from the physics world.

func remove(SKPhysicsJoint)

Removes a specific joint from the physics world.

Detecting Collisions in the Physics World

var contactDelegate: SKPhysicsContactDelegate?

A delegate that is called when two physics bodies come in contact with each other.

Searching for Bodies in the World

func body(alongRayStart: CGPoint, end: CGPoint)

Searches for the first physics body that intersects a ray.

func body(at: CGPoint)

Searches for the first physics body that contains a point.

func body(in: CGRect)

Searches for the first physics body that intersects the specified rectangle.

func enumerateBodies(at: CGPoint, using: (SKPhysicsBody, UnsafeMutablePointer<ObjCBool>) -> Void)

Enumerates all the physics bodies in the scene that contain a point.

func enumerateBodies(in: CGRect, using: (SKPhysicsBody, UnsafeMutablePointer<ObjCBool>) -> Void)

Enumerates all the physics bodies in the scene that intersect the specified rectangle.

Working with Physics Fields

func sampleFields(at: vector_float3)

Samples all of the field nodes in the scene and returns the summation of their forces at that point.

Relationships

Inherits From

See Also

Simulating Physics

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 SKPhysicsJoint

The abstract superclass for objects that connect physics bodies.

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.