The physics simulation attributes attached to a scene graph node.
- iOS 8.0+
- macOS 10.10+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
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
SCNPhysics object and then assign it to the
physics 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
SCNPhysics class defines the physical characteristics for the body when it is simulated by the scene. Three properties are most important for physics simulation:
typeproperty, 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.
physicsproperty, 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
kinematic()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.
collision properties to define an object’s collision behavior. The constants listed in
SCNPhysics provide default values for these properties. In addition, with the
contact property you can define interactions where a pair of bodies generates contact messages (see the
SCNPhysics 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
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
Physics and the Rendering Loop
SceneKit evaluates its physics simulation as part of the rendering loop described in
SCNScene. 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
presentation 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
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, as shown below: