LogoLogo
⚠️ Outdated documentationGo to LatestHomeAPI
SDK 0.7.4
SDK 0.7.4
  • Welcome
  • Overview
    • What is coherence?
    • How does coherence work?
    • Features and Roadmap
    • Rooms and Worlds
    • Requirements
  • Get Started
    • Install coherence
    • Scene setup
    • Prefab setup
    • Build and run
    • Baking and code generation
    • Create a free account
    • Deploy replication server
    • Share builds
  • Authority and communication
    • How authority works
    • Authority transfer
    • Commands / Messages
    • Client messages
    • Server-side and input queues
    • Input prediction and rollback
    • Animations
  • Persistence
    • Overview
    • Configuring persistence
    • Storage
    • Example – A global counter
  • Optimization
    • Overview
    • Simulation frequency
    • Areas of interest
    • World size
    • Level of detail
    • Interpolation
    • Extrapolation
  • Connected entities
    • Overview
    • Entity references
    • Parent-child relationships
    • CoherenceNode
  • Simulators
    • Overview
    • Client vs. simulator logic
    • Build and deploy
    • Simulator load balancing
    • Room Simulators
    • World Simulators
    • Simulator Slugs
    • Testing Simulators Locally
  • Tutorial project
    • Get the Tutorial Project
    • Start Tutorial
      • 1. Transforms
      • 2. Physics
      • 3. Persistence
      • 4. Animation and Variables
      • 5. AI Navigation
      • 6. Network Commands
      • 7. Team based
      • 8. Connected Entities
  • Game Services
    • Game account
    • Key-value store
    • Matchmaking
  • Developer Portal
    • Overview
    • Dashboard
    • Enabling Game Services
    • Configure Rooms
    • Manage Worlds
  • API reference
    • Network SDK
      • CoherenceSync
      • MonoBridge
      • LiveQuery
      • Archetype
      • Sample UI
      • Settings Window
      • Custom Bindings (Advanced)
      • PlayResolver
      • Rooms
      • Worlds
    • Cloud API
      • API tokens and keys
      • Game account
      • Key-value store
      • Matchmaking
    • Replication Server
    • Simulation Server
  • Schema reference
    • Overview
    • Specification
    • Field Settings
    • Archetypes and LOD-ing
  • Resources
    • Downloads
    • SDK Update Guide
    • Video Tutorials
    • Glossary
    • CLI Utilities
    • Simulator CLI arguments
    • Helper Scripts
    • Troubleshooting
  • Community
    • Discord
  • Additional information
    • Pricing
    • SLA
    • Unreal Engine support
    • WebGL
    • Peer-to-Peer (P2P)
    • Known Issues
    • Changelog
Powered by GitBook
On this page
  • Overview
  • Enabling client messages
  • Connection management
  • Sending client messages

Was this helpful?

Export as PDF
  1. Authority and communication

Client messages

Last updated 3 years ago

Was this helpful?

Overview

Client messages are a form of that are used for client-to-client communication rather than client-to-entity. To achieve this type of communication a special connection entity is automatically created by the for each connected client. Those entities are subject to a different rule set than standard entities. Connection entities:

  • Can't be created or destroyed by the client - they are always replication server-driven

  • Are global - they are replicated across clients regardless of the in-simulation distance or radius

Client messages shine whenever there's a need to communicate something to all the connected players. Usage examples:

  • Global chat

  • Game state changes: game started, game ended, map changed

  • Server announcements

  • Server-wide leaderboard

  • Server-wide events

Enabling client messages

The globality of client messages doesn't fit all game types - for example, it rarely makes sense to keep every client informed about the presence of all players on the server in an MMORPG (think World Of Warcraft). Due to this reason, client messages are turned off by default. To enable client messages:

1. Turn on the global query in the (the Global Query On toggle)

Global query enables querying for entities containing a global component, including a connection entity.

Disabling global query on one client doesn't affect other clients, i.e. connection entity of this client will still be visible to other clients that have the global query turned on.

2. Create a class that inherits from the CoherenceClientConnection class

public class PlayerConnection : CoherenceClientConnection
{
    // My chat command
    public void OnChatMessage(string message)
    {
        Debug.Log($"Received chat message: {message}");
    }
}

3. Create a client connection prefab

4. Binding of the method to CoherenceSync

Next, we have to create a binding. Navigate to CoherenceSync component on your prefab and press Select, in appeared window open Methods tab and check OnChatMessage:​

5. Link the connection prefab to the MonoBridge

For the system to know which object to create for every new client connection, we have to link our prefab to the Coherence MonoBridge. Simply drag the prefab to the Client Connection Prefab field in the MonoBridge inspector:​

Connection management

Once we have everything set up, whenever a new client joins an instance of the connection prefab will be created. The instantiated object resembles a client connection and will be kept alive for as long as that client remains connected to the replication server.

To get notified about the creation and destruction of connections we can use the following events:

public class GameManager : MonoBehaviour
{
    public CoherenceMonoBridge MonoBridge;

    private void Start()
    {
        MonoBridge.OnConnectionCreated += OnConnectionCreated;
        MonoBridge.OnConnectionDestroyed += OnConnectionDestroyed;
    }

    private void OnConnectionCreated(CoherenceClientConnection clientConnection)
    {
        Debug.Log($"Client connected: {clientConnection.Id}");
    }

    private void OnConnectionDestroyed(CoherenceClientConnection clientConnection)
    {
        Debug.Log($"Client disconnected: {clientConnection.Id}");
    }
}

The connection ID is simply an EntityID of the connection entity.

To get local connection or connection of any client by the ID use the following MonoBridge methods:

PlayerConnection myConnection 
    = MonoBridge.GetMyConnection<PlayerConnection>();
    
PlayerConnection otherPlayerConnection 
    = MonoBridge.GetClientConnection<PlayerConnection>(otherPlayerId);

A null may be returned by both methods if client messages are not enabled or the connection with a given ID doesn't exist.

The CoherenceClientConnection class exposes the following properties:

PlayerConnection playerConnection = MonoBridge.GetMyConnection<PlayerConnection>(id);

// ID of the connection (and connection entity)
SerializeEntityID connectionId = playerConnection.Id;

// True if this is connection belongs to the local client
bool isMyConnection = playerConnection.IsMyConnection;

// CoherenceSync of the connection object
CoherenceSync sync = playerConnection.Sync;

Sending client messages

Client messages are sent using the SendClientMessage method of the CoherencePlayerConnection class:

private void OnConnectionCreated(CoherenceClientConnection clientConnection)
{
        clientConnection.SendClientMessage("OnChatMessage", MessageTarget.AuthorityOnly, "This is a private message");

        clientConnection.SendClientMessage("OnChatMessage", MessageTarget.All, "This is a global message");
}

The first message will be delivered only to the player that owns the created connection. The other message will be delivered to all instances of this connection, that is, every player (including the sender) that knows about this connection will receive this message.

If the connection ID of the message recipient is known we can use the MonoBridge to send a client message:

private SerializeEntityID newestConnectionId;

private void OnConnectionCreated(CoherenceClientConnection clientConnection)
{
    if (!clientConnection.IsMyConnection)
    {
        newestConnectionId = clientConnection.Id;
    }
}

public void SendMessageToNewestConnection(string message)
{
    MonoBridge.SendClientMessage("OnChatMessage", newestConnectionId, MessageTarget.AuthorityOnly, "Hello!");
}

Under the hood, client messages are nothing but sent between the connected entities. Each such entity is represented on the client side by an instance of a CoherenceClientConnection class. Implementing client messages is as simple as adding a new command to our custom connection class:

This step is described in detail in the . In short, a prefab with CoherenceSync and our PlayerConnection must be created and placed in the Resources directory:​

PlayerConnection prefab
commands
Prefab setup section
commands
replication server
live query
Coherence MonoBridge
MonoBridge component
Binding a client message
MonoBridge with linked connection prefab