Dependencies

• Working familiarity with Runtime Options - The Commit ID Check is configured using the runtime options system. See Working with Runtime Options for details.
• Understanding Logic Versions - The Commit ID Check is an alternative lightweight versioning system limitation, making it suitable its use only during development. Logic Versions describes the fully featured versioning system.
• Populated Build Information in Client - The Commit ID Check is based on the version control revision data detected at build time. Client Build Version describes how to integrate it into your CI.

Key Concepts

• A Commit ID is an identifier of a specific revision in the version control system used to manage your game project's source code.
• A Commit ID Check compares Commit IDs of the client and the server to verify they are built from the same source code version.

Overview

Commit ID Checks ensure the client and the server have been built from the same source code version, and reject the connection otherwise. This can be thought as an automatic, simple versioning that ensures the client and server are always compatible.

The Commit ID Check is specifially useful in development environments when actions, models, or messages are iterated on quickly. If these shared data structure are changed only on client or the server, it's easy to run into checksum mismatches or deserialization failures, for which the proper solution is to use Logic Versions. However, updating Logic Versions for every change requires manual work which can be tedious.

Enabling Commit ID Checks eliminates the need for manual versioning, as every change to the project source code changes the Commit ID in the version control. Therefore, any change breaks the compatibility with the server, preventing out-of-date clients causing compatibility issues.

⚠️ Not for Production Environments

Commit ID Check is not suitable for production environments! Requiring exact Commit IDs is too coarse as you may need to perform client-only or server-only updates.

Enabling Commit ID Check

The checking is controlled with the ClientConnection.CommitIdCheckRule runtime environment value. To configure the check for each environment, you can use the environment-specific yaml files: Options.<env>.yaml.

To disable it, set the CommitIdCheckRule to Disabled. This is the default mode and never needs to be done manually:

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

ClientConnection:
    CommitIdCheckRule: Disabled

To enable the check such that both the server and the client must have their Commit ID set and match, set the CommitIdCheckRule to Strict:

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

ClientConnection:
    CommitIdCheckRule: Strict

Strict mode prevents connections if the client has no Commit ID. Since Commit IDs are set during the client build, Strict mode also prevents connecting from clients that haven't been build, such as when running the client from a local copy on the Unity Editor.

Since connecting to the server from the local Unity Editor can be useful for debugging, the server also supports OnlyIfDefined Commit ID Check mode. In this mode, the client and server Commit IDs are checked only if they are available. This ensures built clients and servers are compatible with each other, while allowing for debugging with local clients:

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

ClientConnection:
    CommitIdCheckRule: OnlyIfDefined