Implementing SharePlay for immersive spaces in visionOS

At a glance

Project structure

Source bundle/
└── GroupActivities-SharePlayCube/
    ├── SharePlayCubeApp.swift  # SharePlayCubeApp
    ├── Models/
    │   ├── SessionController.swift  # SessionController
    │   ├── AppModel.swift  # AppModel
    │   ├── CubeActivityMessagingTypes.swift  # UpdateColorMessage, MessageUpdateCount, CubeColor
    │   └── ChangeColorActivity.swift  # ChangeColorActivity
    └── Views/
        ├── CubeImmersiveView.swift  # CubeImmersiveView
        └── SharePlayAttachmentView.swift  # SharePlayAttachmentView

Structure observations

• The runtime boundary is 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.

Overall architecture

flowchart LR
    SharePlayCubeApp_1["SharePlayCubeApp"]
    ImmersiveSpace_2["ImmersiveSpace"]
    CubeImmersiveView_3["CubeImmersiveView"]
    AppModel_4["AppModel"]
    RealityView_entity_graph_5["RealityView entity graph"]
    GroupActivities_session_6["GroupActivities session"]
    SharePlayCubeApp_1 --> ImmersiveSpace_2
    ImmersiveSpace_2 --> CubeImmersiveView_3
    CubeImmersiveView_3 --> AppModel_4
    AppModel_4 --> RealityView_entity_graph_5
    RealityView_entity_graph_5 --> GroupActivities_session_6

Reference code

GroupActivities-SharePlayCube/SharePlayCubeApp.swift:12 — the app or executable entry declares the outer scene lifecycle.

struct SharePlayCubeApp: 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
    SharePlayCubeApp *-- AppModel : appModel
    CubeImmersiveView o-- AppModel : appModel
    CubeImmersiveView *-- Entity : rootEntity
    AppModel --> SessionController : sessionController

Ownership evidence

GroupActivities-SharePlayCube/SharePlayCubeApp.swift:13 — representative stored state or the nearest verified lifecycle anchor.

    @State private var appModel = AppModel()

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, public, open; unmodified Swift declarations are internal.

Reference code

GroupActivities-SharePlayCube/Models/AppModel.swift:27 — representative visibility boundary.

    private(set) var color: CubeColor = .red

    init() {
        // ...
    }

Logic ownership and placement

Design patterns

Naming conventions

• Role suffixes are evidence, not decoration: App: SharePlayCubeApp; Model: AppModel; Controller: SessionController; View: CubeImmersiveView, SharePlayAttachmentView.
• Protocols: no app-defined protocol in the reviewed source.
• Commands use verb-led methods: endSession, observeUpdateColorMessages, syncColorChange, observeActiveRemoteParticipants, setColor, observeGroupSessions, changeColor, setUpRootEntity.
• Files generally match their primary type; Views, Models, Managers, Providers, Components, Systems, and Packages folders describe architectural roles where present.

Architecture takeaways

• Treat SharePlayCubeApp 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