Azure Storage Bird

  • Article

Note

This is a Sandbox project. The content in this article is unsupported, and therefore may be out of date or not in a working state. That said, we still think it was awesome enough to include here. Enjoy!

Azure Storage Bird heading image

Get the source

Introduction

This sample game project demonstrates downloading files at runtime from Azure Storage using the Azure Storage SDK for Unity. This is useful for reducing the initial download size of your app. This approach could be adapted for a variety of purposes, such as updating game content without rebuilding and resubmitting the game, or adding new content to a live game.

Because music files typically are among the largest data files in games, the sample game has been designed to leverage several music assets. As the player progresses in the game, the background music changes, providing a good use case for downloading assets at runtime with the Azure Storage SDK.

Requirements

Note

The Azure Storage SDK for Unity is considered experimental. As such, this may not build and run on every single Unity platform. Please see the Azure Storage SDK compatibility list for a list of known working platforms and issues.

Azure setup

  1. Create an Azure Storage account.

  2. Create a container called music.

  3. Download the sample music files, unzip them, and upload them to Azure Storage as block blobs. These music files are from the free Metal Mayhem Music Pack made available by Unity.

browse blobs

Note

The sample project is hard coded to look in a block blob container called music and use the specific file names included in the sample music zip file (Track1.ogg through Track10.ogg). If you use differently named files, or only upload some of the files, you will need to modify the sample project's code accordingly.

Download the sample Unity project

Clone or download the project from the AzureSamples-Unity repository on GitHub.

  • On the GitHub site, click the Clone or download button to get a copy of the project to work with.
  • This project is located within the AzureStorageBird directory.

Note

The project comes with the Azure Storage for Unity SDK included. To learn more, including how to import the SDK into new projects, you can visit the SDK documentation.

Set scripting runtime version to .NET 4.x equivalent

The Azure Storage for Unity SDK requires the .NET 4.x equivalent scripting runtime. This is only available in Unity 2017.1 and above.

  1. From the Unity menu select Edit > Project Settings > Player to open the PlayerSettings panel.

  2. Select .NET 4.x from the Scripting Runtime Version dropdown in the Configuration section. Unity will prompt you to restart the editor.

    Scripting Configuration dialog

Note

In Unity 2017, this option is labeled Experimental (.NET 4.6 Equivalent).

Enter your connection string

  1. Log in to the Azure portal.

  2. Navigate to the Azure Storage account that you created for use with this sample.

  3. In the Settings section of the left-side menu, select Access keys.

  4. Copy the entire Connection string.

copy the connection string

  1. In the Unity sample project, open the file AzureStorageClient.cs.

  2. Replace the string YOUR_CONNECTION_STRING_HERE with your connection string copied from the Azure portal.

Important

Using HTTPS requires Unity 2018.2 or above. Unity 2017 and 2018.1 users must modify the DefaultEndpointsProtocol entry in the connection string to use http instead of https. This means your data will not be encrypted to and from the server.

Try the sample game

  1. Build and run on a supported platform or open the Title Scene in the editor and click the play button.

  2. When the game starts, if any required assets are missing, a "Downloading assets..." dialog should appear. Wait for the game to finish downloading the required assets from your Azure Storage account.

  3. Once the download completes, the dialog should clear. Press the Play button.

  4. In the main game scene, click the left mouse button or tap the screen to "flap." Navigating through the columns earns points. Each time you earn five points, the background music should change to a new song downloaded from Azure storage.

Sample game explanation

Gameplay

The sample game gameplay is based on the Make a Flappy Bird Style Game Unity tutorial series. It has been modified to download music assets from Azure Storage and play new music each time the player reaches a new level by accumulating a specified amount of points.

AzureStorageClient.cs

The static class AzureStorageClient holds the Azure Storage account connection string and contains a static reference to a CloudBlobClient, which is necessary for most Azure Storage functions.

TitleSceneBehavior.cs

The MonoBehaviour TitleSceneBehavior is placed on an empty GameObject in the Title Scene. Its Start function asynchronously initiates the process of checking for the required music files and downloading them from Azure Storage if necessary. The play button is disabled until the required files are first downloaded and then loaded as audio clips.

BlobStorageUtilities.cs

The static class BlobStorageUtilities contains functions for downloading files from Azure Blob Storage.

LevelMusicPlayer.cs

The MonoBehaviour LevelMusicPlayer is placed on an empty GameObject in the Title Scene and persists via DontDestroyOnLoad. During the Title Scene, it waits for the TitleSceneBehavior.DownloadingMusicFilesFinished event and then begins loading all of the downloaded files as Unity audio clips. This happens before entering the Game Scene in order to avoid stuttering when each new audio clip is played. Once loading is complete, the LoadingAudioClipsFinished event is raised, allowing TitleSceneBehavior to know when it's safe to display the play button.

During the Game Scene, LevelMusicPlayer handles the GameControl.StartedNewLevel event with a function that plays an audio clip corresponding to the new level.