Tips and trips for setting up Continuous Integration (CI) for your projects
Continuous Integration means that any changes to the project are merged frequently into the main branch, and automation (especially of testing) is used to ensure quality. The main benefits of Continuous Integration (henceforth CI) are that it makes software development easier, faster, and less risky for developers. Building your Game Client with CI and automated testing might require coherence setup.
For automated delivery of your project changes and testing it in CI, you can take the following steps to make sure coherence is set up appropriately in your project before building a standalone Client.
Make sure you generate your schema or schemas before building. For example, you can create a build method and call it from Unity via command line as a custom method.
After that, you will need to bake your code according to the schema. Baking is also accessible via the Unity command line in a custom method.
To start the Replication Server in CI you can also use scripts generated in ./Library/coherence folder /project_path/Library/coherence/run-replication-server-rooms.sh and /project_path/Library/coherence/run-replication-server-worlds.sh.
If you want to automate the uploading of schemas, keep in mind that you need to set the COHERENCE_PORTAL_TOKEN environment variable in your continuous integration setup so the upload is accepted by the coherence Cloud. You can get the token from coherence Dashboard > Project > Settings > Project Settings > Project Token.
You can use the Simulator Build Pipeline public API to build and upload your Simulator builds to the coherence Cloud from the command line. If you wish to learn more about Simulators, check out the dedicated section.
There are two methods you will need to call, in order, to build and upload a Simulator build successfully:
Coherence.Build.SimulatorBuildPipeline.PrepareHeadlessBuild This method will add the COHERENCE_SIMULATOR scripting symbol, will set the build sub target to Server (for Unity 2021) and it will change the platform to Linux. It is necessary to perform these steps in an isolated Unity execution, because in batch mode, there is no editor loop that will make sure your assemblies are reloaded with the changes.
Coherence.Build.SimulatorBuildPipeline.BuildHeadlessLinuxClientAsync ****This method will build the Unity Client and upload it to your selected organization and project.
In order to be able to interact with your coherence Dashboard from the command line, you will need to export your project token as an environment variable.
You can create your custom build steps by implementing Unity interfaces IPreprocessBuildWithReport and IPostprocessBuildWithReport. In order to verify that the build being created is a Simulator, you can check for the SimulatorBuildPipeline.IsBuildingSimulator boolean.
The Unreal SDK is under development. We're looking for partners or studios that want to take a sneak peek.
Contact devrel@coherence.io for more information or collaboration options.
You can also join our Discord to get in touch with the team directly.
A list of common terms and concepts used in coherence.
Authority defines which Client or Simulator is allowed to make changes to the synced properties of an any networked GameObject, and in general defines who "runs the gameplay code" for that networked GameObject.
See CoherenceInput.
The process of generating network code for your GameObjects. It does two things: schema generation and code generation.
The data that Game Clients exchange with the cloud-hosted Replication Server to sync your Rooms or Worlds and all the players and other game objects within it.
Also known as CoherenceBridge. It represents a connection to the Replication Server. It makes sure CoherenceSyncs are linked to their networked representations, serving as an interface between Unity's GameObjects and coherence's network. When you place a CoherenceSync in your Unity scene, the Bridge detects it and makes sure state is synchronized.
In plain terms, CCU hour is the number of connection slots for a World/Room, times the number of hours the World/Room was online.. The calculation is based on the maximum player capacity these are reserved for, regardless of how many players are active within them.
A Client connection represents a participant or Simulator in a game you're playing online.
A CoherenceSync representing a Client connected to the Replication Server. Required to send Client Messages.
The ability for Clients to host their own game sessions, without the need of using the Replication Server. The SDK for Unity achieves this by bundling the Replication Server binary and the schemas needed for the project within the built game. Read more about it in the Client-hosting article.d
The process of generating network code for CoherenceSync Prefabs. Part of the baking process.
The backend of the coherence Developer Portal.
CoherenceInput is a Unity component that enables a Simulator to assume authority over the simulation of another Client's objects. Each object can only accept inputs from one specific Client, called the object’s Input Authority. You should use CoherenceInput when a) you want a centralized simulation of all inputs b) Clients have low processing power c) determinism is important for your project.
CoherenceSync is a Unity component that should be attached to every Prefab you want to network. It may be your player, an NPC or an inanimate object such as a ball, a projectile or a banana - anything that needs to be synchronized over the network.
A request to invoke a method on a Client (other solutions may refer to this mechanism as RPC).
Dashboard is the front-end of the coherence Developer Portal that is used for managing your coherence projects.
These are useful features for multiplayer games that coherence offers like the Key-value store and Authentication Service (Player Accounts). More info is available in the Game Services and Lobbies articles.
See CoherenceInput. Replaced InputOwner.
The KV Database, also know as a key-value store, provides a simple persistence layer for the players. The KV Database matches a short key (identifier) to a specific value (data payload) held in a simple, unstructured database. For example, KV store can be used to store the player's score, email address, or any other data. There are no limits to the total number of key/value pairs as long as the total size stays under 256KB.
An optimization technique to adjust the resources spent on networking entities, based on distance. CoherenceSync Prefabs can define LODs, which are applied substractively: each level can compress the information sent (less data, but also less quality) and also stop sending data altogether, on a Unity component basis.
Used for filtering Entities that receive updates via CoherenceSync by distance and relevance, as an optimization measure (latency, compute). LiveQuery area is shaped like a box, and the distance is measured from middle to edges. Also, see TagQuery.
Multi-Room Simulators are Room Simulators which are able to simulate multiple Game Rooms at the same time.
In the context of the Dashboard, the entity that uses coherence for its project(s).
In the context of the Dashboard, a project identifies a specific game or application within the coherence Cloud. Projects are owned by an Organization.
A server that replicates entities across the network between Clients and Simulators. It's a binary (per desktop platform) that the SDK provides, and can be used for development or distribution (see client-hosting or coherence Cloud).
Short-lived multiplayer environments for dozens of players. Perfect for quick session-based matches. For accommodating more players, see Worlds.
Schemas are files that define which data is networked. They define network components, commands, inputs and archetypes. There's two primary uses:
As a description for the Replication Server, telling it how the data in your project looks like – to receive, store, and send this data to Clients.
As a basis for code generation, creating various structs and methods that can be used in your project to communicate with the Replication Server.
The Unity package distributed through UPM, that allows developers to use coherence to develop multiplayer games.
A Simulator is a headless client running game logic in the server that is syncing all the changes in the Room or World to all the players. It ensures a stable connection and is a way to make your multiplayer game logic tamper-proof. Find out more about Simulators in our developer documentation.
A string of text that uniquely identifies an uploaded Simulator, making it easy to differentiate between various World or Room Simulators during deployment. The Simulator slug should be descriptive for ease of use purposes, although coherence supports any string value.
State authority, when given to a Simulator or a Client, means they can change the state of Entities in the game. In server-authoritative games state authority is given to a Simulator for anti-tampering reasons, but for casual projects it can lie with Clients that create the Entities. However, coherence allows for flexibility as well - for example, state authority can be configured so it can be transferred to other Clients or Simulators, and reassigned continuously in the course of the game. Additionally, see Input Authority.
What the Replication Server is doing by determining the state of the game and then syncing it to all the connected Clients.
Storage here relates to the cost of keeping data on coherence Cloud. It is measured in terabytes (TB) per hour.
In addition to the LiveQuery, coherence also supports filtering objects by tag. This is useful when you have some special objects that should always be visible regardless of World position. Also, see LiveQuery.
Long-lived and permanent multiplayer environments for thousands of players. Best suited for MMO-type games. For more smaller player counts, see Rooms.
coherence SDK supports networking in WebGL without any additional setup. Both Rooms and Worlds are supported.
WebGL builds use WebRTC to connect to the Replication Server and so the ports used to connect are different from the usual UDP ports. This is managed automatically in the sample connect dialogs, but if you are building your own, you need to make sure you're connecting to the the correct port which is specified by the --signalling-port when starting the Replication Server locally (defaults to 42002 for Rooms and 32002 for Worlds).
This is resolved automatically when using the Unity Cloud Service API to create and join Rooms and Worlds.
For anyone building WebGL in Linux, some additional packages are required.
For Ubuntu:
sudo apt install clang libtinfo5 python python-setuptools
Others: check with your package repository to install the correct packages for your distribution.
For running a WebGL build locally, please refer to the official Unity documentation.
A word of caution - currently, WebGL doesn't handle async/await well.
Other build options work nicely!
Game Clients normally connect to one another via the coherence Cloud services, but it is also possible to connect Clients via 3rd party relays, such as Steam Networking, Epic Online Services and Azure PlayFab. These relays are essential for the Game Clients to find one-another and maintain connectivity. As an additional bonus, you may get a significant reduction in lag.
This makes it easy for the players of your coherence-enabled game to host Replication Servers themselves, without using our cloud services.
For the particulars, see our client-hosting article.