# 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

This plugin has been tested, and supports Unity versions 2021.3.0f1+, including Unity 6 LTS.

{% 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).

### Client Agent

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

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

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

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

Agent's handler is expected to take control and call agent 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,
* `StartMatchmaking`  to create a ticket and being searching for a match,
* `ResumeMatchmaking`  to load a previously created (cached) ticket and continue searching,
* `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.

## ⚙️ 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 %}

### Client Events

Client Agent 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 `Assignment`:

<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>received</code></td><td>Ticket created OK.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>resumed</code></td><td>Ticked loaded OK.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>ticket create failed</code></td><td>Failed to create ticket.</td></tr><tr><td>🔴 <code>Error</code></td><td><code>conflict, abandon and restart</code></td><td>Another ticket is searching for a match, abandon the ticket before restarting.</td></tr><tr><td>🔵 <code>Notify</code></td><td><code>polling [{consecutive}/{maximum}]</code></td><td>Client initiated polling ticket 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>updated [{status}]</code></td><td>Detected ticket 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 ticket. Prevent 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>Unexpected issue.</td></tr><tr><td>🟢 <code>Update</code> </td><td><code>removed</code></td><td>Removed local ticket and assignment reference, reflecting resource expiration.</td></tr></tbody></table>

[^1]: Data Transfer Object


---

# Agent Instructions: 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.