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.

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

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

Although sending new actions from the client is safe, you have 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 they will 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

All MetaSerializable members (e.g. 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;
}

Similarly, you can do the same for classes. However, serializing or deserializing a class that is not available for the player's LogicVersion 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 at the same time.

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 you're using GeneratedForms, you often don't know whether the type is available. We provide 2 built-in solutions for this, the first helps 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 that are known to not be available.

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 in cases where you are targeting a group of players, think Broadcasts or LiveOps Events. We will show a warning if a member or type is only available to a subset of players. Keep in mind 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 can verify that a player is indeed compatible.

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:

• 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 that if a PlayerModel is incompatible with the current Logic Version, 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 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 - 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.
• Player Logic Version 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.