Push channels in CloudBehaviours
Declare a push channel, listen for it in your game, and understand how delivery works.
Read time 4 minutesLast updated 2 days ago
Important
This page describes an experimental feature that might change significantly before release. It's not recommended to use or rely on experimental features in production environments due to potential instability.
A push channel is a public event on a CloudBehaviour that notifies players when the cloud class invokes it. When the event fires, the generated code sends a player message, tagged with a message type named after the event, over each player's push connection. In a scope, every player in the session receives the message. In a scope, only that player receives it. The client bindings then raise a matching . Use a push channel to notify players as soon as something happens, such as a turn ending, without polling.
MultiplayerSessionPlayerUnityEventPush channels and synchronized state serve different purposes. To decide which one to use, refer to Choose between a push channel and synchronized state.
Declare a push channel
To declare a push channel, add a public event of type , , , or to the cloud class. The following example declares a push channel that reports which player ended the round:
ActionAction<T>EventHandlerEventHandler<T>[StateScope(Scope.MultiplayerSession)]public class MatchState : CloudBehaviour{ public int Round; public event Action<string> RoundEnded; public void PlayTurn() { Round++; RoundEnded?.Invoke(Context.PlayerId); }}
Event payloads serialize as JSON. An event can have at most four parameters.
Listen for push channel events in your game
The generated client bindings expose each push channel as a . Subscribe with :
UnityEventAddListenerprotected virtual void OnEnable(){ EnableClient(); RoundEnded.AddListener(playerId => Debug.Log($"Round ended by {playerId}"));}
Because the client bindings expose push channels as instances, you can also use the Inspector window to add listeners.
UnityEventPush message delivery
Only connected clients receive a push message. Push channels are transient. Cloud Code doesn't store or replay a push message for a player who connects later. Represent lasting state as synchronized state instead.
Every player in the session receives an event that you invoke, whatever its payload. To send player-specific data to one player, such as the card a player drew, use instead of an event. To control what each player receives in synchronized state, refer to Per-player state views in CloudBehaviours.
Push.SendPlayerMessageAsync(Context, message, messageType, playerId)Choose between a push channel and synchronized state
Push channels and synchronized state both send data from a CloudBehaviour to clients. Synchronized state holds the current value of something, such as the score or whose turn it is. A push channel reports that something happened, such as a player ending a round.
The following table compares push channels and synchronized state.
Characteristic | Synchronized state | Push channel |
|---|---|---|
| What it represents | The current value of a member | An occurrence at a specific moment |
| How the client reads it | Read the generated property at any time | Handle the generated |
| Players who connect later | Receive the current value when the client's scope resolves | Don't receive the message |
| Client notification | The | A dedicated |
Use synchronized state for information that a player needs to read at any time, including after reconnecting. Use a push channel to trigger a reaction at the moment something happens, such as an animation, a sound, or a notification.
You don't need to repeat synchronized state in the event payload, because each push channel message also carries the synchronized state. The client bindings apply that state before they raise the event, so a listener can read up-to-date synchronized state directly. Use the event payload only for details about the occurrence that synchronized state doesn't hold, such as which player ended the round. The message carries the state from the moment the cloud class invokes the event, so update synchronized state before you invoke the event.
Cloud Code doesn't replay push messages, so don't rely on a push channel alone for information that a player needs later. For example, store the winner of the last round in synchronized state so that a reconnecting player can display it, and invoke a push channel event to play a victory animation for connected players.