Stay organized with collections Save and categorize content based on your preferences.

Quickstart

In this quickstart, you learn how to get started with Immersive Stream for XR from Google Cloud. You will use Unreal Engine® and the Immersive Stream for XR template project to create experiences and then build and deploy them to the service. Your end users can access these experiences from the Google app for Android or iOS by visiting a universal URL.

Figure 2

Before you begin

Make sure you have access to the following requirements:

  • Workstation with these minimum specifications, which mirror the Unreal Editor requirements:
    • Windows 10
    • Higher-end CPU (12 cores or more, such as an AMD Ryzen 9)
    • 16 GB RAM or more
    • GTX 1070 GPU or better
  • Google Cloud account with the permissions to create new projects.
  • Supported mobile device with up-to-date Google app

Set up storage

This section is for the Google Cloud admin in your organization.

Set up Google Cloud project

Estimated time: 30 minutes

  1. Create a new Google Cloud project.
  2. Create a Cloud Storage bucket in this project:
    1. Go to Cloud Storage and click Create Bucket.
    2. Choose a name for the bucket. The name must be globally unique. (The system displays an error if the name is in use). Leave the rest of the default settings unchanged.
  3. Click Create.

Once you create a Content and Service Instance you can generate a URL to launch and test the experience in your browser.

Creator's flow

This section is intended for the team creating or developing the immersive experience.

Install Unreal Engine

Estimated time: 30 minutes

  1. On the download page for Unreal Engine, download and install Unreal Engine for Creators.
  2. After the Epic Games launcher is installed, open the launcher and download version 4.27.2 of the engine.

If you need help with the installation, Unreal Engine provides a video tutorial.

Downloading the template project

Estimated time: 20 minutes

  1. Download the latest template project zip file.
  2. Extract the file in a location where you place Unreal projects. For example: C:\users\xyz\projects\immersive-stream
  3. Open the XR_Template.uproject file.
  4. Select Unreal Engine version 4.27 as the default engine version for this project.

Setting up Google Cloud SDK

Estimated time: 20 minutes

  1. If you haven't already, create a Google Cloud user account with the email address you plan to share with the owner of the bucket. Download the Google Cloud SDK.
  2. Install the SDK.
  3. Initialize the Google Cloud SDK using the gcloud init command and follow the prompts. For more information about this step, see the initializing documentation.

Iterating on Content

Estimated time: 60 minutes (depends on the changes that you make to the content)

  1. After you open the template project following the previous steps, you can view the content in the Main_Persistent.umap that loads by default. Learn more about the template-project.
  2. Modify something within a level and save. You can change streaming maps in that level or open the map independently. To select a level, in the Levels panel, double click the level you want to modify.
  3. Preview in engine by playing or simulating while Main_Persistent.umap is loaded.
  4. Upload content to bucket and trigger build:
    1. Use .\XR_Actions\SyncContent.ps1 to upload your updated Unreal Engine project to your Cloud Storage bucket.
    2. Initiate building a new content version using the build command.
    3. After the build finishes and a new content version is created, update the instance with the new content version.

Immersive Stream for XR detects the project file and builds the game image using our modified version of Unreal Engine, and uploads the image to the Google Cloud streaming project. In the first run, you will upload approximately 3 GB. Subsequent runs will only upload changed files and can take about 30 minutes.

Build and deploy Content

The Immersive Stream for XR interfaces are designed around two core aspects of the service:

  • Content creation and management
  • Cloud streaming

As a result, the APIs model two resources:

  • Content Resource
  • Service Instance

Diagram of the storage bucket, content resource, and service instance

You can have more than one of these resources. For example:

Two XR experiences with their own set resources

Each instance is deployed in Google Cloud regions.

Complete the following steps to enable an Immersive Stream for XR experience using the interfaces. You can use the Cloud Shell in the Cloud console.

Development cycle

Prerequisites

Estimated time: 10 minutes

  1. Verify that the account has the IAM permission serviceusage.services.enable for the cloud project you want to use. The account is granted this permission if it has the Service Usage Admin, Editor, or Owner role in the project.
  2. Enable the Immersive Stream for XR service in your project by running the following command. For this example, we'll use my-project as the project ID.

    gcloud services enable stream.googleapis.com --project my-project
    
  3. Look up the project number for your project:

    gcloud projects describe my-project
    
  4. Set the gcloud CLI context to use this project number:

    gcloud config set project my-project-number
    
  5. Install the alpha command component of gcloud CLI:

    gcloud components install alpha
    
  6. Ensure gcloud CLI is up to date:

    gcloud components update
    

Content creation

Estimated time: four hours

  1. Create a Cloud Storage bucket in the same project where you've enabled the Stream API. For this example, we assume you have created a bucket named my-gcs-bucket in our project and it's accessible at gs://my-gcs-bucket.
  2. Once you have a bucket, create a Content resource pointing to your bucket. You must pick a name for the content id (my-content):

    gcloud alpha immersive-stream xr contents create my-content --bucket=my-gcs-bucket --async
    

    This is an asynchronous operation, describe the content to see its status:

  3. To start developing your immersive experience, download and edit the Immersive Stream for XR template project files in your Windows PC.

  4. Describe the Content and check if it's ready to use. Describing it shows the CREATING lifecycle state before the creation completes, or the READY lifecycle state when it's ready.

    gcloud alpha immersive-stream xr contents describe my-content
    

    Output:

    createTime: '2021-12-07T18:40:08.#######'
    lifecycleState:
      description: 'Creation operation: projects/my-project-number/locations/global/operations/operation-####'
      state: CREATING
    name: projects/my-project-number/locations/global/streamContents/my-content
    updateTime: '2021-12-07T18:41:33.#######'
    
  5. (Recommended) Wait one hour for the content builder to prewarm after the Content is ready.

  6. On your windows machine, where you downloaded and extracted the template project, run SyncContent.ps1 in a PowerShell script to upload the Unreal Engine project to the Cloud Storage bucket associated with your content.

    PowerShell
    .\XR_Actions\SyncContent.ps1 my-gcs-bucket
  7. Build the Unreal Engine project that is uploaded to your Cloud Storage bucket using the build command.

    gcloud alpha immersive-stream xr contents build my-content --version=my-version --async
    
  8. Describe the Content periodically with the gcloud alpha immersive-stream xr contents describe my-content command to check the status of the build. Describing it initially shows a Builder is building ... message in the lifecycle state description. After the build completes successfully, the description will change to Builder finished building ... The first build process takes up to four hours to complete, and the following builds take about 30 minutes to complete for the template project content. Once you start iterating over the project, the build time will depend on your specific assets and settings.

  9. (Optional) If the build failed in the previous step, you can find where the Unreal Engine build log is stored by running the contents describe command:

    gcloud alpha immersive-stream xr contents describe my-content
    

    The build log is a Cloud Storage object (for example, gs://{YOUR_CLOUD_PROJECT_ID}_immersive_stream_xr/.../build.log). You can view the log in the Cloud Storage console or use the gsutil command line tool to copy it locally.

  10. Iterate and build other versions as needed.

    gcloud alpha immersive-stream xr contents describe my-content
    
  11. (Optional) You can also configure a custom fallback URL to send users to when your instance server is stocked out, there is a failed connection, or there are other issues that prevent the experience from continuing.

    Follow these steps to set up a server fallback URL:

    1. Create a file named uiconfig.json with the following contents:

      {
          "fallback_config": {
              "link_url": "YOUR_LINK_URL"
          }
      }
      
    2. Replace YOUR_LINK_URL with your fallback URL.

    3. Upload the configuration file to the bucket (my-gcs-bucket) you have created for the content.

    4. Apply the configuration to your instance by running this command:

      gcloud alpha immersive-stream xr contents update <content-name> --uiconfig --async
      

    Once your service is turned up, the fallback URL will take effect on your instance.

Service turnup

Estimated time: one hour

  1. Determine the regions, the number of streaming servers that should be launched per region and create a Immersive Stream for XR Service Instance. This capacity represents the maximum number of concurrent sessions you can serve from each region. Note that the content must be built before the instance is created, the newly created instance is initialized with the specified content version.

    gcloud alpha immersive-stream xr instances create my-instance --content=my-content --version=my-version-tag --add-region="region=us-central1,capacity=1" --add-region="region=us-west1,capacity=3" --async
    

    Not all Google Cloud regions are supported. The list of supported Google Cloud regions will expand and is subject to change in future versions. The Immersive Stream for XR will manage the deployment and load distribution within a region.

Google Cloud region Location
us-central1 Council Bluffs, Iowa, North America
us-east4 Ashburn, Virginia, North America
us-west1 The Dalles, Oregon, North America
asia-northeast1 Tokyo, Japan, APAC
asia-southeast1 Jurong West, Singapore, APAC
europe-west4 Eemshaven, Netherlands, Europe
This is an asynchronous operation. Describe the content to see its status:
  1. Describe the Instance and check if the instance was updated with the new content version. Describing it shows that the CREATING lifecycle state before the creation completes. After your Instance is successfully created, describing it shows the READY lifecycle state along with other metadata about the instance including the current content version.

    gcloud alpha immersive-stream xr instances describe my-instance
    

Update instance with new content version

Estimated time: 15 minutes

  1. Update the instance in all regions of the instance deployment. The update may take up to 15 minutes to take effect. You can verify the update by using the following URL in a browser.

    gcloud alpha immersive-stream xr instances update my-instance --version=my-version --async
    
  2. To update an instance with a different version of Content, repeat the above step with the intended version. Make sure a Content build with the given version exists or build the Content.

Launch the experience

Estimated time: 20 minutes

URL Creation

You can create URLs to launch an Immersive Stream for XR experience using this web tool Input the Endpoint URL, API Key, and Cloud AR Asset ID values and click Create for the desired output URL.

Immersive Stream Link Generator

There are 2 types of URLs you can generate:

  1. Cross-Platform: A dynamic link that works for all platforms. When accessing from unsupported devices (for example, from a desktop computer) the page displays a QR code that you can scan with your device to access the experience.
  2. Web (Experimental): A URL to launch in your web browser 3D mode only experiences. The web browser client supports Safari on iOS devices. The web client has experimental support for Safari and Chrome browsers on desktop.

Customer or Google hosted web pages

You can use the following options to drive the user to the correct experience for each platform:

  1. Use the cross platform URL, which automatically triggers the correct experience based on the user's platform. On a desktop, the URL launches a web page that displays a QR code to scan on a device.
  2. Host an Entry page on your end that detects the user's platform and redirects them to the experience on Android and iOS or shows a QR code allowing them to easily access the same page from their Android or iOS device.

Customer hosted and Google hosted workflows

Here are examples of behavior of the Customer Hosted option:

  • iPhone or Android: Send the user to a cross-platform redirect link.
  • Other devices: Show a QR code on a web page that points to a cross-platform redirect link.

Other pages hosted by the customer:

  • Landing page: Your user gets redirected to this page when clicking on the logo at the top of the screen.
  • Retry page: Your user gets redirected to this page when we could not establish a connection (for example, when the user's internet connection does not meet the requirements).

To set these pages for your experience, specify the link in a file within the project folder together with the logo. See Logo and attribution for instructions.

Change the capacity of instances

Estimated time: 10 minutes

You can change the capacity of your instances one region at a time. To update instances in multiple regions, you must change the capacity in each region individually.

To change the instance capacity in a region, run the following command:

    gcloud alpha immersive-stream xr instances update my-instance --update-region="region=<region>,capacity=<new-capacity>"

The new capacity must be greater than zero and cannot exceed the capacity limit.

Default controls

3D mode

By default, our 3D mode cameras use the following controls. You can customize the camera controls in this mode within the Unreal Engine project.

  • Swipe to rotate: Orbit around the object by swiping left, right, up, or down.
  • Pinch to zoom: Zoom out by pinching towards the center of the screen or zoom in by pinching towards the borders of the screen.

AR mode

AR mode cameras are controlled by the client side and the functionality cannot be modified. Creators can use the teleport function to move around and set the starting position and angle in AR.

  • Placement: Point your phone down at an empty space and move it around slowly to place the object in space.
  • Twist to rotate: Rotate the object by twisting your fingers on top of the object.
  • Drag to move: Drag the object around to move it in space.
  • Pinch to resize: Reduce the scale of the object by pinching towards the center of the screen or enlarge it by pinching outwards toward the borders of the screen.

Service turndown

Estimated time: one hour

  1. To turn down the service and release reserved compute resources:

    gcloud alpha immersive-stream xr instances delete my-instance --async
    
    

    Describe the instance with gcloud alpha immersive-stream xr instances describe my-instance command and check if the deletion completes. Before the instance is deleted, describing it shows that the DELETING lifecycle state, and after the deletion completes, a NOT_FOUND error will be returned.

  2. If necessary, to further remove the Content resource:

    gcloud alpha immersive-stream xr contents delete my-content --async
    

    Similarly, describing the Content shows the DELETING lifecycle state before the above asynchronous operation completes and a NOT_FOUND error is returned after the Content is successfully deleted:

    gcloud alpha immersive-stream xr contents describe my-content
    

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

  • Make sure you complete the service turndown procedure when you're finished with your evaluation.

What's next