Dependencies

• Working familiarity with Runtime Options - The Protocol Hash Check is configured using the runtime options system. See Working with Runtime Options for details.
• Understanding Logic Versions - The Protocol Hash Check only applies when the client and server logic versions match. Logic Versions describes the versioning system.

Key Concepts

• A Protocol Hash is a hash computed over the serializable types that make up the wire protocol shared by the client and the server.
• A Protocol Hash Check compares the Protocol Hashes of the client and the server when their logic versions match, to detect a client built from a different source code version whose serialization protocol has drifted.

Overview

When a client connects with the same logic version as the server's latest supported logic version, the client and server are expected to share an identical serialization protocol. If their Protocol Hashes differ, the shared data structures (actions, models, or messages) were changed on only one side without bumping the logic version. Such a mismatch leads to checksum mismatches or deserialization failures that are hard to diagnose.

This most commonly happens in local development using Unity Editor. Changing the source code affecting the protocol causes the client to be automatically rebuilt, but the running local server is not.

Automatic Local Server Rebuild

To automatically rebuild and restart the server when shared code is changed, use the watch-flag when starting the server:

metaplay dev server --watch

The Protocol Hash Check prevents the possible incompatibility by rejecting connections if the hash of the client and the server differ. In this case, the client will report a MetaplayClientConnectionErrors.ProtocolHashMismatch error when attempting to connect.

In production, the intended solution for incompatible wire protocol is to use Logic Versions. The Protocol Hash Check is only intended to prevent issues stemming from incompatible protocol versions during local development.

Configuring Protocol Hash Check

The check is controlled with the ClientConnection.ProtocolHashMismatchIsError runtime option.

Backend/Server/Config/Options.<env>.yaml

ClientConnection:
    ProtocolHashMismatchIsError: true # Require protocol hash to match
    # ProtocolHashMismatchIsError: false # Tolerate protocol mismatch

The Protocol Hash Check defaults to enabled on local environments and disabled elsewhere. Local development is where rebuilding of only client or server is most common. In the production environments, consider using Logic Versions instead.