> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/unity/matchmaking.md).

# Matchmaking

This SDK is an optional starter kit for Unity users, which can be extended and customized later.

## 💡 Features

{% columns %}
{% column %}

* Complete Examples
* Ping Automation
* Tickets, Groups, Teams
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Match Variables
* Type Definitions (C#)
* Local Dev Testing
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Cross-Platform
* Easy to Customize
* Automated Retry
  {% endcolumn %}
  {% endcolumns %}

## ✔️ Preparation

Unity SDK contains optional integration utilities for Deployments, Matchmaking, and Server Browser. This plugin officially supports Unity versions 2021.3.0f1 and later.

{% hint style="success" %}
This plugin is provided 100% free of charge, under Terms and Conditions of Free Tier.
{% endhint %}

#### Requirements

<details>

<summary>Install a Git Client (for example <a href="https://git-scm.com/">git-scm</a>)</summary>

A git client is needed for Unity to download and install our Unity package automatically. You will not need to use git directly once it's installed.

</details>

#### Installation

1. Open your Unity Project,
2. Select `Window > Package Management > Package Manager` ,
3. Click the :heavy\_plus\_sign: icon and select `Add package from git URL...` ,
4. Input the URL of our SDK when prompted:

{% code title="" %}

```
https://github.com/edgegap/edgegap-unity-sdk.git
```

{% endcode %}

5. Click `Add`  and wait until installation is completed.

#### Import Samples

This package includes multiple samples, intended to be used individually (do not combine samples).

#### Verified Sources

This is the only official distribution channel for this SDK, do not trust unverified sources!

#### Update Package

Navigate to Edgegap SDK in Unity Package Manager and click `Update` .

{% hint style="warning" %}
**Imported Samples are not updated automatically!** Back up any custom property values, delete the sample scripts used in your scene currently and re-import samples.
{% endhint %}

{% hint style="info" %}
Some releases may contain breaking changes. This will be indicated by a new MAJOR version.
{% endhint %}

#### Updating to v3

This update includes many new [Server Browser](/unity/server-browser.md) utilities and examples, improves matchmaking error handling, and more. See [Release Notes](/docs/release-notes.md) for a complete list.

{% hint style="warning" %}
Unity SDK update v3 includes a few breaking changes. Please re-test your integration carefully.
{% endhint %}

## 🍀 Getting Started

This guide assumes basic knowledge of [Matchmaking](/learn/matchmaking.md) concepts and a running Matchmaker.

{% hint style="success" %}
**We strongly recommend importing our Simple Example** to follow along code as you read this document. You can do so in `Unity Package Manager > Edgegap SDK > Samples` .
{% endhint %}

### Overview

Our SDK utilizes heavily [Dependency Injection](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/overview#the-concept) and [Observer](https://learn.microsoft.com/en-us/dotnet/standard/events/observer-design-pattern) programming patterns.

{% hint style="info" %}
This package integrates both [Server Browser](/learn/server-browser.md) and [Matchmaking](/learn/matchmaking.md), which can be used together or separately. You may freely reuse any scripts for your own customized forks and integrations.
{% endhint %}

This package includes:

* Runtime Files - will be compiled and bundled with your client and server builds:
  * Service-Specific Utilities:
    * [#client-agent](#client-agent "mention") - a complete client integration to reuse/extend.
    * API functions - endpoint definitions, error handling, and logging automations.
  * Service-Specific DTOs[^1] - typed data containers for Matchmaking API.
  * Shared Utilities - logging, HTTP, ping, observables, etc...
  * Shared DTOs[^1] - used by multiple Edgegap services to pass data around.
* Sample Files - bundled and compiled ONLY if imported in your project:
  * [#simple-example](#simple-example "mention") - example handlers for a [minimal configuration](/learn/matchmaking.md#simple-example).
  * [#region-picker](#region-picker "mention") - explore UI integration with manual region selection.

### Group Client

**Ping automation, ticket management, and host retrieval** are performed by Group Client.

Once instantiated, agent's **parent Monobehaviour (handler) must initialize the client** and provide:

* `onMonitorUpdate`  callback - observe service health changes,
* `onAssignmentUpdate`  callback - observe and react to host assignment changes.

Once initialized, this client will automatically provide validations and hook up logging observers, finishing with a single call to the monitoring API endpoint to indicate service health.

Client's handler is expected to take control and call client functions from this point:

* `Beacons`  to retrieve a list of available [Ping Beacons](/learn/orchestration/ping-beacons.md),
* `MeasureBeaconsRoundTripTime`  to provide ping measurements against a given set of beacons,
* `CreateGroup`  for the lobby leader to create a joinable group, which friends can be invited to,
* `JoinGroup`  to join an existing group using the group ID sent through 3rd party lobby/backend,
* `SetReady`  to mark group owner and members as ready and begin searching for matches,
* `ResumeMatchmaking`  load a cached group and continue searching in case client crashed,
* `StopMatchmaking`  to delete the ticket (if not matched) and abandon queue,
* `Status`  to verify Server Browser service health.

When a new player connection is established, player is expected to send their ticket ID to the game server using your netcode, to correlate connections with [In-Depth Look](/learn/matchmaking/matchmaker-in-depth.md#injected-variables).

{% hint style="success" %}
Save connection details in client or game backend to reconnect in case of an unexpected crash.
{% endhint %}

## 🧪 Samples

Get started with samples including a complete functioning integration for both server and client.

### Simple Example

Includes a full player lifecycle implementation with ping measurement, ticket management, and host assignment retrieval. Demonstrates how to read injected match variables on server side.

Modify matchmaking attributes to expand this example to fit any configuration easily.

### Region Picker

Some players (or groups) have special localized conditions (such as ISP[^2] blockage, [country-wide blockage](#user-content-fn-3)[^3], or other) and may prefer choosing a region manually rather than based on ping alone.

Inspect our Region Picker sample and draw inspiration for your matchmaking UI implementation.

### Group Up

Join matchmaking queue with a group of friends, requiring all players to confirm before starting search. Get started with a minimal UI implementation, then customize for your game design.

Explore UI integration with the group up flow and deliver the best possible social experience.

## ⚙️ Customization

This SDK is meant to be extended and modified, though some modifications may be risky:

✅ Handler - safely hook up UI observers and perform minor additions or modifications,

⚠️ Agent - modify player lifecycle management at your own risk,

⚠️ API - write your own integration from scratch, using cherry-picked utilities.

Handlers may observe any events emitted by Server and Client agents as described below.

{% hint style="warning" %}
Make sure to get familiar with [Matchmaking In-Depth](/learn/matchmaking/matchmaker-in-depth.md) concepts before making customizations.
{% endhint %}

{% hint style="info" %}
If you need help, [please reach out to us over Discord](https://discord.gg/MmJf8fWjnt). For live games support see our [ticketing system](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### Observe Events

Group Client emits events (actions) for parent handler to observe and consume.

{% hint style="success" %}
Read event payloads by accessing  `.Current` state of any observable. 🔴 `Error` events contain full error message delimited by a newline character after the main event message.
{% endhint %}

Preview events emitted by observable `Monitor` :

<table data-full-width="true"><thead><tr><th width="125">Action Type</th><th width="450">Event Message</th><th>Description</th></tr></thead><tbody><tr><td>🟢 <code>Update</code> </td><td><code>healthy</code></td><td>All systems OK.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>unhealthy</code></td><td>Unexpected issue.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>get monitor failed</code></td><td>Misconfiguration or unexpected issue.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>get beacons failed</code></td><td>Unexpected issue.</td></tr></tbody></table>

Preview events emitted by observable `Group`:

<table data-full-width="true"><thead><tr><th width="125">Action Type</th><th width="450">Event Message</th><th>Description</th></tr></thead><tbody><tr><td>🟢 <code>Update</code> </td><td><code>created</code></td><td>Group created OK.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>group create failed</code></td><td>Failed to create group.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>joined</code></td><td>Group joined OK.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>group join failed</code></td><td>Failed to join group.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>resumed</code></td><td>Group resumed OK.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>group not found</code></td><td>Not a member of group, or group expired.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>conflict, abandon and restart</code></td><td>Please abandon current group before trying to create/join a new group.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>member updated [{ready}]</code></td><td>Member updated with new Ready value.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>member update failed</code></td><td>Failed to update group member. Can't unready after the group started searching for match.</td></tr><tr><td>🔵 <code>Notify</code></td><td><code>polling [{consecutive}/{maximum}]</code></td><td>Client initiated polling group status.</td></tr><tr><td>🔵 <code>Notify</code></td><td><code>polling stopped</code></td><td>Client stopped polling ticket status.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>polling failed, reached maximum retries</code></td><td>Client exhausted maximum consecutive polling retries. Check service status.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>polling failed</code></td><td>Client received a non-retryable error when polling. Check service status.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>group updated [{status}]</code></td><td>Detected group status change while polling.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>abandoned</code></td><td>Deleted ticket OK.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>abandon failed (not found)</code></td><td>Client couldn't find the ticket to delete, possibly expired.</td></tr><tr><td>🟡 <code>Warn</code></td><td><code>abandon failed (already matched)</code></td><td>Client couldn't delete a matched group. Disable abandonment or <a data-mention href="/pages/kBCQHitUL4u9O0iTPk7x#backfill-match">/pages/kBCQHitUL4u9O0iTPk7x#backfill-match</a> to replace the player.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>abandon failed</code></td><td>Failed to delete group or membership.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>removed</code></td><td>Group expired, local reference deleted.</td></tr></tbody></table>

[^1]: Data Transfer Object

[^2]: [Internet Service Provider](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: most notably China or Russia


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgegap.com/unity/matchmaking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.