Class

SKPhysicsBody

An object which adds physics simulation to a node.

Overview

An SKPhysicsBody object is used to add physics simulation to a node. When a scene processes a new frame, it performs physics calculations on physics bodies attached to nodes in the scene. These calculations include gravity, friction, and collisions with other bodies. You can also apply your own forces and impulses to a body. After the scene completes these calculations, it updates the positions and orientations of the node objects.To add physics to a node, create and configure an SKPhysicsBody object and then assign it to the physicsBody property of the SKNode object. A physics body must be associated with a node object before you apply forces or impulses to it.

Sprite Kit supports two kinds of physics bodies, volume-based bodies and edge-based bodies. When you create a physics body, its kind, size, and shape are determined by the constructor method you call. An edge-based body does not have mass or volume and is unaffected by forces or impulses in the system. Edge-based bodies are used to represent volume-less boundaries or hollow spaces in your physics simulation. In contrast, volume-based bodies are used to represent objects with mass and volume. The isDynamic property controls whether a volume-based body is affected by gravity, friction, collisions with other objects, and forces or impulses you directly apply to the object.

The SKPhysicsBody class defines the physical characteristics for the body when it is simulated by the scene. For volume-based bodies, the most important property is the mass property. A volume-based body is assumed to have a uniform density. You can either set the mass property directly, or you can set the body’s density property and let the physics body calculate its own mass. All values in Sprite Kit are specified using the International System of Units (SI units). The actual forces and mass values are not important so long as your game uses consistent values.

When you design a game that uses physics, you define the different categories of physics objects that appear in the scene. You define up to 32 different categories of physics bodies, and a body can be assigned to as many of these categories as you want. In addition to declaring its own categories, a physics body also declares which categories of bodies it interacts with. See Working with Collisions and Contacts. You use a similar mechanism to declare which physics field nodes (SKFieldNode) can affect the physics body.

For a volume-based body, you can dynamically control how the body is affected by forces or collisions. See Defining How Forces Affect a Physics Body.

Other Related Physics Classes

A scene’s physicsWorld property holds an SKPhysicsWorld object that provides physics characteristics that affect the entire scene.

You can use fields to apply forces to a set of physics bodies or to change their velocities. See SKFieldNode.

You can connect physics bodies together using joints. See SKPhysicsJoint.

Symbols

Creating Volume-Based Physics Bodies

init(circleOfRadius: CGFloat)

Creates a circular physics body centered on the owning node’s origin.

init(circleOfRadius: CGFloat, center: CGPoint)

Creates a circular physics body centered on an arbitrary point.

init(rectangleOf: CGSize)

Creates a rectangular physics body centered on the owning node’s origin.

init(rectangleOf: CGSize, center: CGPoint)

Creates a rectangular physics body centered on an arbitrary point.

init(bodies: [SKPhysicsBody])

Creates a physics body by performing a union of a group of volume-based physics bodies.

init(polygonFrom: CGPath)

Creates a polygon-shaped physics body.

init(texture: SKTexture, size: CGSize)

Creates a physics body from the contents of a texture.

init(texture: SKTexture, alphaThreshold: Float, size: CGSize)

Creates a physics body from the contents of a texture, capturing only the texels that exceed a specified transparency value.

Creating Edge-Based Physics Bodies

init(edgeLoopFrom: CGRect)

Creates an edge loop from a rectangle.

init(edgeFrom: CGPoint, to: CGPoint)

Creates an edge between two points.

init(edgeLoopFrom: CGPath)

Creates an edge loop from a path.

init(edgeChainFrom: CGPath)

Creates an edge chain from a path.

Defining How Forces Affect a Physics Body

var affectedByGravity: Bool

A Boolean value that indicates whether this physics body is affected by the physics world’s gravity.

var allowsRotation: Bool

A Boolean value that indicates whether the physics body is affected by angular forces and impulses applied to it.

var isDynamic: Bool

A Boolean value that indicates whether the physics body is moved by the physics simulation.

Defining a Body’s Physical Properties

var mass: CGFloat

The mass of the body in kilograms.

var density: CGFloat

The density of the object in kilograms per square meter.

var area: CGFloat

The area covered by the body.

var friction: CGFloat

The roughness of the surface of the physics body.

var restitution: CGFloat

The bounciness of the physics body.

var linearDamping: CGFloat

A property that reduces the body’s linear velocity.

var angularDamping: CGFloat

A property that reduces the body’s rotational velocity.

Working with Collisions and Contacts

var categoryBitMask: UInt32

A mask that defines which categories this physics body belongs to.

var collisionBitMask: UInt32

A mask that defines which categories of physics bodies can collide with this physics body.

var usesPreciseCollisionDetection: Bool

A Boolean value that determines whether the physics world uses a more precise collision detection algorithm.

var contactTestBitMask: UInt32

A mask that defines which categories of bodies cause intersection notifications with this physics body.

func allContactedBodies()

The physics bodies that this physics body is in contact with.

Applying Forces and Impulses to a Physics Body

func applyForce(CGVector)

Applies a force to the center of gravity of a physics body.

func applyTorque(CGFloat)

Applies a torque to an object.

func applyForce(CGVector, at: CGPoint)

Applies a force to a specific point of a physics body.

func applyImpulse(CGVector)

Applies an impulse to the center of gravity of a physics body.

func applyAngularImpulse(CGFloat)

Applies an impulse that imparts angular momentum to an object.

func applyImpulse(CGVector, at: CGPoint)

Applies an impulse to a specific point of a physics body.

Inspecting the Physics Body’s Position and Velocity

var velocity: CGVector

The physics body’s velocity vector, measured in meters per second.

var angularVelocity: CGFloat

The physics body’s angular speed.

var isResting: Bool

A Boolean property that indicates whether the object is at rest within the physics simulation.

Reading the Physics Body’s Node

var node: SKNode?

The node that this body is connected to.

Determining Which Joints Are Connected to a Physics Body

var joints: [SKPhysicsJoint]

The joints connected to this physics body.

Interacting with Physics Fields

var fieldBitMask: UInt32

A mask that defines which categories of physics fields can exert forces on this physics body.

var charge: CGFloat

The electrical charge of the physics body.

Pinning a Physics Body to the Node’s Parent

var pinned: Bool

A Boolean value that indicates whether the physics body’s node is pinned to its parent node.

Relationships

Inherits From