Collisions & Physics: Getting Started with Physics Body Component

Adding the component in code and in Reality Composer Pro.

Overview

RealityKit ships with a powerful physics engine. We can use it to add realism to our apps, explore complex simulations, or even play with concepts like gravity. At minimum, we’ll need a Physics Body component and a Collision component. Let’s take a look at an example.

// Create a box model
let box = ModelEntity(
    mesh: .generateBox(size: 0.1),
    materials: [SimpleMaterial(color: .stepBlue, isMetallic: false)])

// A simple box collision
let collision = CollisionComponent(shapes: [.generateBox(size: .init(x: 0.1, y: 0.1, z: 0.1))])

// Physics Body 
let physics = PhysicsBodyComponent()

// Add the components
box.components.set([collision, physics])

// add the box to the scene content
content.add(box)

This will create a blue box with a collision and a physics body. We’re using all the default values, so this box will respond to gravity and will use the .dynamic mode. This box can fall on to the floor of our scene–assuming we have one. It will bounce just a bit, because the default physics material has a slight amount of restitution.

It’s a little easier to see the available options in Reality Composer Pro. We can add our Collision and Physics Body components, then adjust their values in the inspector.

As you can see, Physics Body has quite a number of options. We won’t cover all of them today, but we’ll visit each of them in future examples and labs. Let’s review the categories of options:

• Mode:
  • Dynamic: this entity can interact with other physics entities.
  • Static: Think of these as an immovable objects. Dynamic entities can collide with static ones, but the static ones won’t move.
  • Kinematic: Use this mode when you plan to take control of an entity, but still want it to interact with other physics objects. For example, a player in a game could push boxes of the way, but the boxes won’t “push back” on the player.
• Detect continuous collision: This mainly comes into play for fast moving objects. You can leave it off in most cases
• Affected by gravity: we can toggle this on or off depending on needs of the scene
• Dampening values: I leave these default values in most cases
• Material: define the “surface” of the entity. How much friction to apply, how bouncy, etc. more
• Mass Properties: how heavy is the entity? Where is the center of mass? more
• Movement Locking: we can customize how physics is applied to our axes of rotation and movement

Two values that are noticeably missing are included in another component. We can add a Physics Motion component if we need to access or change linear or angular velocity.

That covers the basics of this component. Next, we’ll dive into some examples where we customize physics for our entities.

Example Code

This scene has three spheres defined in Reality Composer Pro, and three boxed created in code.

struct Example060: View {
    var body: some View {
        RealityView { content  in

            // Load the scene and position it in the volume
            guard let scene = try? await Entity(named: "PhysicsBodyBasics", in: realityKitContentBundle) else { return }
            content.add(scene)
            scene.setScale(.init(repeating: 0.8), relativeTo: nil)
            scene.position.y = -0.4

            let collision = CollisionComponent(shapes: [.generateBox(size: .init(x: 0.1, y: 0.1, z: 0.1))])
            let input = InputTargetComponent()

            // kinematic example
            let redBox = ModelEntity(
                mesh: .generateBox(size: 0.1),
                materials: [SimpleMaterial(color: .stepRed, isMetallic: false)])
            redBox.setPosition([-0.15, 0.2, 0.2], relativeTo: scene)
            let redPhysics = PhysicsBodyComponent(massProperties: .default, material: .default, mode: .kinematic)
            redBox.components.set([collision, input, redPhysics])
            content.add(redBox)

            // static example
            let greenBox = ModelEntity(
                mesh: .generateBox(size: 0.1),
                materials: [SimpleMaterial(color: .stepGreen, isMetallic: false)])
            greenBox.setPosition([-0, 0.1, 0.2], relativeTo: scene)
            let greenPhysics = PhysicsBodyComponent(massProperties: .default, material: .default, mode: .static)
            greenBox.components.set([collision, greenPhysics])
            content.add(greenBox)

            // dynamic example
            let blueBox = ModelEntity(
                mesh: .generateBox(size: 0.1),
                materials: [SimpleMaterial(color: .stepBlue, isMetallic: false)])
            blueBox.setPosition([0.15, 0.2, 0.2], relativeTo: scene)
            let bluePhysics = PhysicsBodyComponent(mode: .dynamic)
            blueBox.components.set([collision, input, bluePhysics])
            content.add(blueBox)

        }
        .modifier(DragGestureImproved())
    }
}

Download the Xcode project with this and many more examples from Step Into Vision.
Some examples are provided as standalone Xcode projects. You can find those here.