About

What is SharePlayMock

SharePlayMock is an extension API of Apple's GroupActivities API. The goal of SharePlayMock is to make testing SharePlay feature of visionOS apps easier.

Without SharePlayMock, the only way to test a visionOS app's SharePlay feature is to ask a friend who has a vision pro to test with you, because you need to be in a FaceTime call to enable SharePlay.

However, SharePlay, at the essence, is just a message channel that helps you send messages to and receive messages from others in the same SharePlay session.

SharePlayMock, when enabled, establishes message channles using WebSocket among all participants, so that FaceTime call is not required anymore for testing. When SharePlayMock is disabled, the messages go through the official real SharePlay.

With SharePlayMock, developers can test their multiplayer logics themselves by running an app instance on the simulator and another app instance on the vision pro device.

(In Xcode, you can run multiple instances at the same time on different targets)

Use Cases & Limitations

SharePlayMock helps you test your multiplayer logics, such as syncing the sphere size in the tutorial app, or syncing card positions in a card game.

However it does not help with testing positioning of participants, for example whether they are side-by-side or surrounding or what the distance is between the volume and the participants. You need to update to visionOS 2.0 to test the positioning logic.

APIs & Example Code

On a high level, you use SharePlayMock by replacing various SharePlay identifiers (e.g. GroupActivity) with their SharePlayMock counterpart (e.g. GroupActivityMock).

1. GroupActivityMock
   

   
   class PlayTogetherGroupActivity: GroupActivityMock {
   
     typealias ActivityType = PlayTogetherGroupActivity.Activity
   
     private(set) var groupActivity: Activity
   
     init() {
       self.groupActivity = Activity()
     }
   
     struct Activity: GroupActivity {
       // Define a unique activity identifier for system to reference
       static let activityIdentifier = "com.spatialdevs.SharePlayTutorial.PlayTogether"
   
       var metadata: GroupActivityMetadata {
         var metadata = GroupActivityMetadata()
         metadata.title = "Spatial Devs SharePlay Tutorial"
         metadata.subtitle = "Let's play together!"
         metadata.previewImage = UIImage(named: "birdicon")?.cgImage
         metadata.type = .generic
         return metadata
       }
     }
   }
   

2. GroupSessionMock

   var sharePlaySession: GroupSessionMock<PlayTogetherGroupActivity>?

3. GroupSessionMessengerMock

   var sharePlayMessenger: GroupSessionMessengerMock?

4. GroupStateObserverMock

   @ObservedObject var groupStateObserver = GroupStateObserverMock()

5. ParticipantMock

    func sendMessage<T: Codable>(_ message: T, to predicate: @escaping (ParticipantMock) -> Bool, inSequence: Bool = true) {
      if let participants = self.groupSession?.activeParticipants.filter(predicate),
        participants.isEmpty == false {
          self.sendMessage(message, to: Participants.only(participants), inSequence: inSequence)
        }
    }

6. SystemCoordinatorMock

    if let systemCoordinator = await session.systemCoordinator { // systemCoordinator has type SystemCoordinatorMock
      var configuration = SystemCoordinator.Configuration()
      configuration.supportsGroupImmersiveSpace = true
      configuration.spatialTemplatePreference = .conversational
      systemCoordinator.configuration = configuration
   
      self.tasks.insert(
         Task.detached { @MainActor in
             for await immersionStyle in systemCoordinator.groupImmersionStyle {
                 if let immersionStyle {
                     await openImmersiveSpace(id: "ImmersiveSpace")
                 } else {
                     await dismissImmersiveSpace()
                 }
             }
         }
     )
    }

Integration Instructions

This instruction assumes you already have a visionOS project and used GroupActivities API and enabled SharePlay for your app/game.

For a more detailed tutorial, go here.

1. Download SharePlay Mock server (We're working on a P2P version so you don't have to run a local server to do local testing)
   1. Brew install java
      

      brew install openjdk@17

   2. Download SharePlayMock Server jar file
      https://github.com/Pixeland-Tech/SharePlayMock/releases/tag/placeholder-tag-0.1.0
      
      

      Note: This repo does NOT include the source code of this jar file.

2. Add SharePlayMock package to project
   1. Open your visionOS project in Xcode
   2. Go to File -> Add Package Dependencies... -> Search or Enter Package URL -> Enter "https://github.com/Pixeland-Tech/SharePlayMock" -> Dependency Rule select "Branch", input "visionOS2" -> Add Package
   3. Under "Add to Target", select your project, then click "Add Package"

3. Modify code

   1. Enable mock on App init

      struct SharePlayTutorialApp: App {
      init() {
        SharePlayMockManager.enable(webSocketUrl: "ws://<your_local_ip_address>:8080/endpoint") // e.g. ws://192.168.50.103:8080/endpoint
      }
      ...
      }

      To find out your local IP, go to System Settings -> Wi-Fi -> "Details" button of your connected wifi -> IP address

      Note: You need to manually enable/disable Mock. To disable Mock, simply comment out this line of code.
      When Mock is enabled, all SharePlay messages will go through the websocket.
      When Mock is disabled, all SharePlay messages will go through the official SharePlay.

      ⚠️ Important: Comment out this line of code before publishing your app!! This line should only be added during testing.

   2. Replace all the APIs below

   GroupActivities	SharePlayMock
   GroupActivity	GroupActivityMock
   GroupSession	GroupSessionMock
   GroupSessionMessenger	GroupSessionMessengerMock
   GroupStateObserver	GroupStateObserverMock
   Participant	ParticipantMock
   SystemCoordinator	SystemCoordinatorMock

4. Test code
   1. Spin up websocket server Open a terminal and run

      java -jar /<your_path_to_the_jar_file>/shareplay-mock-server-0.1.0.jar

   2. Run your app on Simulator
   3. Connect your vision pro to Xcode and run your app on your vision pro. In Xcode, you can run 2 app instances at the same time on different targets.
   4. In your app, turn on SharePlay using the UI/feature you built for your app.
   5. The app on the simulator and the app on your device should now be connected and you can test and debug your code.

Contact

Spatial Devs Discord Server

support@pixeland.tech