Dependencies

• Working familiarity with Runtime Options - The supported Logic Versions are configured using the runtime options system. If you're not familiar with them or need a refresher, you can check out Working with Runtime Options.

Key Concepts

• A game's Logic Version is a versioning number that keeps track of major changes in the codebase. It should be updated whenever new features that alter the deterministic calculations are added to the game. It's possible to support older Logic Versions to roll out changes gradually or allow players to keep playing the game without having to update the client.
• The Supported Logic Version Range is the range of Logic Versions that the server supports. It is set in the global options during the building process and cannot be changed at runtime.
• The Active Logic Version Range is the range of Logic Versions the server accepts. It is set in the LiveOps Dashboard, and you can change it at runtime. The server will then only accept connections from clients with a Logic Version within this range.

Overview

Using Logic Versions, you can implement backward-compatible support so multiple client versions can connect to the server. Although only one server version can be deployed at a time, it can support multiple client versions.

The Logic Versions are used to track the range of implementations the client and the server support. The Version, therefore, should be bumped whenever changes are made to the deterministic simulation run on the client and the server to avoid two players having the same Version but different results on a given operation.

You can define which client versions work with the current server by modifying the range of Logic Versions in MetaplayCoreOptions.supportedLogicVersions. The client's Logic Version is defined in MetaplayCoreOptions.clientLogicVersion. By default, the server will support only a single client version, but it's possible to support multiple versions simultaneously with a little extra work.

Supporting Multiple Logic Versions in Code

Suppose you want to roll out a new feature and bump up the current LogicVersion. Here are the steps necessary to support both the old and new clients:

1. Deploy a version of the server that supports all desired Logic Versions.
2. Update the server's Active Logic Version Range.
3. Roll out the updated client with the new feature and increment the clientLogicVersion.
4. When desired, you can drop support for the old client in the LiveOps Dashboard, forcing players to update to the new one.

You can specify the clientLogicVersion on the client and supportedLogicVersions on the server separately in your options:

GlobalOptions.cs

public MetaplayCoreOptions Options => new MetaplayCoreOptions(
    ...
    // Specify client version (only support version 6)
    clientLogicVersion: 6,
    // Server accepts multiple client versions (5 and 6)
    supportedLogicVersions: new MetaVersionRange(5, 6),
    ...);

You can find the definition of MetaplayCoreOptions in Assets/SharedCode/GlobalOptions.cs.

To trigger behavior changes based on the Logic Version, you can use regular if statements in PlayerActions or in the PlayerModel tick:

PlayerActions.cs

// On the server, this will check what the client version is.
if (playerModel.LogicVersion >= 6) {
    // Implementation of feature X
} else {
    // Old implementation before feature X, in case some old behavior was removed
}

Be Careful!

It's important that the server is still able to reproduce the old game logic identically for all client versions connecting to the server.

Lastly, PlayerModel members can be added and removed but must be marked with the [AddedInVersion(...)] and [RemovedInVersion(...)] attributes to ensure the model checksums still get computed correctly across all versions:

PlayerModel.cs

class PlayerModel ... {
    // Example of adding a new member. The member is not checksummed when dealing
    // with clients with LogicVersion<=5.
    [MetaMember(123)]
    [AddedInVersion(6)]
    string NewMemberRequiredByFeatureX;

    // Example of soft-removing a member that is no longer used by LogicVersion>=6
    // but is kept around for compatibility with LogicVersion<=5.
    [MetaMember(124)]
    [RemovedInVersion(6)]
    string SomeDeprecatedMember;
}

Changing the Active Logic Version Range from the Dashboard

The active Logic Version Range can be changed in the LiveOps Dashboard. This range determines which client Versions can connect to the server. Even if a client is within the Supported Logic Version Range, it won't be able to connect to the server if the Active Logic Version Range does not include that client's Logic Version.

To change the Active Logic Version Range, go to the LiveOps Dashboard and click on the "Settings" button. Navigate to the Client Compatibility Settings section and click on the "Edit Settings" button. You can then change the Active Logic Version Range to include the desired Logic Versions.

Tread Carefully!

If you roll back the Active Logic Version Range to a lower value than before, you may experience data loss or unexpected behaviour.

You can also enable auto-upgrading of the Active Logic Version Range by setting the System.AutoUpgradeLogicVersion runtime option to true. This will automatically update the Active Logic Version Range to the highest Supported Logic Version when the server starts.

Additional Considerations

There are a few things to keep in mind to keep the experience of working with multiple client versions flowing smoothly:

First, note that the server can only have one game config active at a time, so it must work with both the old and new clients. In practice, the feature is mainly intended to give players some time (perhaps a few days or weeks) before they must upgrade clients.

Also note that for any features that involve player interactions, the old client should still be able to handle any messages it may receive from the newer clients. In practice, rolling out any multiplayer features with forced synchronized client/server updates may be best.

It's best to keep the number of supported versions to a minimum. The more versions you support, the more chances of things going wrong. We also recommend keeping the Active Version Range maximum value the same as the latest released client's Logic Version. It's possible to pre-emptively roll out a server that supports a future client version, but the Active Version Range should be updated to include the new client version only after the client has been released.

Players are not allowed to downgrade their Logic Version. Once a player has connected to the server with a specific Logic Version, they will not be able to connect with a lower Logic Version even when using a different device. This exists to prevent any possible data loss from reverting to an older version. This prevention is turned off in development environments and for developer players. Trying to downgrade a player's Logic Version will result in TerminalError.LogicVersionDowngrade being thrown, which should be handled by the client by showing an error message telling the player to update their client.

When a player is imported, the player's Logic Version will be set to the highest Active Logic Version of the server. When a player is reset, the Logic Version is set to the lowest Active Logic Version.

This feature is somewhat cumbersome to use as it requires supporting multiple versions of the game logic on the server simultaneously. It might be replaced eventually, so keep an eye out for new SDK releases. If you have any issues, please don't hesitate to send us a message.