Platforms to show: All Mac Windows Linux Cross-Platform

SCNPhysicsBodyMBS class

Type Topic Plugin Version macOS Windows Linux iOS Targets
class SceneKit MBS Mac64bit Plugin 20.2 ✅ Yes ❌ No ❌ No ✅ Yes Desktop & iOS
The physics simulation attributes attached to a scene graph node.

When SceneKit prepares to render 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 SceneKit completes these calculations, it updates the positions and orientations of the node objects before rendering the frame.

To add physics to a node, create and configure an SCNPhysicsBody object and then assign it to the physicsBody property of the SCNNode object. A physics body must be associated with a node object before you apply forces or impulses to it.

A Body’s Physical Characteristics
The SCNPhysicsBody class defines the physical characteristics for the body when it is simulated by the scene. Three properties are most important for physics simulation:

  • The type property, which determines how the body interacts with forces and other bodies in the simulation. Static bodies are unaffected by forces and collisions and cannot move. Dynamic bodies are affected by forces and collisions with other body types. Kinematic bodies are not affected by forces or collisions, but by moving them directly you can cause collisions that affect dynamic bodies.
  • The physicsShape property, which defines the three-dimensional form of the body for collision detection purposes. Physics simulations run faster when using simple shapes instead of the fine detail of a node’s visible geometry. Typically, you set a body’s physics shape to a bounding box, sphere, or primitive shape that roughly matches its node’s visible content. For details on creating physics shapes, see SCNPhysicsShape.
  • The kinematicBody property. Applying a force or torque to a dynamic body results in an acceleration (or angular acceleration) proportional to its mass.

All values in SceneKit’s physics simulation use the International System of Units (SI): The unit of mass is the kilogram; the units of force, impulse, and torque are the newton, newton-second, and newton-meter; and the unit of distance for node positions and sizes is the meter. Note that you need not attempt to provide realistic values for physical quantities—use whatever values produce the behavior or gameplay you’re looking for.
For a dynamic body, you can control how the body is affected by forces or collisions. See Defining How Forces Affect a Physics Body.

Defining a Body’s Category and Collisions
When you design a game that uses physics, you define the different categories of physics objects that appear in the scene. You define different categories of physics bodies for the behaviors your want for your app. 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.
Use the categoryBitMask and collisionBitMask properties to define an object’s collision behavior. The constants listed in SCNPhysicsCollisionCategory provide default values for these properties. In addition, with the contactTestBitMask property you can define interactions where a pair of bodies generates contact messages (see the SCNPhysicsContactDelegate protocol) without the bodies being affected by the collision.

Related Physics Classes
Physics fields create forces that affect all bodies in an area, such as vortices and gravitational attraction. For details and a list of available field types, see SCNPhysicsField.
You can add higher-level behaviors that control interactions between multiple bodies, such as joints and wheeled vehicles. For details and a list of available behaviors, see SCNPhysicsBehavior.
A scene’s physicsWorld property holds an SCNPhysicsWorld object that manages physics characteristics that affect the entire scene.

Physics and the Rendering Loop
SceneKit evaluates its physics simulation as part of the rendering loop described in SCNSceneRendererDelegate. On each pass through this loop, SceneKit determines the state of all nodes with attached physics bodies, and simulates the effects of physics on those bodies for one time step—for example, by updating the position or rotation of a body based on its velocity and angular velocity. After simulating physics, SceneKit applies the results of the physics simulation to the scene for display.

Because you can animate SceneKit content not only through physics, but also through actions and implicitly and explicitly defined animations, SceneKit applies the results of physics simulation not to the SCNNode objects in your scene, but to each node’s presentationNode object that represents its currently displayed state. As such, changing properties of a node that are affected by physics requires special consideration.

If you change the transform value—or any of the other properties that are components of the transform, such as position and rotation—of a node affected by physics, SceneKit resets the physics simulation for that node. If you want to change only one component of the transform, while leaving the others at their physics-simulated values, copy the presentation node’s transform before making changes.

see also

Collision Categories

Constant Value Description
kPhysicsCollisionCategoryAll -1 This is the default value for a physics body’s collisionBitMask property.
With this collision mask, a physics body can collide with all other physics bodies.
kPhysicsCollisionCategoryDefault 1 The default categoryBitMask value for dynamic and kinematic bodies.
kPhysicsCollisionCategoryStatic 2 The default categoryBitMask value for static bodies.

Body Types

Constant Value Description
kTypeDynamic 1 A physics body that can be affected by forces and collisions.
Use dynamic bodies for the elements of your scene that are moved by the physics simulation.
kTypeKinematic 2 A physics body that is unaffected by forces or collisions but that can cause collisions affecting other bodies when moved. more
kTypeStatic 0 A physics body that is unaffected by forces or collisions and cannot move. more

This class has no sub classes.

Some methods using this class:

Some properties using for this class:

Some examples using this class:

Blog Entries

The items on this page are in the following plugins: MBS Mac64bit Plugin.

SCNPhysicsBehaviorMBS   -   SCNPhysicsConeTwistJointMBS

The biggest plugin in space...