Dependencies

• Working familiarity with Runtime Options - The supported Logic Versions are configured using the runtime options system. If you're unfamiliar with them or need a refresher, 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. You should update it whenever you add new features to the game that alter the deterministic calculations. 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. You can set it in the LiveOps Dashboard and 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 you can only deploy one server version at a time, it can support multiple client versions.

The Logic Versions track the range of implementations the client and the server support. The Version, therefore, should be bumped up whenever changes are made to the deterministic simulation being 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. You can, in turn, define the client's Logic Version 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 bit of extra work.

Changing the Active Logic Version Range from the Dashboard

You can change the Active Logic Version Range in the LiveOps Dashboard. This range determines which client Logic 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 unless the Active Logic Version Range includes that client's Logic Version.

To change the Active Logic Version Range, go to the LiveOps Dashboard and click the "Settings" button. Navigate to the "Client Compatibility Settings" section and click 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 behavior.

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.

Supporting Multiple Logic Versions

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 its 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.

Although sending new actions from the client is safe, you need to be careful when adding new actions to the server. Executing a server action on a player with an incompatible logic version will cause the player to be kicked and their data to be updated to the minimum required logic version. Therefore, it's important to consider that your users might be on different Logic Versions when executing actions.

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.

Removing Or Adding New Members And Types

You can add or remove all MetaSerializable members (like PlayerModel members, for example) in new Logic Versions, but they 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;
}

You can also do the same for classes. However, serializing or deserializing a class that isn't available in the player's Logic Version will throw an exception.

BaseClass.cs

[MetaSerializable]
abstract class BaseClass {
 ...
}

[AddedInVersion(6)] 
[MetaSerializableDerived(1)]
class NewlyAddedClass : BaseClass {
 ...
}

We also provide some utilities to check whether a given instance is compatible with the Logic Version. This is especially useful in cases where the data is coming from a different system or you're targeting a group of users that can be on different Versions of the client.

PlayerActor.cs

class PlayerActor : ... {
    void DoSomething()
 {
        if (MetaSerializationUtil.IsInstanceCompatibleWithLogicVersion<NewlyAddedClass>(newlyAddedClass, ClientLogicVersion))
 {
 // Implementation of the feature
 }
        else
 {
 // Fallback for players that do not support this feature
 }
 }
}

Dashboard Support

The dashboard can communicate that certain features are not available to a given player or a group of players. For built-in features, we've already taken care of this when you're using the AddedInVersion or RemovedInVersion attributes.

Manually disabling components when you know the feature is not available to a player is the easiest option. However, that is not always feasible. For example, when using GeneratedForms, you often don't know whether a type is available. We provide two built-in solutions for this:

First, when you know which player you're targeting and what logic version they're on at the moment, passing the player's logic version to the generated form will disable components known to be unavailable.

PlayerActionSendMail.vue

meta-generated-form(
    v-model="mail"
    :typeName="'Metaplay.Core.InGameMail.MetaInGameMail'"
    :forcedLocalization="playerData.model.language"
    :page="'PlayerActionSendMail'"
    class="!tw-overflow-x-hidden"
    :logic-version="playerData.model.logicVersion"
    @status="isValid = $event"
)

The other option helps when you target a group of players, like with Broadcasts or LiveOps Events. We will show a warning if a member or type is only available to a subset of players. Remember that we won't stop you from executing these actions, and as such, you should handle this gracefully. For example, through segmentation or your server implementation, you can verify that a player is compatible with the action you're executing.

To enable this, you can just set is-targeting-multiple-players on a GeneratedForm:

BroadcastFormButton.vue

meta-generated-form(
    typeName="Metaplay.Server.NotificationCampaign.NotificationContent"
    :value="campaignFormInfo.content"
    :page="'NotificationFormButton'"
    class="tw-mt-3"
    @input="campaignFormInfo.content = $event"
    @status="isContentValid = $event"
    is-targeting-multiple-players
)

Additional Considerations

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

• The server can only have one game config active - 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.
• Data integrity and safety - The server will detect if a PlayerModel is incompatible with the current Logic Version, as this can happen because an incompatible type was accidentally added to the PlayerModel or an incompatible ServerAction was executed against the PlayerModel. In these cases, we'll forcefully update the player to the minimum required Logic Version that supports the types.
• Old client handling messages - 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.
• Keep the number of supported versions to a minimum - 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 recommend keeping the Active Version Range maximum value the same as the latest released client's Logic Version. It's possible to preemptively 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 - 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 in the client by showing an error message telling the player to update their client.
• Player Logic Versions on import and reset - 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.

If you have any issues, please don't hesitate to send us a message.

Further Reading

• The Metaplay SDK additionally supports identifying Client Patch Versions within a given Logic Version, see Client Patches for details.