Skip to content

Dynamic Objects

Dynamic Objects track moving/interactive entities during a participant session (position, orientation, scale, and object properties).

Required supporting files

Add these files to your app project:

  • DynamicObjectSystem.swift
  • DynamicComponent.swift
  • ImmersiveView+DynamicObject.swift

DynamicComponent.swift must be available in the Reality Composer Pro side where the component is authored.

Register component + system

DynamicComponent.registerComponent()
DynamicObjectSystem.registerSystem()

Register dynamic objects from a RealityView scene

func configureDynamicObjects(rootEntity: Entity) async {
    guard let objManager = Cognitive3DAnalyticsCore.shared.dynamicDataManager else {
        return
    }

    let dynamicEntities = findEntitiesWithComponent(rootEntity, componentType: DynamicComponent.self)

    for (_, comp) in dynamicEntities {
        await objManager.registerDynamicObject(
            id: comp.dynamicId,
            name: comp.name,
            mesh: comp.mesh
        )
    }
}

func findEntitiesWithComponent<T: Component>(_ entity: Entity, componentType: T.Type)
    -> [(entity: Entity, component: T)]
{
    var found: [(entity: Entity, component: T)] = []

    func walk(_ current: Entity) {
        if let comp = current.components[componentType] {
            found.append((entity: current, component: comp))
        }
        for child in current.children {
            walk(child)
        }
    }

    walk(entity)
    return found
}

RealityView { content, _ in
    if let immersiveRoot = try? await Entity(named: appModel.sceneInfo.usdName, in: realityKitContentBundle) {
        content.add(immersiveRoot)

        let core = Cognitive3DAnalyticsCore.shared

        // Required for gaze raycasts and dynamic-object collision association
        core.entity = immersiveRoot

        await configureDynamicObjects(rootEntity: immersiveRoot)
    }
}

Hand dynamic objects (v1.0.1)

If you track hands, register them with registerHand:

await objManager.registerHand(id: "HAND-LEFT-0001", isRightHand: false)
await objManager.registerHand(id: "HAND-RIGHT-0002", isRightHand: true)

This uses controller metadata (hand_left / hand_right) expected by the SDK.

Maintenance cleanup for long sessions (v1.0.1)

For very long runs, call cleanup periodically to prune stale state:

await objManager.performMaintenanceCleanup()

DynamicObjectSystem behavior

DynamicObjectSystem runs each frame, finds entities with DynamicComponent, and records updates only when thresholds/rates are met. It also emits enabled/disabled states when entities are removed or deactivated.

Using dynamic objects with SwiftUI windows

For SwiftUI windows, use a PositionTrackerView in each window and mirror those transforms to matching dynamic entities in your RealityView. This allows gaze/object analytics on windowed UI content in addition to immersive entities.

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.