SKPhysicsBody Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SpriteKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
SKPhysicsBody.h

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 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 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.”

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

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

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

Tasks

Creating Volume-based Physics Bodies

Creating Edge-based Physics Bodies

Defining How Forces Affect a Physics Body

Defining a Body’s Physical Properties

Working with Collisions and Contacts

Applying Forces and Impulses to a Physics Body

Inspecting the Physics Body’s Position and Velocity

Reading the Physics Body’s Node

Determining Which Joints Are Connected to a Physics Body

Properties

affectedByGravity

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

@property(assign, nonatomic) BOOL affectedByGravity
Discussion

The physics world’s gravity property defines the gravitational forces applied to volume-based bodies in the scene. The default value is YES. This property is ignored on edge-based bodies, which are unaffected by gravity.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

allowsRotation

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

@property(nonatomic) BOOL allowsRotation
Discussion

The default value is YES. This property is ignored on edge-based bodies, which are unaffected by forces in the system.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

angularDamping

A property that reduces the body’s rotational velocity.

@property(assign, nonatomic) CGFloat angularDamping
Discussion

This property is used to simulate fluid or air friction forces on the body. The property must be a value between 0.0 and 1.0. The default value is 0.1. If the value is 0.0, no angular damping is applied to the object.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

angularVelocity

The physics body’s angular speed.

@property(nonatomic) CGFloat angularVelocity
Discussion

The angular velocity is a pseudo vector around an axis vector of (0.0,0.0,1.0) measured in radians per second.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

area

The area covered by the body. (read-only)

@property(readonly, nonatomic) CGFloat area
Discussion

This property is used in conjunction with the density property to calculate the body’s mass.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

categoryBitMask

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

@property(assign, nonatomic) uint32_t categoryBitMask
Discussion

Every physics body in a scene can be assigned to up to 32 different categories, each corresponding to a bit in the bit mask. You define the mask values used in your game. In conjunction with the collisionBitMask and contactTestBitMask properties, you define which physics bodies interact with each other and when your game is notified of these interactions.

The default value is 0xFFFFFFFF (all bits set).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

collisionBitMask

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

@property(assign, nonatomic) uint32_t collisionBitMask
Discussion

When two physics bodies contact each other, a collision may occur. This body’s collision mask is compared to the other body’s category mask by performing a logical AND operation. If the result is a non-zero value, then this body is affected by the collision. Each body independently chooses whether it wants to be affected by the other body. For example, you might use this to avoid collision calculations that would make negligible changes to a body’s velocity.

The default value is 0xFFFFFFFF (all bits set).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

contactTestBitMask

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

@property(assign, nonatomic) uint32_t contactTestBitMask
Discussion

When two bodies share the same space, each body’s category mask is tested against the other body’s contact mask by performing a logical AND operation. If either comparison results in a non-zero value, an SKPhysicsContact object is created and passed to the physics world’s delegate. For best performance, only set bits in the contacts mask for interactions you are interested in.

The default value is 0x00000000 (all bits cleared).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

density

The density of the object in kilograms per square meter.

@property(nonatomic) CGFloat density
Discussion

The actual unit is arbitrary as long as relative masses of objects are consistent throughout the game.

The mass and density properties are interrelated. When you change the value of either property, the other property’s value is automatically recalculated to be consistent.

The default value is 1.0.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
SKPhysicsBody.h

dynamic

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

@property(getter=isDynamic, nonatomic) BOOL dynamic
Discussion

The default value is YES. If the value is NO, then the physics body ignores all forces and impulses applied to it. This property is ignored on edge-based bodies; they are automatically static.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

friction

The roughness of the surface of the physics body.

@property(nonatomic) CGFloat friction
Discussion

This property is used to apply a frictional force to physics bodies in contact with this physics body. The property must be a value between 0.0 and 1.0. The default value is 0.2.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

joints

The joints connected to this physics body. (read-only)

@property(readonly, nonatomic) NSArray *joints
Discussion

This property holds an array of SKPhysicsJoint objects that define all joints added to the scene’s physics world that are connected to this physics body.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

linearDamping

A property that reduces the body’s linear velocity.

@property(assign, nonatomic) CGFloat linearDamping
Discussion

This property is used to simulate fluid or air friction forces on the body. The property must be a value between 0.0 and 1.0. The default value is 0.1. If the value is 0.0, no linear damping is applied to the object.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

mass

The mass of the body in kilograms.

@property(nonatomic) CGFloat mass
Discussion

The actual unit is arbitrary as long as relative masses of objects are consistent throughout the game. The mass of the body affects its momentum as well as how forces are applied to the object.

The mass and density properties are interrelated. When you change the value of either property, the other property’s value is automatically recalculated to be consistent. The default value is based on the size of the physics body and the body’s default density.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
SKPhysicsBody.h

node

The node that this body is connected to. (read-only)

@property(readonly, weak, nonatomic) SKNode *node
Discussion

You associate the body with a node by assigning it to the physicsBody property of the SKNode object. If the body is not associated with a node, the value is nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

resting

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

@property(getter=isResting, nonatomic) BOOL resting
Discussion

This property is automatically set to YES by the physics simulation when it determines that the body is at rest. This means that the body is at rest on another body in the system. Resting bodies do not participate in the physics simulation until an impulse is applied to the object or another object collides with it. This improves the performance of the physics simulation. If all bodies in the world are resting, then the entire simulation is at rest, reducing the number of calculations that are performed by the physics world.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

restitution

The bounciness of the physics body.

@property(nonatomic) CGFloat restitution
Discussion

This property is used to determine how much energy the physics body loses when it bounces off another object. The property must be a value between 0.0 and 1.0. The default value is 0.2.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

usesPreciseCollisionDetection

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

@property(nonatomic) BOOL usesPreciseCollisionDetection
Discussion

The default value is NO. If two bodies in a collision do not perform precise collision detection, and one passes completely through the other in a single frame, no collision is detected. If this property is set to YES on either body, then the simulation performs a more precise and more expensive calculation to detect these collisions. This property should be set to YES on small, fast moving bodies.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

velocity

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

@property(nonatomic) CGVector velocity
Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

Class Methods

bodyWithBodies:

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

+ (SKPhysicsBody *)bodyWithBodies:(NSArray *)bodies
Parameters
bodies

An array of SKPhysicsBody objects. The objects must be volume-based physics bodies. (You may not use a compound body created using this method in the array.)

Return Value

A new compound-physics body.

Discussion

The shapes of the physics bodies passed into this method are used to create a new physics body whose covered area is the union of the areas of its children. These areas do not need to be contiguous. If there is space between two parts, other bodies may be able to pass between these parts. However, the physics body is treated as a single connected body, meaning that a force or impulse applied to the body affects all of the pieces as if they were held together with an indestructible frame.

The properties on the children, such as mass or friction, are ignored. Only the shapes of the child bodies is used.

Availability
  • Available in iOS 7.1 and later.
Declared In
SKPhysicsBody.h

bodyWithCircleOfRadius:

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

+ (SKPhysicsBody *)bodyWithCircleOfRadius:(CGFloat)r
Parameters
r

The radius of the circle.

Return Value

A new volume-based physics body.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithCircleOfRadius:center:

Creates a circular physics body centered on an arbitrary point.

+ (SKPhysicsBody *)bodyWithCircleOfRadius:(CGFloat)r center:(CGPoint)center
Parameters
r

The radius of the circle.

center

The origin of the circle in the owning node’s coordinate system

Return Value

A new volume-based physics body.

Availability
  • Available in iOS 7.1 and later.
Declared In
SKPhysicsBody.h

bodyWithEdgeChainFromPath:

Creates an edge chain from a path.

+ (SKPhysicsBody *)bodyWithEdgeChainFromPath:(CGPathRef)path
Parameters
path

A Core Graphics path. The points are specified relative to the owning node’s origin. The path must not intersect itself.

Return Value

A new edge-based physics body.

Discussion

An edge has no volume or mass and is always treated as if the dynamic property is equal to NO. Edges may only collide with volume-based physics bodies.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithEdgeFromPoint:toPoint:

Creates an edge between two points.

+ (SKPhysicsBody *)bodyWithEdgeFromPoint:(CGPoint)p1 toPoint:(CGPoint)p2
Parameters
p1

The starting point for the edge, relative to the owning node’s origin.

p2

The ending point for the edge, relative to the owning node’s origin.

Return Value

A new edge-based physics body.

Discussion

An edge has no volume or mass and is always treated as if the dynamic property is equal to NO. Edges may only collide with volume-based physics bodies.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithEdgeLoopFromPath:

Creates an edge loop from a path.

+ (SKPhysicsBody *)bodyWithEdgeLoopFromPath:(CGPathRef)path
Parameters
path

A Core Graphics path. The points are specified relative to the owning node’s origin. The path must not intersect itself.

Return Value

A new edge-based physics body.

Discussion

If the path is not already closed, a loop is automatically created by joining the last point to the first.

An edge has no volume or mass and is always treated as if the dynamic property is equal to NO. Edges may only collide with volume-based physics bodies.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithEdgeLoopFromRect:

Creates an edge loop from a rectangle.

+ (SKPhysicsBody *)bodyWithEdgeLoopFromRect:(CGRect)rect
Parameters
rect

The rectangle that defines the edges. The rectangle is specified relative to the owning node’s origin.

Return Value

A new edge-based physics body.

Discussion

An edge has no volume or mass and is always treated as if the dynamic property is equal to NO. Edges may only collide with volume-based physics bodies.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithPolygonFromPath:

Creates a polygon-shaped physics body.

+ (SKPhysicsBody *)bodyWithPolygonFromPath:(CGPathRef)path
Parameters
path

A convex polygonal path with counterclockwise winding and no self intersections. The points are specified relative to the owning node’s origin.

Return Value

A new volume-based physics body.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithRectangleOfSize:

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

+ (SKPhysicsBody *)bodyWithRectangleOfSize:(CGSize)s
Parameters
s

The size of the rectangle.

Return Value

A new volume-based physics body.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

bodyWithRectangleOfSize:center:

Creates a rectangular physics body centered on an arbitrary point.

+ (SKPhysicsBody *)bodyWithRectangleOfSize:(CGSize)s center:(CGPoint)center
Parameters
s

The size of the rectangle.

center

The center of the square in the owning node’s coordinate system

Return Value

A new volume-based physics body.

Availability
  • Available in iOS 7.1 and later.
Declared In
SKPhysicsBody.h

Instance Methods

allContactedBodies

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

- (NSArray *)allContactedBodies
Return Value

An array of SKPhysicsBody objects that this body is in contact with.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyAngularImpulse:

Applies an impulse that imparts angular momentum to an object.

- (void)applyAngularImpulse:(CGFloat)impulse
Parameters
impulse

The magnitude of the impulse. The impulse is measured in Newton-seconds.

Discussion

This method affects the body’s angular velocity without changing the body’s linear velocity.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyForce:

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

- (void)applyForce:(CGVector)force
Parameters
force

A vector that describes how much force was applied in each dimension. The force is measured in Newtons.

Discussion

This method accelerates the body without imparting any angular acceleration to it. The acceleration is applied for a single simulation step (one frame).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyForce:atPoint:

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

- (void)applyForce:(CGVector)force atPoint:(CGPoint)point
Parameters
force

A vector that describes how much force was applied in each dimension. The force is measured in Newtons.

point

A point in scene coordinates that defines where the force was applied to the physics body.

Discussion

Because the force is applied to a specific point on the body, it may impart both linear acceleration and angular acceleration. The force is applied for a single simulation step (one frame).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyImpulse:

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

- (void)applyImpulse:(CGVector)impulse
Parameters
impulse

A vector that describes how much momentum was imparted in each dimension. The impulse is measured in Newton-seconds.

Discussion

This method affects the body’s linear velocity without changing the body’s angular velocity.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyImpulse:atPoint:

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

- (void)applyImpulse:(CGVector)impulse atPoint:(CGPoint)point
Parameters
impulse

A vector that describes how much momentum to impart to the body. The impulse is measured in Newton-seconds.

point

A point in scene coordinates that defines where the impulse was applied to the physics body.

Discussion

Because this impulse is applied to a specific point on the object, it may change both the body’s velocity and angular velocity.

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h

applyTorque:

Applies a torque to an object.

- (void)applyTorque:(CGFloat)torque
Parameters
torque

The amount of torque, in Newton-meters.

Discussion

This method generates an angular acceleration on the body without causing any linear acceleration. The force is applied for a single simulation step (one frame).

Availability
  • Available in iOS 7.0 and later.
Declared In
SKPhysicsBody.h