BundleVersionChecker is a set of Unity editor classes to get access to Unity’s PlayerSettings.bundleVersion and their history at runtime. This first article series in 3 parts describes the problem how it started (part 1). (Part 2) shows the concept of the more sophisticated version with tracking the history of bundle versions. The usage in (Part 3) is likely what most people are looking for.
Unity’s PlayerSettings.bundleVersion is an editor class and thus not available at runtime. When you prepare a new version for your iOS or Android users that contains critical changes in player preferences or other migration tasks, you want to know if and when the users has updated.
Assume you decide to use encryption for your local highscores (like in this forum posting) starting with version 1.1. Then you need to know the installed version and thus if the migration is done. Especially when users update their apps after months from 1.0 to 2.1 this can be quite challenging. A flag will help but having access to the whole history of versions at runtime would give you more sophisticated options to perform all necessary migration steps in a safe way.
How It Started: The Runtime Class CurrentBundleVersion
The trick is to use an editor class that generates the code of a runtime class containing the bundle version string. This can be read from any other runtime class at app start to check if migration tasks have to be performed.
I placed this class in directory Assets/Scripts/Config/BundleVersionCheck but the location can be configured to be somewhere under Assets/Scripts (s. next paragraph). The code contains just one static member in the first revision:
public static class CurrentBundleVersion
public static readonly string version = "0.8.5";
This is generated code, so don’t modify it your changes will be lost. If you want to add or change something, do it in
The Editor Class BundleVersionChecker
BundleVersionChecker.cs has to be placed somewhere under Assets/Editor/BundleVersionCheck directory. Whenever Unity refreshes its state i.e. an asset file has changed, you start your project in editor player, build a new version, … this class is executed.This is achieved by the [InitializeOnLoad] attribute combined with a static constructor.
Within the class constructor the version string from CurrentBundleVersion is compared to PlayerSettings.bundleVersion. If they don’t match, file CurrentBundleVersion.cs is regenerated with updated bundle version string read from player settings. This is done in method
If you are fine with this simple and dirty approach, check out the branch plain_version at github (master contains the more sophisticated solution described in Part (2) and Part (3) Copy the files into your Unity project at the specified locations. Note that you will get an error if CurrentBundleVersion is not found at the prefefined directory Assets/Scripts/Config/BundleVersionCheck.
If you want to have it at a different location go to the editor class and edit the line
const string TargetCodeFile = "Assets/Scripts/Config/" + ClassName + ".cs";
You can change the class name string as well, but take care to change the runtime class name and the static constructor line as well
string lastVersion = CurrentBundleVersion.version; // -> MyClassName.version
Improvements And Outlook on Part 2
The plain static solution works so far when set up once but there are a some annoying drawbacks. Most of them are related to the fact, that there must be an initial dummy version of CurrentBundleVersion.cs:
- Integrating the github project as submodule is not possible as long as BundleVersionChecker is located under Assets/Editor and CurrentBundleVersion resides in Assets/Scripts
- Configuring class name needs code changes at 3 places and file renaming of CurrentBundleVersion.cs
- There is no version history available at runtime i.e. you can check if the versions are equal. If you want to do something like if (currentVersion < Version_0_8_4) you have to do this manually in a separate VersionManager class
- Starting with a useless initial dummy version has a smell of bad design
In part (2) I am going to enhance BundleVersionChecker to solve these problems.
Part (3) will describe the usage of the final version.