Design Document for Versioning Unity AssetBundles

Purpose

As a player, one would like to get the latest Unity asset bundles without having to manually uninstall the app or clear the data. The purpose of this implementation is to detect if a newer version of AssetBundle is available. In which chase, the Game will first clear the existing bundle from the cache and then download the latest version of AssteBundle from S3 Bucket.

This implementation requires close communication between Android, LAMP stack and Unity3D Games to provide a seamless experience with the latest assets available to a game player.

Architectural Design (Swim Lane Diagram)

Technology Platforms

Unity3D – Platform in which the Games are developed and AssetBundles are generated. In this platform we would be handling the following:

  1. Managing the device cache where AssetBundles are stored once they are downloaded. Perform cache cleaning and loading unloading of the AssetBundles.
  2. Update Android App when the Curren Device AssetBundle version is up to date with the latest version.
  3. Decide whether to load the AssetBundles from the Device cache or get the latest version from the S3 Bucket.

Android – It acts as a bridge between Unity and LAMP stack.

  1. Fetches the records of CurentDeviceAssetBundle and LatestAssetBundle from the server and sends it in Extra Parameters to Unity.
  2. Receives communication from unity when there is a change in CurrentDeviceAssetBundle version and call backend API to update the DB with the new CurrentDeviceAssetBundle version.

LAMP Stack – This acts as the persistent layer.

  1. Manages the records of AssetBundles by versions, that are currently available in all client devices and the latest Asset Bundle in the S3 Bucket.
  2. Performs Fetching and Update operations to get latest records of Asset Bundle versions.
  3. Pass the latest records of CurrentDeviceAssetBundle and LatestAssetBundle to every Android client while booting.
  4. Get updates from Android Client through API when there is an update needed to the CurrentDeviceAssetBundle of a user.
  5. Provides a GUI using which Unity team is able to update the LatestAssetBundle versions for the available AssetBundles to the DB.

Sequence of events

  1. Generation of AssetBundles in Unity – New asset bundles are generated for individual games.
  2. Naming Convention – Name of each of the AssetBundle is exactly same as the name of the Main Scene of the respective Unity Game. E.g. RunnerBoy appended with _practice appended with the version of AssetBundle e.g. V1.1 so that the final construct looks like the sample below:

RunnerBoy_practiceV1.1

  • Uploading to S3 Bucked – New AssetBundles are then uploaded to designated folders in S3 Bucket.
  • Unity developer responsible for uploading the Assetbundle must ensure that the following details are updated to a GUI which is a part of the backed stack, with the following details:
    • Select from a dropdown of available games.
    • Note the Latest Version of the Asset Bundle and increment the Sub-version by 1 if it is a minor update. Increase the Major version if it is a major update. E.g. V1.1, V(1)-Major and (.1)-Minor.
    • Once saved, the backend system should get updated with the LatestAssetBundle versions.
  • When the Android Client is launched, the payload that contains the UserID and GameID must also receive the LatestAssetBundle (common for all clients) and CurrentDeviceAssetBundle (specific to a client)
  • When a unity game is launched from Android App, Unity receives the above details in Extra Parameters from Android along with GameID and UserID (apart from all other params it is currently receiving).
  • Unity3D performs the check if (CurrentDeviceAssetBundle == LatestAssetBundle) and if the 2 parameters match, an additional check is performed to check if the LatestAssetBundle version is equal to the Cached AssetBundle version. Based on the checked results, Unity either downloads the latest version of AssetBundle from S3 Bucket or fetches the same from device cache.
  • If CurrentDeviceAssetBundle and LatestAssetBundle are different, then Unity directly fetches the latest AssetBundle from S3 Bucket and calls an android function to update the CurrentDeviceAssetBundle version which is not equal to the LatestAssetBundle for that specific GameID and UserID.
  • When a new asset bundle is loaded, Unity clears off the old AssetBundle from the Device Cache by calling Caching.ClearCache() (more API refs: How do I delete AssetBundles from the cache? – Unity)
  • Android after receiving the Update function call from Unity make a Backend API call to update the CurrentDeviceAssetBundle version for the GameID and UserID.
  • Backend updates the DB with new CurrentDeviceAssetBundle for GameID and UserID.

Android Communication with Backend

  1. At Login – On successful client authentication, backend adds the following parameters to the existing payload:
    1. CurrentDeviceAssetBundle Versions – The AssetBundle that are currently available with the client.

Key – GameName

Value – GameName wise AssetBundle version

Sample JSON snippet:

{ ” CurrentDeviceAssetBundles“ : [{“RunnerBoy” : “V1.1”}, {“CandyCrush” : “V1.5”}, …] }

  • LatestAssetBundle Versions – The latest AssetBundle versions that are now available in S3 Bucket.

Sample JSON snippet:

{ ” LatestAssetBundles” : [{“RunnerBoy” : “V1.2”}, {“CandyCrush” : “V1.6”}, …] }

  • On CallBack  function from Unity when it has updated the latest assetbundle from S3 Bucket. This is when Android calls Backend API again to update the current AssetBundle versions.

Sample JSON snippet sent to Backend from Android:

{ ” UpdatedCurrentDeviceAssetBundles” : [{“RunnerBoy” : “V1.2”}, {“CandyCrush” : “V1.6”}, …] }

Unity Communication with Android

  1. On every Unity Game Launch – This is when Android sends CurrentDeviceAssetBundle Versions and LatestAssetBundle Versions to Unity and Unity does the comparison to decide whether to get the latest AssetBundles from S3 or from Device cache.

Sample Extra Parameters from Android, received in unity:

extras.Call<string>(“getString”, “LatestRunnerBoyAssetBundle_Version”);

extras.Call<string>(“getString”, “CurrentDeviceRunnerBoyAssetBundle_Version”);

extras.Call<string>(“getString”, “LatestCandyCrushAssetBundle_Version”);

extras.Call<string>(“getString”, “CurrentDevice CandyCrushAssetBundle_Version”);

…

  • Every time Unity updates the CurrentDeviceAssetBundle Versions with LatestAssetBundle Versions.

currentActivity.Call(“UpdateAsstBundleVersions”, new string[] { ” UpdatedCurrentDeviceAssetBundles” : [{“RunnerBoy” : “V1.2”}, {“CandyCrush” : “V1.6”}, …] }

Backend Communication with Android and DB updates

  1. DB updates from GUI when a new Asset Bundle is updated.
  2. Added array of AssetBundle versions for all games to the Login Response payload to Android.

On successful client authentication, backend adds the following parameters to the existing payload:

  1. CurrentDeviceAssetBundle Versions – The AssetBundle that are currently available with the client.

Key – GameName

Value – GameName wise AssetBundle version

Sample JSON snippet:

{ ” CurrentDeviceAssetBundles” : [{“RunnerBoy” : “V1.1”}, {“CandyCrush” : “V1.5”}, …] }

  • LatestAssetBundle Versions – The latest AssetBundle versions that are now available in S3 Bucket.

Sample JSON snippet:

{ ” LatestAssetBundles” : [{“RunnerBoy” : “V1.2”}, {“CandyCrush” : “V1.6”}, …] }

  • Backend API Call for Android to Update the CurrentDeviceAssetBundle Versions – When the CurrentDeviceAssetBundle Versions is updated at Unity Games, Android App must be able to call a Backend API to update the same to DB.

Sample JSON snippet:

{ ” UpdatedCurrentDeviceAssetBundles” : [{“RunnerBoy” : “V1.2”}, {“CandyCrush” : “V1.6”}, …] }