Creating a navigation mesh with Reality Composer Pro

At a glance

Project structure

RCP-NavigationMesh.xcodeproj/        one app target, one remote package product
RCP-NavigationMesh/                  synchronized root group for the app target
├── RCPNavigationMeshApp.swift       @main App: runtime setup + scene selection
├── ContentView.swift                RealityView: load "world", add camera, input
├── rcp-navigationmesh.reality       exported scene the app loads at run time
└── Assets.xcassets
rcp-navigationmesh.realitycomposerpro/   authoring project (not in the target)
├── Entities/        world, Player, NavigationTargetMarker
├── Behaviors/       Player_Behavior behavior tree
└── Script Graphs/   TapTerrain, PlayerLogic, PlayerModelLogic, ...
Info.plist                           visionOS-only scene manifest
Configuration/SampleCode.xcconfig

Structure observations

• The target has a single app product. Its only package product dependency is RealityKitScripting (RCP-NavigationMesh.xcodeproj/project.pbxproj:90), resolved from a remote repository with an up-to-next-minor requirement starting at 1.4.0 (RCP-NavigationMesh.xcodeproj/project.pbxproj:387). There is no local Swift package and no Package.swift in the tree.
• RCP-NavigationMesh/ is a PBXFileSystemSynchronizedRootGroup (RCP-NavigationMesh.xcodeproj/project.pbxproj:23). The exported rcp-navigationmesh.reality file sits in that folder next to the Swift files. Inference: that placement is what lets Entity(named: "world") find the scene in the app bundle at run time.
• The rcp-navigationmesh.realitycomposerpro authoring project is not referenced by the Xcode project. Its asset files hold the navigation behavior. Entities/world.tm_entity contains a tm_navigation_mesh_component. Entities/Player.tm_entity contains tm_navigation_component and tm_re_behavior_tree_component. Behaviors/Player_Behavior.tm_behavior_tree uses a BTMoveOnNavMeshNodeDefinition node. This is a deliberate split: code handles hosting, assets handle gameplay.
• The root Info.plist applies only to visionOS SDKs (INFOPLIST_FILE[sdk=xros*]). It makes an immersive space the preferred default scene role, with mixed immersion (Info.plist:8, Info.plist:16).

Platform boundary

Apple’s documentation lists iOS, iPadOS, Mac Catalyst, macOS, and visionOS. The project file lists iphoneos, macosx, and xros as supported platforms and sets SUPPORTS_MACCATALYST = NO (RCP-NavigationMesh.xcodeproj/project.pbxproj:185). The downloaded project therefore builds native macOS rather than Mac Catalyst. The front matter keeps Apple’s documented platform list.

Overall architecture

flowchart LR
    App["RCPNavigationMeshApp"] -->|init| RT["ScriptingRuntime.setup"]
    App -->|visionOS| IS["ImmersiveSpace"]
    App -->|other platforms| WG["WindowGroup"]
    IS --> CV["ContentView"]
    WG --> CV
    CV -->|await| Load["Entity(named: world)"]
    Load --> Asset["rcp-navigationmesh.reality"]
    CV -->|input| Graphs["Script graphs + behavior tree"]

Reference code

RCP-NavigationMesh/RCPNavigationMeshApp.swift:19 — RCPNavigationMeshApp.init and body

@main
struct RCPNavigationMeshApp: App {
    // ...
    init() {
        // The scene doesn't use hand tracking or world sensing, so it skips
        // the ARKit input provider.
        ScriptingRuntime.setup(inputOptions: .all.subtracting(.ar))
    }

    var body: some Scene {
        #if os(visionOS)
        // An immersive space is unbounded, so the level isn't clipped to a box
        // and the person wearing the device can walk around it.
        ImmersiveSpace {
            ContentView()
        }
        #else
        WindowGroup {
            ContentView()
        }
        .defaultSize(width: Self.windowSize, height: Self.windowSize)
        #endif
    }
}

Interpretation

Observed: the app entry point does two things. It configures the scripting runtime synchronously in init, and it picks a scene type at compile time. Both branches host the same ContentView, so platform differences stay in the scene declaration and a single #if !os(visionOS) block in the view.

Inference: running ScriptingRuntime.setup in App.init ensures the runtime is configured before any RealityView loads entities that carry script graphs. The source comment explains only why AR input is excluded, not the ordering, so treat the ordering rationale as inference.

Ownership and state

classDiagram
    RCPNavigationMeshApp *-- ContentView : creates in scene body
    ContentView --> RealityViewContent : adds entities
    RealityViewContent o-- Entity : world (loaded asset)
    RealityViewContent o-- PerspectiveCamera : non-visionOS only

Ownership evidence

RCP-NavigationMesh/ContentView.swift:15 — RealityView make closure

struct ContentView: View {

    var body: some View {
        RealityView { content in
            // The Reality Composer Pro project exports a scene named "world".
            let world: Entity
            do {
                world = try await Entity(named: "world")
            } catch {
                print("Failed to load the scene named \"world\": \(error)")
                return
            }
            content.add(world)
            // ...
        }
        // Sends taps and drags to the script graphs on the scene's entities.
        .enableRealityKitScriptingInput()
    }
}

Observed: ContentView has no stored properties, no @State, and no references to entities after the make closure returns. After content.add, the Swift code never mutates the scene. Inference: the entities’ runtime state belongs to the scripting runtime and RealityKit. The source does not show which framework object retains them.

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

Task retention and cancellation: the sample creates no task, so it has nothing to retain or cancel. If loading fails, the closure logs with print and returns before adding anything (RCP-NavigationMesh/ContentView.swift:21).

Reference code

RCP-NavigationMesh.xcodeproj/project.pbxproj:186 — target concurrency settings

SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor;

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

Reference code

RCP-NavigationMesh.xcodeproj/project.pbxproj:387 — remote package requirement

repositoryURL = "https://github.com/apple/realitykitscripting";
requirement = {
    kind = upToNextMinorVersion;
    minimumVersion = 1.4.0;
};

Class and protocol design

The sample declares only two types, both value types that conform to SwiftUI protocols. It declares no local protocols, classes, RealityKit Component types, or System types. A class diagram would not add information.

RCP-NavigationMesh/ContentView.swift:12 — ContentView

struct ContentView: View {

    var body: some View {
        RealityView { content in
            // ...
        }
        // Sends taps and drags to the script graphs on the scene's entities.
        .enableRealityKitScriptingInput()
    }
}

Access control

Reference code

RCP-NavigationMesh/RCPNavigationMeshApp.swift:14 — conditional constant

@main
struct RCPNavigationMeshApp: App {

    #if !os(visionOS)
    /// The width and height of the window that holds the scene, in points.
    static let windowSize = 800.0
    #endif
    // ...
}

The sample uses conditional compilation rather than access modifiers to separate platform concerns. It has no private or fileprivate members because neither type holds mutable state.

Logic ownership and placement

Design patterns

No named design pattern is supported. The Swift code composes framework types directly. The project does show one structural decision worth studying: gameplay is data-driven and lives outside the code. The Swift layer is a thin host that installs the runtime, loads the asset, and routes input. The navigation component, navigation mesh, and behavior tree are defined in the Reality Composer Pro project. This is described here as a project-structure observation, not as a named pattern (RCP-NavigationMesh/ContentView.swift:40).

Main application flow

The sequence-diagram checks are not all satisfied. The app has one async load, and the order of tap handling inside the scripting runtime is not visible in Swift. The flow is therefore described in prose:

1. App.init calls ScriptingRuntime.setup (RCP-NavigationMesh/RCPNavigationMeshApp.swift:22).
2. The scene body builds ContentView inside the scene type chosen for the platform.
3. The RealityView make closure awaits Entity(named: "world") and adds the result (RCP-NavigationMesh/ContentView.swift:24).
4. Taps reach the script graphs through .enableRealityKitScriptingInput(). From there, the asset’s TapTerrain and PlayerLogic script graphs and the Player_Behavior tree move the player. That last step is visible only in asset names, not in Swift.

Naming conventions

• Types: RCPNavigationMeshApp follows the <ProductName>App convention, with the RCP prefix taken from the target name RCP-NavigationMesh. ContentView is the Xcode-template root view name.
• Asset identifiers: the Swift code refers to the exported scene by the string "world", which must match the root entity name in the Reality Composer Pro project (Entities/world.tm_entity). The coupling is a single literal, not a named constant.
• Asset folders: Reality Composer Pro groups its assets by role (Entities, Behaviors, Script Graphs). Script graphs are named <Entity>Logic (PlayerLogic, NavigationTargetMarkerLogic) or after an action (TapTerrain).
• Protocols: none declared.
• Files: one primary type per file, and each file is named after its type.

Architecture takeaways

• A thin Swift host can run a full gameplay loop. The navigation mesh, navigation component, and behavior tree are assets, and Swift only installs the runtime and loads the scene.
• Global framework runtimes are configured in App.init, before any RealityView loads content that depends on them.
• Platform divergence is pushed to two seams: the scene type in App.body, and a #if !os(visionOS) camera block in the view. The rest of the code is shared.
• Concurrency is minimal and framework-owned. RealityView creates the only async context, and the target’s default MainActor isolation covers everything else.
• The coupling between code and asset is a single string, "world". Renaming the root entity in Reality Composer Pro breaks loading at run time, not at compile time.

Source map

• Official Apple documentation