Using Occlusion in Reality Kit


This 2nd tutorial on using Reality Kit. I recommend reading the 1st Reality Kit tutorial if you haven’t already.

For this simple example we are going to use a custom usdz file of an Apple. However, we could also use a simple primitive box or one of the assets which ships with Reality Composer to achieve the same result.

Download Page for the Apple above

Once you’ve finished downloading the Apple. Open up Xcode 11 and start a project with the Augmented Reality App template.


We want to achieve 4 main things in this tutorial

    1. Anchor a custom usdz file into our App on a horizontal surface
    2. Add tap gesture in our App, so we can control simple behaviours
    3. Add occlusion to our app to hide a custom usdz object with tap.
    4. Launch our App and test it on iOS13 or iPADOS device

In Xcode we will only need to work with the three areas I’ve circled in red.

    1. Edit ViewController.swift
    2. Edit Experience.rcproject
    3. Open Reality Composer

Build Reality Kit App in Xcode 11

Let’s first edit ViewController.swift

Remove all the template code and replace it with the code snippet below. The code is commented and self-explanatory. The code will basic anchor the Apple into the scene on the horizontal plane. When you tap the Apple, the scene will be covered over by a big occlusion sphere. Tapping again will remove the occlusion sphere.

import UIKit
import RealityKit

class ViewController: UIViewController {

@IBOutlet var arView: ARView!

override func viewDidLoad() {

// Load the "Box" scene from "Experience" Reality file

let boxAnchor = try! Experience.loadBox()

// Setup horizontal Anchor and add to arView

let anchor = AnchorEntity(plane: .horizontal, minimumBounds: [0.2, 0.2])


// setup tap gesture recognizer & add to arView

let tapGesture = UITapGestureRecognizer(target: self, action:#selector(onTap))


// Add the box anchor to the scene


@IBAction func onTap(_ sender: UITapGestureRecognizer) {

let tapLocation = sender.location(in: arView)

// Get the entity at the location we've tapped, if one exists

if let tappedEntity = arView.entity(at: tapLocation) {

// Create occlusion sphere to cover over Apple

let boxMesh = MeshResource.generateSphere(radius: 0.151)

let material = OcclusionMaterial()

let occlusionBox = ModelEntity(mesh: boxMesh, materials: [material]) = "Occlusion"

occlusionBox.position.y = 0.05

// check for occlusion mesh
if let occlusionMesh = tappedEntity.findEntity(named: "Occlusion") {

// Remove occlusion mesh

} else {


Now we are going to add the Apple4.usdz to our Experience.rcproject that we downloaded from

Go back into Xcode and click on the Experience.rcproject file in our Xcode project (left sidebar) and Open
Reality Composer inside Xcode (top right header bar).

Once inside Reality Composer – delete the cube by clicking on it with right click on the mouse. Then, click on the Objects + button at the top and import the Apple4.usdz file. To make an object clickable or tappable you need to setup the Apple4.usdz as a collision body. In Reality Composer set the Apple4.usdz to physics participate – as fixed. Now close Reality Composer as we don’t need to setup any behaviours and return to Xcode again.

We can now attach our iOS13 Device and build the app with the target device correctly selected. If everything is working as expected. The Apple should anchor on the horizontal and tapping the Apple will make it disappear… Re-tapping the position where the Apple was should make the Apple reappear.