Events & States
MatchmakingBehaviour tells your game what is happening through events and a connection state.
Events
| Event | Arguments | When it fires |
|---|---|---|
OnMatchFound | MatchFoundMetadata (MatchId, Team) | A match was made for this player. |
OnError | ErrorData, bool isTerminal | The server sent an error, or a connection attempt failed. See Error Handling. |
OnSearchSuperseded | none | The same player started a search from a newer connection, so this connection was closed. |
OnStateChanged | MatchmakingConnectionState | The connection state changed. |
OnSearchStarted | SearchStartedData (GameMode, StartedAt, PartyId) | The server confirmed the search is queued. Every party member receives it, not just the leader. |
OnPartyUpdated | PartyState | The party changed. Always the full state. |
OnPartyLeft | PartyLeftData (PartyId, Reason) | You left the party or were kicked. |
OnPartySearchCancelled | PartySearchCancelledData (Reason, UserId) | The party's search stopped before a match. |
OnPartyInvite | PartyInviteData (PartyId, FromUserId) | Another player invited you to their party. |
The last four are only used with Parties.
They are UnityEvents, so you can wire them up in the Inspector as well as in code. They always run
on Unity's main thread.
MatchFoundMetadata.Team is the zero-based team index, per the game mode's
Match Shape.
Connection state
MatchmakingBehaviour.State and OnStateChanged report one of:
| State | Meaning |
|---|---|
Idle | Not searching: nothing started yet, the search was cancelled, or a match was found. |
Connected | Connected with ConnectAsync and not searching, for example while forming a party. |
Connecting | Getting a ticket and opening the connection. |
Searching | In the queue. Heartbeats are being sent. |
Reconnecting | The connection dropped and the SDK is waiting to retry. |
Closed | The connection ended: you closed it, the search was superseded, or reconnect attempts ran out. |
Faulted | A terminal error ended the search. |
A search started with BeginSearchAsync alone goes Idle → Connecting → Searching → Idle (the final Idle arrives
with OnMatchFound). State is Idle before you start.
_matchmaking.OnStateChanged.AddListener(state =>
{
statusLabel.text = state switch
{
MatchmakingConnectionState.Connecting => "Connecting…",
MatchmakingConnectionState.Searching => "Searching for a match…",
MatchmakingConnectionState.Reconnecting => "Connection lost. Reconnecting…",
_ => string.Empty,
};
});Superseded searches
If a player starts a search on a second device or client while one is already running, the first
connection receives OnSearchSuperseded and closes. Treat it as "this client is no longer
searching" and return the player to your menu.
_matchmaking.OnSearchSuperseded.AddListener(() => ShowMainMenu());Next
Error Handling covers OnError in detail.