Enabling video reflections in an immersive environment

At a glance

Project structure

Source bundle/
├── DestinationVideo/Model/visionOS/ImmersiveEnvironment.swift  # ImmersiveEnvironment, ImmersiveSpaceState
├── DestinationVideo/Model/visionOS/EnvironmentStateHandler.swift  # EnvironmentStateType, EnvironmentStateHandler
├── DestinationVideo/Views/visionOS/ImmersiveEnvironmentView.swift  # ImmersiveEnvironmentView
├── DestinationVideo/DestinationVideo.swift  # DestinationVideo
├── DestinationVideo/ContentView.swift  # ContentView
├── DestinationVideo/Player/PlayerModel.swift  # Presentation, PlayerModel, PlayerViewObserver
├── DestinationVideo/Player/SystemPlayerView.swift  # SystemPlayerView, Coordinator, SystemPlayerView
├── DestinationVideo/SharePlay/WatchingCoordinator.swift  # WatchingCoordinator, PlaybackCoordinatorDelegate
└── Packages/Studio/Package.realitycomposerpro/ProjectData/main.json  # authored RealityKit content

Structure observations

• The runtime boundary is WindowGroup + ImmersiveSpace; the pruned tree lists only files that explain lifecycle, state, or framework integration.
• App code is split into role-named views, models, managers, providers, components, or systems.
• Authored .reality or Reality Composer Pro content is a real implementation boundary; Swift loads or drives it rather than reproducing its entity graph.
• Uses the Destination Video archive but focuses on the immersive-environment state and RealityKit environment-probe updates that produce reflected video lighting.

Overall architecture

flowchart LR
    DestinationVideo_1["DestinationVideo"]
    WindowGroup___ImmersiveSpace_2["WindowGroup + ImmersiveSpace"]
    ContentView_3["ContentView"]
    PlayerModel_4["PlayerModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    AV_playback___system_presentation_6["AV playback + system presentation"]
    DestinationVideo_1 --> WindowGroup___ImmersiveSpace_2
    WindowGroup___ImmersiveSpace_2 --> ContentView_3
    ContentView_3 --> PlayerModel_4
    PlayerModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> AV_playback___system_presentation_6

Reference code

DestinationVideo/DestinationVideo.swift:14 — the app or executable entry declares the outer scene lifecycle.

struct DestinationVideo: App {
    // ...
}

The diagram is a responsibility flow, not a claim that every adjacent node directly calls the next. It keeps scene ownership, shared state, RealityKit content, and framework-provider work at separate levels.

Ownership and state

classDiagram
    DestinationVideo *-- PlayerModel : player
    DestinationVideo --> ModelContainer : modelContainer
    ContentView o-- PlayerModel : player
    DestinationVideo *-- ImmersiveEnvironment : immersiveEnvironment

Ownership evidence

DestinationVideo/DestinationVideo.swift:19 — representative stored state or the nearest verified lifecycle anchor.

@main
struct DestinationVideo: App {
    // ...
    @State private var player: PlayerModel
    // ...
}

Ownership here is deliberately narrow: @Environment and weak references are shared links, initialized @State or stored services are lifecycle ownership, and a RealityView content closure owns additions to its entity graph without making the SwiftUI view a reference-type owner.

Class and protocol design

The source defines no local substitution protocol in the reviewed boundary. Its protocol use is framework-facing (App, View, RealityKit/ARKit protocols, or platform adapters), so this document does not label the whole app protocol-oriented.

Access control

No reviewed declaration uses fileprivate, open; unmodified Swift declarations are internal.

Reference code

DestinationVideo/Model/visionOS/EnvironmentStateHandler.swift:45 — representative visibility boundary.

    public private(set) var activeState: EnvironmentStateType = .none

    public func gatherEntities(from rootEntity: Entity?) {
        // ...
    }

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: Model: PlayerModel; Coordinator: Coordinator, WatchingCoordinator; Delegate: PlaybackCoordinatorDelegate; View: CategoryListView, CategoryView, ContentView, DetailView, GenreView.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: loadEnvironment, clearEnvironment, requestEnvironmentState, setEnvironmentState, findCommonEntityByName, setVirtualEnvironmentProbeComponent, gatherEntities, setActiveState.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat DestinationVideo as the owner of scene declarations, not as the owner of every RealityKit entity created later.
• Keep view-local interaction in SwiftUI, but move provider sessions, playback resources, shared game state, or transport state into a stable owner when their lifetime exceeds one render pass.
• Model immersive-space open, transition, and close states explicitly so windows and immersive content cannot drift apart.

Source map

• Official Apple documentation