Managing a videogames version information can be a MASSIVE pain in the butt - especially in the final days close to release when you are juggling release candidates and bug fixes. Sometimes the most helpful thing in the world is just knowing exactly which version of a game you have running on a devkit. This package helps you solve a lot of these common versioning problems and is pretty much ripped right out of the codebase we used to ship Gunsport @ Necrosoft.
- Keep your games version information in one central, easy to edit asset
- Automatically increments the games build number each time you run a build
- Stores a timestamp for each build
- If your project uses Git for version control, it captures the most recent commit hash during a build too
- Prints all this info right at the top of a games log file making it much easier to match bug reports to game versions
- And provides easy ways to expose the game version in game - super handy for displaying the version in your UI or more feeding into multiplayer APIs for server filtering
Installation is hyper simple! Open up Unity's Package Manager view (Window → Package Manager) and then select the Add Package icon in the top left of the window to add a git package.
The current git install URL is https://github.com/LotteMakesStuff/LMS.Version.git#1.1.2
Version information is kept in a Version asset, which needs to be created in your project after installing the package. Theres two simple ways to make the asset
the easiest way is to just hit build in Unity. If no version asset is found in your project at build time a new one is created for you.
You can also manually trigger creating the asset in the Project Settings window (Edit → Project Settings → Version). If no Version asset is found in your project, youll see a button here for creating one. As soon as the asset is created you may edit version information from this screen.
Both methods of creating the asset will try and set the initial version number to whatever the value of the version field in Player Settings.
Ahhh heck. Its also avaible via OpenUPM.
At its core, this package implements a Unity build preprocessor, a script that is executed before Unity builds your game. Every time you build your game, this script opens the version asset and does the following modifications
- Increments the Build number. For example version 1.5.2 will become version 1.5.3
- Calls into Git to fetch the hash of the last commit
- Update the versions Timestamp field
The version asset is also added to the project Preloaded asset list. This ensures it is one of the first objects to be loaded by your game. This is important because it needs an opportunity to write into the player log as early as possible. When the version information is loaded in at runtime it is immediately written into your games log file, which is SUPER useful when taking bug reports with logs as you can tell what version of the game the log is from within the first few lines of the log.
Version information can be edited directly on the version asset itself or via the Version page in the Project Settings window (Edit → Project Settings → Version). As well as being able to directly set the games Major & Minor version number, you can specify Extra Versions. Sometimes it's useful to specify versions for subsystems within your game. Some more common use cases might save data format version or netcode version. We used this extensively in Gunsport on Google Stadia to filter multiplayer lobbies based on netcode version, rather than game version.
| API | Usage |
|---|---|
| Version.GetGameVersion() | Returns the version of the game as a string |
| Version.GetGameVersion(VersionDeliniator delineator) | Returns the version of the game as a string. Allows you to specify if you want the numbers separated with dots or underscores |
| Version.GetExtraVersion(string name) | Returns an extra version as a string. Name is case insensite. |
| Version.Instance | Singleton access to the Version Assets data |
LMS.Versions ships with two UI components, VersionDisplay and VersionDisplayTextMeshPro that help with displaying version information on a uGUI canvas. These components let you specify a format string that automatically binds data from the version asset and give you a lot of flexibility over how it's displayed. The version string in this example shows how Gunsports version was displayed on the games main menu.
Version.cs - this class implements the actual Version asset as a Unity ScriptableObject It provides a bunch of static accessors that make grabbing version information easy at runtime. Its OnEnable() and Initialize() methods are responsible for printing version information into a Player.log file
VersionDisplay.cs & VersionDisplayTextMeshPro.cs - these components can be used to display version information in a Unity GUI, using either the inbult text renderer or Textmesh Pro. The most interesting feature here is the version format string, which can be used to customize how the version text is rendered without changing the underlying code.
BuildNumberTool.cs - Manages all the pre-build magic, including creating a version asset if one does not exist, incrementing the version number and saving changes to the asset as well as calling into git to find the most recent commit hash.
I hope you find this as useful in your projects as i have in mine! If you find this at all useful, please consider sending me a coffee <3