Matchmaking

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

💡 Features

• Complete Examples

• Ping Automation

• Tickets, Groups, Teams

• Match Variables

• Type Definitions (C#)

• Local Dev Testing

• Cross-Platform

• Easy to Customize

• Automated Retry

✔️ Preparation

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

This plugin is provided 100% free of charge, under Terms and Conditions of Free Tier.

Requirements

Install a Git Client (for example git-scm)

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.

Installation

1. Open your Unity Project,

2. Select Window > Package Management > Package Manager ,

3. Click the ➕ icon and select Add package from git URL... ,

4. Input the URL of our SDK when prompted:

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

1. 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 .

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.

Some releases may contain breaking changes. This will be indicated by a new MAJOR version.

Updating to v3

This update includes many new Server Browser utilities and examples, improves matchmaking error handling, and more. See Release Notes for a complete list.

Unity SDK update v3 includes a few breaking changes. Please re-test your integration carefully.

🍀 Getting Started

This guide assumes basic knowledge of Matchmaking concepts and a running Matchmaker.

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 .

Overview

Our SDK utilizes heavily Dependency Injection and Observer programming patterns.

This package integrates both Server Browser and Matchmaking, which can be used together or separately. You may freely reuse any scripts for your own customized forks and integrations.

This package includes:

• Runtime Files - will be compiled and bundled with your client and server builds:

  • Service-Specific Utilities:

    • Matchmaking - a complete client integration to reuse/extend.

    • API functions - endpoint definitions, error handling, and logging automations.

  • Service-Specific DTOs - typed data containers for Matchmaking API.

  • Shared Utilities - logging, HTTP, ping, observables, etc...

  • Shared DTOs - used by multiple Edgegap services to pass data around.

• Sample Files - bundled and compiled ONLY if imported in your project:

  • Simple Example - example handlers for a minimal configuration.

  • Region Picker - 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,

• 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 📌 Injected Variables.

Save connection details in client or game backend to reconnect in case of an unexpected crash.

🧪 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 blockage, country-wide blockage, 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.

⚙️ 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.

Make sure to get familiar with Matchmaking In-Depth concepts before making customizations.

If you need help, please reach out to us over Discord. For live games support see our ticketing system.

Observe Events

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

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.

Preview events emitted by observable Monitor :

Action Type	Event Message	Description
🟢 Update	healthy	All systems OK.
🟢 Update	unhealthy	Unexpected issue.
🔴 Error	get monitor failed	Misconfiguration or unexpected issue.
🔴 Error	get beacons failed	Unexpected issue.

Preview events emitted by observable Group:

Action Type	Event Message	Description
🟢 Update	created	Group created OK.
🔴 Error	group create failed	Failed to create group.
🟢 Update	joined	Group joined OK.
🔴 Error	group join failed	Failed to join group.
🟢 Update	resumed	Group resumed OK.
🔴 Error	group not found	Not a member of group, or group expired.
🔴 Error	conflict, abandon and restart	Please abandon current group before trying to create/join a new group.
🟢 Update	member updated [{ready}]	Member updated with new Ready value.
🔴 Error	member update failed	Failed to update group member.
🔵 Notify	polling [{consecutive}/{maximum}]	Client initiated polling group status.
🔵 Notify	polling stopped	Client stopped polling ticket status.
🔴 Error	polling failed, reached maximum retries	Client exhausted maximum consecutive polling retries. Check service status.
🔴 Error	polling failed	Client received a non-retryable error when polling. Check service status.
🟢 Update	group updated [{status}]	Detected group status change while polling.
🟢 Update	abandoned	Deleted ticket OK.
🟢 Update	abandon failed (not found)	Client couldn't find the ticket to delete, possibly expired.
🟡 Warn	abandon failed (already matched)	Client couldn't delete a matched group. Disable abandonment or Backfill Match to replace the player.
🔴 Error	abandon failed	Failed to delete group or membership.
🟢 Update	removed	Group expired, local reference deleted.