By default, users who subscribe to a Steam Workshop item will download the latest version of that item. Any subsequent updates to the item will also be propagated to all current subscribers.

With the release of version 1.60 of the Steamworks SDK, content creators can now specify that a specific version of their item is valid for a Steam (beta) branch.

Version control for complex mods

Version control of game builds and mod versions can be really important for supporting complex mods and evolving games. An example is a game where some players have dozens or hundreds of hours of game progression in a certain version of the game that works with a certain set of mods. In this scenario, automatically updating the game may break some of that player's installed mods and corrupt their save game. You now have the option to call a Steam API telling Steam to switch the player to a specific branch of the game if you detect that a recent update has broken compatibility with their mods.

The following documentation describes how to set up your builds and your modding community to allow this to work.

Setting up a game for version history

In order to support mods that target specific versions of your game, you'll need to be deliberate about how you preserve old game versions. Here are the things you'll need to think about:

1. Organize past versions - The order of your build versions (a.k.a. beta branches) is key! Start by organizing past versions of your game, setting and keeping a deliberate order to your beta branches. To do this, you will need to order your Steam branches on the Steamworks site by visiting the SteamPipe > Builds page. From there you can re-order the branches you've created from oldest to newest. This is needed if you want users to be able to specify that a version of their item is valid for a range of branches (i.e. "minimum" and "maximum") instead of just one specific branch.
   
   
2. Enable the feature - On your game's Workshop configuration page, select Enable Game Branch Versions and then publish your changes when you're ready.
   
   
3. Check the user's current game version - Use The Steamworks API ISteamApps::GetBetaInfo from within your game to check which version of your game the current user is on.
   
   
4. Evaluate the subscribed mods - From within your game, create a query to retrieve the user's subscribed Workshop mods that the current user has subscribed, and check ISteamUGC::GetSupportedGameVersionData to see what version each is intended to work with.
   
   
5. Prompt the user if necessary - If you detect that the user is subscribed to mods that may not work with the version of the game that the user is currently running, you can present the user with some UI, asking if they wish to change to a different version. If so, you can call ISteamApps::SetActiveBeta to switch to a specific older version of the game that is known to support the mods.
   
   Calling this API will cause Steam to exit the running game, switch build branches (kicking off an install of that branches content), and restart the game in that new version.

Getting and setting the current version of the game can be done through these Steamworks API calls:
ISteamApps::GetCurrentBetaName
ISteamApps::GetNumBetas
ISteamApps::GetBetaInfo
ISteamApps::SetActiveBeta

Setting up your Steam Workshop for mod versions

By enabling mod versions, items in the Steam Workshop can include data about a range of one or more game builds that are known to be supported by each version of the mod. If no range is specified, Steam will assume the version works with any build of the game. If more than one version of the Workshop item are indicated as compatible with the player's current version of the game, then the latest uploaded version of the item will be the one that Steam downloads.

There are two ways that Workshop items can get version information set: Mod authors can set this information, or your uploader tool can set this information.

1. Mod authors can set supported versions - Mod authors in the Steam Workshop can set version support by visiting the item history page and using the UI to configure which versions of the game work for each version of their Workshop item.
   
   
2. Your Workshop uploader can set supported versions - If your Workshop item uploader tool can validate support for an item, you can automatically mark it as supporting the appropriate versions, or you can build UI to make it easy for the mod author to choose supported versions and ranges at time of upload.
   
   When uploading a version of an item, simply call ISteamUGC::SetRequiredGameVersions with a minimum and maximum Steam branch. These branches can be the same if the item is only valid for a specific Steam branch. If the minimum branch is not set, then the item is valid for all Steam branches older than the maximum branch, and vice-versa for when the maximum branch is not set. Content creators can also set the minimum and maximum branches for their items on the web page for their item under the "Change Notes" section.
   
   Users who have opted into Steam branch will download the version of the item that is valid for that branch. If the content creator updates a version of an item, all subscribers who have opted into the Steam branch associated with that item will download those changes.

To get and set version information for a Workshop item, use these Steamworks APIs:

• ISteamUGC::SetRequiredGameVersions – when submitting an update, the user can specify the min/max beta branches the item is valid for
  
• ISteamUGC::GetNumSupportedGameVersions – returns the number of versions the item has
  
• ISteamUGC::GetSupportedGameVersionData – returns the min/max branch for the specific item version

Best practices for game developers

With an ideal setup of game versions and mod versions, Steam will automatically download the right mod version for the version of the game being run.

Below are a few important things that game developers should keep in mind in order to use these features correctly, and to best support their mod authoring community.

• Deliberately manage your build branches - Visit the Steamworks build management page and craft your set of previous game versions carefully. You'll probably want to name your branches in such a way that makes sense for the version numbers you've been using for your game. You can version at whatever points make sense for your game. For example, naming a branch "version_1.4" and another one "version_1.5"
  
  
• Enable the Workshop setting "Enable Game Branch Versions" - This setting under your Steamworks Workshop configuration will allow mod authors to specify ranges of branches that their item works with
  
  
• Establish a consistent test-to-deployment process - It is important to give mod authors a chance to create and upload new versions of their mod, or update version support definition for existing mods if they work well with the latest version of the game. Creating a consistent test process of deploying new builds to a beta branch ahead of public release will give mod authors a chance to test out their mods and upload new versions if desired.
  
  
• Add in-game UI to manage game version - If updates to a game are likely to break mods that your players have installed, you can present some UI asking the player if they want to update their game or stay on the previous version. You can even get the list of subscribed Workshop items for the user and check the supported game versions for each so you can warn the user if the newest version of the game doesn't work with one or more of their mods.
  
  You can set up ahead of time for the best user experience when you know that upcoming changes to the game are likely to break a lot of compatibility with mods.
  
  1. Planning for the future: First, update your game version that is on the 'default' branch to tell Steam to keep the user on this particular branch of the game.
     
  2. Then, later when you are deploying a new version of the game, the game should recognize that the user previously specified as staying on a certain version and ask them whether they want to move to a new version or stay on their current version.