Server Browser

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

💡 Features

Gain access to prebuilt automated features by installing our SDK:

• Complete Examples

• Lifecycle Management

• Capacity Management

• Filter Query Compiler

• 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 Server Browser concepts and a running Server Browser.

We strongly recommend importing our Auto-Assign 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:

    • Server Agent - a complete server integration to reuse/extend.

    • Client Agent - a complete client integration to reuse/extend.

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

    • Filter Compiler - strongly typed utilities for building filter queries.

  • Service-Specific DTOs - typed data containers for Server Browser 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:

  • Auto-Assign - example handlers with auto-assigned reservations,

  • Custom Search - example handlers with manual instance choice.

Server Agent

Server Lifecycle and Capacity management are performed by Server Agent.

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

• onMonitorUpdate callback - observe service health changes,

• onInstanceUpdate callback - observe and react to instance and slot changes,

• onConfirmationsUpdate callback - observe and react to federated authentication.

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:

• DiscoverInstance to create initial Server Instance and Slots and initiate heartbeat,

• DeleteInstance once the match concludes / to prevent new players from joining,

• ConfirmReservation when players join, to verify their identity and slot assignment,

• UpdateSlot to update slot capacity (on player joined/abandoned) or modify metadata,

• UpdateInstance to modify instance metadata,

• Status to verify Server Browser service health.

Confirmations and Slot/Instance Updates are queued and performed in batches by default (Heartbeat Mode) to maximize scalability. To iterate quicker during dev testing, use Greedy Mode.

When updating metadata, all indices must be defined. To unset non-indexed keys, simply omit them.

The agent automatically maintains a heartbeat to keep the server discoverable while running. If the agent can't reach your server browser for several consecutive heartbeats (configurable):

• less than maximum - instance will be automatically re-discovered,

• more than maximum - instance will be automatically deleted.

When a new player connection is established, player is expected to send their reservation ID (third party player ID) to the game server using your netcode, to perform reservation confirmation.

Once onConfirmationsUpdate triggers, handler must perform additional actions:

• call UpdateSlot to reduce available seats for any slots with confirmed reservations,

• accept or deny connection using netcode-specific methods.

When a player abandons game, handler is expected to increase available seats for this slot.

Allow a short time period for players to reconnect before abandoning in case of unexpected crashes.

Client Agent

Searching for instances, pagination, filtering, and reservations are performed by Client Agent.

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

• onMonitorUpdate callback - observe service health changes,

• onInstancesUpdate callback - observe and react to instance list 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:

• ReserveSeats to create a capacity reservation for a particular instance/slot or auto-assign,

• ListInstances to list instances with a specific filter, ordering, cursor, and page size,

• GetNextPage to fetch more instances with the current parameters (filters, etc),

• RefreshList to clear cache and reload first page, or refresh with a specific cursor,

• GetInstanceDetails to fetch instance metadata and slots information for a specific instance,

• Status to verify Server Browser service health.

When a new player connection is established, player is expected to send their reservation ID (third party player ID) to the game server using your netcode, to perform reservation confirmation.

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.

Auto-Assign

Utilizes auto-assigned reservations, with client specifying only policy name. Server browser chooses an instance matching policy filter and slot with sufficient seats automatically.

Custom Search

Includes a full implementation demonstrating how to search instances and slots, hook up UI elements, and let player choose where they wish to reserve capacity manually.

⚙️ 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 lifecycle and capacity 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 Server Browser 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.

Server Events

Server Agent 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.
🟡 Warn	request timeout clamped to heartbeat [{timeout}]	Prevents race conditions.

Preview events (actions) emitted by observable Instance:

Action Type	Event Message	Description
🟢 Update	discovered	Instance Discovery completed OK. May be triggered if instance lost connection due to temporary condition and re-discovered.
🔴 Error	discovery duplicate	Instance with this Request ID is already discovered.
🔴 Error	discovery failed	Unexpected issue with discovery.
🔵 Notify	heartbeat ok	Heartbeat completed OK.
🟡 Warn	heartbeat failed [{consecutive}/{maximum}]	Heartbeat failed, server couldn't reach Server Browser.
🔵 Notify	instance update enqueued	Enqueued instance update for next batch (heartbeat/greedy).
🟢 Update	instance updated	Instance metadata updated OK.
🔴 Error	instance update failed, enqueuing for retry	Instance update failed, possibly due to rate limiting or error.
🟢 Update	instance deleted	Instance is no longer discoverable by players.
🟢 Update	instance delete failed (not found)	Instance may have expired due to too many missed heartbeats.
🔴 Error	instance delete failed	Failed to delete Instance, possibly due to rate limiting or error.
🔵 Notify	slot update enqueued [{slot}]	Enqueued slot update for next batch (heartbeat/greedy).
🟢 Update	slot updated [{slot}]	Slot seats capacity and/or metadata updated OK.
🟡 Warn	agent throttled concurrent slot update	Prevented attempt at concurrent update (race condition).
🔴 Error	slot update failed (not found) [{slot}]	Slot with this name is not defined for this Instance yet.
🔴 Error	slot update failed (not enough seats) [{slot}]	Slot update tried to reduce available seats below zero.
🔴 Error	slot update failed, enqueuing for retry [{slot}]	Slot update failed, possibly due to rate limiting or error.

Preview events (actions) emitted by observable Confirmations:

Action Type	Event Message	Description
🔵 Notify	enqueued [{player}]	Enqueued confirmation for next batch (heartbeat/greedy).
🟡 Warn	duplicate [{player}]	Prevented attempt at duplicated confirmation (already queued).
🟢 Update	confirmed	Confirmed reservations for individual slots, includes also expired and unknown player IDs for handler to resolve (accept/kick).
🔴 Error	failed	Unexpected issue with confirmations. Check service status.

Client Events

Client Agent 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.

Preview events emitted by observable Instances:

Action Type	Event Message	Description
🔵 Notify	seats reserved	Seat reservation OK.
🔴 Error	seats reservation failed (not found)	Auto-Assign - policy name not found (deleted or inactive). Custom Search - instance or slot not found.
🔴 Error	seats reservation failed (reached capacity)	Auto-Assign - policy reached maximum capacity. Custom Search - slot reached maximum capacity.
🔴 Error	seats reservation failed	Seat reservation failed, possibly invalid policy, request ID, or slot ID.
🟢 Update	instance list retrieved	Fetched list of instances OK.
🟢 Update	instance list next page retrieved	Fetched next page of instances OK.
🔴 Error	instance list last page reached	Failed to fetch next page, try refreshing or changing filters.
🔴 Error	instance list next page retrieval failed	Failed to fetch next page, possibly due to an invalid cursor.
🟢 Update	instance details retrieved	Fetched details of a listed instance OK.
🟢 Update	instance not cached, prepending	Fetched details of instance outside current list.
🔴 Error	instance details retrieval failed	Failed to fetch details, possibly due to invalid request ID.