Class

SKPhysicsBody

An object that adds physics simulation to a node.

Declaration

@interface SKPhysicsBody : NSObject

Overview

Assign a SKPhysicsBody object to the physicsBody property of the SKNode object to add physics simulation to the 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.

SpriteKit 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 volumeless boundaries or hollow spaces in your physics simulation. In contrast, volume-based bodies are used to represent objects with mass and volume. The dynamic property controls whether a volume-based body is affected by gravity, friction, collisions with other objects, and forces or impulses you directly apply to it.

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.

Topics

First Steps

Getting Started with Physics Bodies

Create and assign a physics body to enable physics.

Creating a Body from a Shape

+ bodyWithCircleOfRadius:

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

+ bodyWithCircleOfRadius:center:

Creates a circular physics body centered on an arbitrary point.

+ bodyWithRectangleOfSize:

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

+ bodyWithRectangleOfSize:center:

Creates a rectangular physics body centered on an arbitrary point.

+ bodyWithPolygonFromPath:

Creates a polygonal physics body.

Creating a Body from a Texture

Shaping a Physics Body to Match a Node's Graphics

Shape a physics body to your graphics for the right blend of collision accuracy and performance.

+ bodyWithTexture:size:

Creates a physics body from the contents of a texture.

+ bodyWithTexture:alphaThreshold:size:

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

Creating a Body from a Collection of Bodies

+ bodyWithBodies:

Creates a physics body that's shaped like a union of the argument physics bodies.

Creating an Edge-Based Physics Body

Creating an Edge Loop Around a Scene

Border your scene with an obstacle that physics bodies cannot penetrate.

+ bodyWithEdgeLoopFromRect:

Creates an edge loop from a rectangle.

+ bodyWithEdgeFromPoint:toPoint:

Creates an edge between two points.

+ bodyWithEdgeLoopFromPath:

Creates an edge loop from a path.

+ bodyWithEdgeChainFromPath:

Creates an edge chain from a path.

Defining How Forces Affect a Physics Body

affectedByGravity

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

allowsRotation

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

dynamic

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

Defining a Physics Body’s Physical Properties

Configuring a Physics Body

Move a physics body, and make it collide with other objects, by setting its physical properties once or changing them dynamically.

mass

The mass of the body, in kilograms.

density

The density of the object, in kilograms per square meter.

area

The area covered by the body.

friction

The roughness of the surface of the physics body.

restitution

The bounciness of the physics body.

linearDamping

A property that reduces the body’s linear velocity.

angularDamping

A property that reduces the body’s rotational velocity.

Working with Collisions and Contacts

About Collisions and Contacts

Learn how to set up nodes for collision detection.

categoryBitMask

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

collisionBitMask

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

usesPreciseCollisionDetection

A Boolean value that determines whether the physics world uses an iterative collision detection algorithm.

contactTestBitMask

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

- allContactedBodies

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

Applying Forces and Impulses to a Physics Body

Making Physics Bodies Move

Move a body using various physics properties, like velocity, gravity or impulses.

- applyForce:

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

- applyTorque:

Applies torque to an object.

- applyForce:atPoint:

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

- applyImpulse:

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

- applyAngularImpulse:

Applies an impulse that imparts angular momentum to an object.

- applyImpulse:atPoint:

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

Inspecting a Physics Body’s Position and Velocity

velocity

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

angularVelocity

The physics body’s angular speed.

resting

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

Reading a Physics Body’s Node

node

The node that this body is connected to.

Determining Which Joints Are Connected to a Physics Body

joints

The joints connected to this physics body.

Interacting with Physics Fields

fieldBitMask

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

charge

The electrical charge of the physics body.

Pinning a Physics Body to a Node’s Parent

Pinning and Rotating Physics Bodies

Pin a node so it's free to rotate about a certain point on its parent node.

pinned

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

Relationships

Inherits From

See Also

Physics Simulation

Getting Started with Physics

Simulate gravity, acceleration, collision detection, or joints.

SKPhysicsWorld

The driver of the physics engine in a scene; it exposes the ability for you to configure and query the physics system.

SKPhysicsContact

A description of the contact between two physics bodies.

SKPhysicsContactDelegate

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

SKFieldNode

A node that applies physics effects to nearby nodes.