RealityKit Basics: pointing entities

Joseph Simpson

We can use `look(at:)` and its variants to point entities to new directions.

Overview

RealityKit entities have a number of instance methods for performing common actions. Today we’re going to take a look at look(at)†. We can use this method to change the direction that an entity is facing.

Example 1: Point the subject at another entity without moving it. We set the from value to the current position. We set relativeTo to the entity we are pointing, so the rotation takes place in that coordinate space.

subject.look(at: value.entity.position, from: subject.position, relativeTo: subject)

Example 2: We can specify an up vector to keep the subject aligned.

subject.look(at: value.entity.position, from: subject.position, upVector: [0, 1, 0], relativeTo: subject)

Example 3: We can set the forward direction for the method. Be default, entities in RealityKit have a forward vector of negative z. In this line we use positiveZ to cause the entity to look away from the target.

subject.look(at: value.entity.position, from: subject.position, upVector: [0, 1, 0], relativeTo: subject, forward: .positiveZ)

We can also adjust the new position passing a vector to the from augment. For example, if you wanted move the subject forward a bit, you could do something like this

subject.look(at: value.entity.position, from: subject.position + [0, 0, -0.1], relativeTo: subject)

I don’t find myself using this method too often. It is great for simply changing the direction of an entity. For just about anything else, I prefer to use the move() method.

Video Demo

Full Example Code

struct Example078: View {

    @State var subject = Entity()
    @State var box1 = Entity()
    @State var box2 = Entity()
    @State var box3 = Entity()

    var body: some View {
        RealityView { content in
            guard let scene = try? await Entity(named: "MoveToExamples", in: realityKitContentBundle) else { return }
            content.add(scene)

            guard let subjectEntity = scene.findEntity(named: "Subject") else { return }
            subject = subjectEntity

            guard let box1Entity = scene.findEntity(named: "Box_1") else { return }
            box1 = box1Entity

            guard let box2Entity = scene.findEntity(named: "Box_2") else { return }
            box2 = box2Entity

            guard let box3Entity = scene.findEntity(named: "Box_3") else { return }
            box3 = box3Entity

        } update: { content in

        }
        .gesture(tapSubect)
        .gesture(tapBox1)
        .gesture(tapBox2)
        .gesture(tapBox3)

    }

    var tapSubect: some Gesture {
        TapGesture()
            .targetedToEntity(subject)
            .onEnded { value in
                // Reset the subject transform to default
                let newTransform = Transform()
                subject.move(to: newTransform, relativeTo: value.entity.parent)
            }
    }

    var tapBox1: some Gesture {
        TapGesture()
            .targetedToEntity(box1)
            .onEnded { value in

                // Example 1: Point the subject at the red sphere without moving it
                subject.look(at: value.entity.position, from: subject.position, relativeTo: subject)

            }
    }

    var tapBox2: some Gesture {
        TapGesture()
            .targetedToEntity(box2)
            .onEnded { value in

                // Example 2: Point the subject at the entity, but specify the upVector so it doesn't end up rotated off axis
                subject.look(at: value.entity.position, from: subject.position, upVector: [0, 1, 0], relativeTo: subject)

            }
    }

    var tapBox3: some Gesture {
        TapGesture()
            .targetedToEntity(box3)
            .onEnded { value in

                // Example 3: Point the subject away from the entity by flipping the forward direction
                subject.look(at: value.entity.position, from: subject.position, upVector: [0, 1, 0], relativeTo: subject, forward: .positiveZ)
            }
    }
}

† haha yeah I did that on purpose, sorry

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.

Follow Step Into Vision

Questions or feedback?