Creating animation graphs with Reality Composer Pro and RealityKit

At a glance

Project structure

AnimationGraph.xcodeproj/        one app target, no package references
AnimationGraph/                  synchronized root group (Info.plist excluded)
├── AnimationGraphApp.swift      @main App: one WindowGroup, volumetric on visionOS
├── Views/
│   └── ContentView.swift        OwlConstants, logger, ContentView
├── AnimationGraph.reality       exported scene the app loads at run time
├── Info.plist                   volumetric default scene role
└── Supporting Files/Assets.xcassets
AnimationGraph.realitycomposerpro/   authoring project (not in the target)
├── Owl Animation Graph.tm_animation_graph
├── world.tm_entity
└── Animations/   fly, hover, perch clips
Configuration/SampleCode.xcconfig

Structure observations

• The Xcode project has one app target, and its packageReferences list is empty (AnimationGraph.xcodeproj/project.pbxproj:134). There is no local Swift package and no Package.swift.
• AnimationGraph/ is a synchronized root group. Info.plist is listed in its membership exceptions, which excludes the file from the target’s synchronized membership (AnimationGraph.xcodeproj/project.pbxproj:24). Instead, the file is referenced through INFOPLIST_FILE (AnimationGraph.xcodeproj/project.pbxproj:299).
• Swift files are grouped by role: the entry point sits at the folder root and the only view sits in Views/. The exported AnimationGraph.reality sits inside the synchronized folder. Inference: that placement is what lets Entity(named:) load the scene from the app bundle.
• The authoring project holds the behavior. world.tm_entity contains an owl_model entity with a tm_re_animation_graph_component. Owl Animation Graph.tm_animation_graph defines parameters named moving and speed, the same strings that OwlConstants uses in Swift.

Platform boundary

Apple’s documentation lists iOS, iPadOS, Mac Catalyst, macOS, and visionOS. The project’s supported platforms also include appletvos, with device family 3 (AnimationGraph.xcodeproj/project.pbxproj:332), so tvOS is added to the front matter. The project sets no SUPPORTS_MACCATALYST key and includes macosx, so the downloaded project targets native macOS. Mac Catalyst is kept in the front matter because Apple’s documentation lists it.

Overall architecture

flowchart LR
    App["AnimationGraphApp"] --> WG["WindowGroup (volumetric on visionOS)"]
    WG --> CV["ContentView"]
    CV -->|await| Load["Entity(named: world)"]
    Load --> Owl["owl_model Entity"]
    Controls["Toggle / Slider"] -->|Binding| State["@State moving, speed"]
    State -->|onChange| Params["owl.parameters"]
    Params --> Graph["Animation graph (asset)"]
    Owl --- Params

Reference code

AnimationGraph/AnimationGraphApp.swift:10 — AnimationGraphApp

@main
struct AnimationGraphApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        #if os(visionOS)
        .windowStyle(.volumetric)
        .defaultSize(width: 0.3, height: 0.25, depth: 0.3, in: .meters)
        #endif
    }
}

Interpretation

Observed: the app is a single scene with a single view. ContentView combines asset loading, entity lookup, the UI controls, and the bridge from SwiftUI state to entity parameters. It does not use a separate model object. The animation graph asset owns the blending and the state-machine transitions. Swift only writes the graph’s input parameters.

Inference: the sample is meant to teach the parameter boundary. Swift drives a small number of named inputs, and the designer-authored graph turns them into animation. That keeps animation logic out of code.

Ownership and state

classDiagram
    AnimationGraphApp *-- ContentView : creates in WindowGroup
    ContentView *-- moving : @State Bool
    ContentView *-- speed : @State Float
    ContentView o-- Entity : @State owl (found in loaded scene)
    Toggle --> moving : Binding
    Slider --> speed : Binding

Ownership evidence

AnimationGraph/Views/ContentView.swift:22 — ContentView state

struct ContentView: View {
    @State var owl: Entity?
    @State var moving = false
    @State var speed: Float = 0.0
    // ...
    @ViewBuilder
    var animationControls: some View {
        Toggle("Moving", isOn: $moving)
        Slider(value: $speed, in: 0...1) {
            Text("Speed")
        }.frame(idealWidth: 200.0)
    }
}

Observed: SwiftUI state is the source of truth for both parameters. Updates flow one way, from SwiftUI to the entity. No code reads parameter values back from the graph.

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. Load failures are logged with logger.error (AnimationGraph/Views/ContentView.swift:46).

Ordering detail (observed): if the user changes a control before the load finishes, the onChange write does nothing because owl is still nil. Once the load completes, the parameters are seeded from the current moving and speed values (BindableValue(moving)). Inference: the code that runs after the load reads the current state, so early edits are not lost.

Reference code

AnimationGraph/Views/ContentView.swift:28 — load, seed, and update

struct ContentView: View {
    // ...
    var body: some View {
        VStack {
            RealityView { content in
                do {
                    // ...
                    let mainScene = try await Entity(named: OwlConstants.worldEntity)
                    content.add(mainScene)
                    // ...
                    self.owl = mainScene.findEntity(named: OwlConstants.owlName)
                    guard let owl else {
                        logger.error("\(OwlConstants.owlName) was not in scene \(OwlConstants.worldEntity)")
                        return
                    }
                    // ...
                    owl.parameters[OwlConstants.movingParameter] = BindableValue(moving)
                    owl.parameters[OwlConstants.speedParameter] = BindableValue(speed)
                } catch {
                    logger.error("Failed to load scene: \(error)")
                }
            }.onChange(of: moving) {
                owl?.parameters[OwlConstants.movingParameter]?.value = moving
            }.onChange(of: speed) {
                owl?.parameters[OwlConstants.speedParameter]?.value = speed
            }
            // ...
        }
    }
}

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.

Class and protocol design

The sample declares three types and no local protocols, classes, RealityKit Component types, or System types. A class diagram would not add information.

AnimationGraph/Views/ContentView.swift:12 — OwlConstants

enum OwlConstants {
    static let worldEntity = "world"
    static let owlName = "owl_model"
    static let movingParameter = "moving"
    static let speedParameter = "speed"
}

Observed: OwlConstants is a caseless enum, so it cannot be instantiated. It collects every string that must match the Reality Composer Pro project in one place.

Access control

Reference code

AnimationGraph/Views/ContentView.swift:19 — module-wide logger

let logger = os.Logger(subsystem: "com.example.apple-samplecode", category: "AnimationGraph")

The source contains no explicit private, fileprivate, public, or open modifier. Every boundary is the default module-internal scope.

Logic ownership and placement

Design patterns

Removed from consideration: no MVVM, store, or observable model exists, and no ECS System is declared in Swift. The parameter bridge is direct, view-owned code, so it gets no separate pattern label.

Naming conventions

• Types: AnimationGraphApp follows the <ProductName>App convention. ContentView is the template root view name. OwlConstants follows the <Domain>Constants convention for a namespace enum.
• Constants: names describe their role in the asset contract. Entity names end in Entity or Name (worldEntity, owlName), and graph inputs end in Parameter (movingParameter, speedParameter). The values are the exact asset identifiers ("owl_model", "moving").
• Properties: state uses plain nouns and adjectives (owl, moving, speed). The control group is a computed property named for its content (animationControls).
• Files and folders: the entry point is at the root and views go in Views/. Resources go in Supporting Files/.
• Protocols: none declared.

Architecture takeaways

• Treat an animation graph’s parameters as an interface between code and asset. Swift writes a few named inputs, and the designer-authored graph owns blending and transitions.
• Put every string the code shares with the asset in one namespace (OwlConstants), so renaming an asset changes code in one place.
• Seed parameters after the async load from the current state, then push changes with onChange. Optional chaining handles changes made before the entity exists.
• State flows one way: control, then binding, then @State, then onChange, then the entity parameter. No code reads values back from the graph.
• Concurrency is framework-owned. RealityView creates the only async context, and the target’s default MainActor isolation covers the view’s state.

Source map

• Official Apple documentation