Server Browser

Get started with Server Browser quickly and explore example scenarios for various genres.

Server Browser is a managed service for Match-Bound and Persistent servers:

help players search and join suitable servers based on capacity, latency, or game parameters;
pre-warm new servers to serve global audiences at scale and prevent frustrating queues;
streamline server operations including updates, restarts, persistence, meshing, and more.

Looking to match players based on strict rules, without allowing server choice? Consider Matchmaking.

✔️ Preparation

Testing this service is entirely free, no credit card required.

Free Tier allows up to 3 hours of runtime on our shared test cluster, after each restart.

This tutorial assumes you have already:

understood Edgegap’s deployment model,
published your server application on Edgegap (Unreal Engine, Unity),
successfully connected from a game client to your server on Edgegap.

Functions and Flow

Server Browser offers two main features:

▶️ Start Browsing with Game Clients to:

Discover and find suitable server instances, view slots, and reserve available capacity.
Reserve seats in an instance slot, retrieve connection details, and connect to servers.
Authenticate player connections in Deployments using Federated Identity.
Update instance slots' available capacity and/or metadata to modify discovery criteria.

🚀 Automated Scaling (optional) with Scaling Policies to:

Monitor available server instances, slots, capacity - per region and/or other criteria.
Deploy Servers to increase capacity with prewarming or just-in-time scaling.
Automate ops with special policies for demos, updates, testing, QA, tournaments, and more.

After release, your server browser will need to run 24/7 to ensure players across the world can join servers.

▶️ Start Browsing

Learn about server/player lifecycle and their responsibilities to ensure efficient server use.

Authenticate

All requests must send an Authorization HTTP header with your secret Auth Token:

Authorization: xxxxxxxx-e458-4592-b607-c2c28afd8b62

Keep your tokens secret and safe! Edgegap staff will never ask you for your tokens.

Server Browser automatically generates two types of tokens:

Server Token - required for Server API methods, can be injected as app version variable.
- Grants access to all API methods, and is handy for testing, devops, or custom orchestration.
Client Token - required for Monitor API and Seat Reservation API used by Game Clients.
- We recommend storing this token in a third party secret store to make token rotation easier.

Discover Instance

New Deployments must create a new Instance when initialized to keep track of added capacity.

See 🚀 Automated Scaling to learn about Scaling Policies and start deployments automatically.

Required information for each server instance includes:

at least one Slot defined when initializing instance,
server connection details - URL, IP, port information, and location.

Optional custom metadata parameters for player filtering, sorting, and browsing; for example:

slot information - team capacity and team-specific metadata (e.g. team name),
name and tags - customizable, unique, human-readable and searchable labels;
compatibility data - server version or supported client versions;
latency qualifiers - city and region identifiers, and assigned Ping Beacons details;
game parameters - level/scene/map, game mode, difficulty, mods used;
any other custom parameters to help players filter and find a suitable server.

Metadata parameters above are just examples, you can define any number of parameters as needed.

To serialize nested objects try encoding their accessor path in the key as "object.child.property".

Servers may update instance or slot metadata anytime to modify their discoverability criteria. When updating metadata, all indexed keys must be provided with valid values (even if not modified).

Server Instances must periodically send a keep-alive heartbeat to verify their ongoing availability and prevent players from joining crashed or offline servers. Missing heartbeat for the configured expiration period will automatically delete instance and any pending seat reservations.

See Persistence for managing persistent world state and Active Caching for faster deployments.

Allocate Capacity

Instance and Slot capacity may be allocated in two ways, used individually or combined:

Auto-Assigned Reservation to choose a server started with a specific scaling policy,
Search and Browse to let the player define filters and browse suitable servers to pick from.

We recommend getting started with Auto-Assigned Reservation as the simpler option.

Auto-Assigned Reservation

Implement this feature if you wish to choose server automatically, based on regional capacity.

Players may create an auto-assigned reservation, only supplying player IDs and a scaling policy name. Server Browser will automatically find an instance with a slot offering sufficient joinable capacity and reserve seats, responding immediately with instance connection details.

If there is no suitable instance slot for this reservation, the response:

status code indicates whether the policy is scaling up and more capacity will be added,
header Retry-After indicates wait period (seconds) before retrying, if retryable.

Once a reservation is completed, you may skip to Connect to Server.

Search and Browse

Implement this feature if you wish to show users a list of servers and allow custom reservations.

Players may list server instances and paginate through results to find a server they'd like to join.

Instances and slots may be filtered and sorted with built-in parameters or indexed metadata:

Property

Data Type

Instance

Slot

request_id

string

✅

❌

total_joinable_seats, total_available_seats

int

✅

❌

name

string

❌

✅

available_seats, reserved_seats

int

❌

✅

created_at, updated_at

string

✅

metadata.{index} (custom)

string, int, float, bool

✅

Available filtering operators depend on the data type of the filtered property:

Parameter

Operators

Example Filter (based on Simple Example)

string

eq or ne or

lt or le or

gt or ge or contains

?$filter=metadata.custom_name contains 'my game'
and metadata.server_version le '1.1.0'
and metadata.server_version ge '1.0.0'
&$order=metadata.custom_name asc

int, float

eq or ne or

lt or le or

gt or ge

?$filter=metadata.xp_multiplier gt 1.0
&$order=metadata.xp_multiplier desc

bool

eq or ne

?$filter=metadata.allows_new_connections eq true

Filter by regions and/or cities metadata to narrow down selection before measuring latency to servers.

Learn about cursor-based Pagination to let users fetch more results.

Reserve Seats

Before joining a server, a seat reservation is required to ensure that the instance offers sufficient available capacity. Reservations can include a group of players or a solo individual.

Federated Identity: Players must provide a unique third party player ID in their reservation. Sending the same ID once they Connect to Server will allow the server to verify their identity.

Once a reservation is made successfully (200 OK) players should attempt connecting immediately. Pending reservations expire after 30 seconds (configurable) unless confirmed by your server.

Reservations exceeding slot's joinable seat capacity will be automatically rejected (409 Conflict). Joinable seats are any available seats which have not been reserved by other players yet.

Server may forcefully change any slot's capacity, add, delete, or update any slots. All reservations for a given slot will be removed if any pending reservations exceed new available slot capacity.

Connect to Server

Once a player found a suitable instance, they retrieve required connection details from (URL or IP, External Port). As soon as the seat reservation is made, players may proceed to connect to your deployment's game server and pass their player ID.

To connect from PIE (Editor) during development and testing, press the tilde key ~ and type open {URL}:{port} and wait for your editor to load the map.

In case of failed connections or dark screen consult our troubleshooting guide.

To authenticate new connections, your server must send a bulk reservation confirmation request with all new players' IDs, receiving information in confirmation response:

assignment of accepted player reservations to their preferred slot,
assignment of expired player reservations to their preferred slot,
a list of unknown player IDs.

Your server may decide how to handle each group of players and whether to allow or kick/ban expired or rejected users. Each of the instance's slots must be updated immediately with the new available seat count to ensure future reservations won't exceed slot capacity.

Abandon Server

When players leave, your server must increase available seat capacity for the assigned slot.

If your game design allows a reconnection period, your server may wait before updating slots.

Read about Recovery Objectives to prevent frustrating persistent server rollbacks.

🚀 Automated Scaling

Server Browser is compatible with several different methods of autoscoring:

pre-warming method - starting servers strictly with Server Browser scaling policies,
just-in-time method - start through Matchmaking and fill with Server Browser,
custom autoscaler - start through custom game backend and fill with Server Browser.

The following guide will focus on pre-warming with Scaling Policies as the primary method.

Learn how to stop deployments in Unreal Engine, Unity, or with API to manage lifecycle reliably.

Monitor Capacity

Scaling policies continuously refresh the list of your server instances (discovered Deployments), repeating every monitoring_interval . Each policy requires a filter using the same filtering syntax as players do when searching for instances - per region, capacity, or other criteria.

Your configured minimum_active_instances amount can be treated either as a:

fixed capacity of deployments that you wish to keep running at all times,
pre-warm standby deployment buffer to hide initialization delays.

Fixed Capacity

Keep a fixed amount of active servers for games with Persistence, particularly when such games offer players to provision Community Servers.

This type of policy configuration is also sometimes used for Quality Assurance, Tournaments, Closed Alphas, Publisher Demos, or other kinds of limited capacity events and operations.

Scaling policy helps you automatically restart and recycle crashed servers on the fly.

Pre-Warm Standby

Start servers ahead of player demand if:

you're launching a big release and expect rapid inflow of players in a short timespan,
or server initialization requires more than 30 seconds (not including deployment time),
or game implements meshing strategies requiring layered or circular network dependencies.

Deploy Servers

New deployments will be started automatically when the amount of monitored server instances drops below the configured minimum of active instances. All deployments are requested immediately and retried infinitely every monitoring interval after deployment_registration_period elapsed.

Verify that new deployments perform auto-discovery and create instances matching your policy filter correctly, or your policy may loop infinitely and create large amounts of unused deployments!

Policies start deployments with Private Fleets (with Overflow to Cloud) or directly to Cloud.

Available parameters include (see API specification):

application and version - build version, resources, and other orchestration parameters,
users - a single set of geographical coordinates for preferred server placement,
private host IDs - leave empty for cloud, or specify hosts within the desired region,
tags - tag with policy name to find deployments started with this policy later on,
environment variables - pass custom parameters and secrets to servers,
webhooks - notify your game backend (or matchmaker) of deployment lifecycle events,
require cached locations - if you prefer faster deployments only in cached locations.

Example Policies

Test and modify any of these policies as you need. Most games will use multiple policies.

A simple policy to keep one server deployed for testing at all times.

{
  "name": "sb-qa-pool",
  "filter": "metadata.policy_name eq 'sb-qa-pool'",
  "deployment_request": {
    "private_host_ids": [],
    "application": "my-game-server",
    "version": "2024.01.30-16.23.00-UTC",
    "users": [
      {
        "user_type": "geo_coordinates",
        "user_data": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-qa-pool"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-qa-pool",
        "is_hidden": false
      }
    ]
  },
  "minimum_active_instances": 1
}

Start 10x deployments prior to the release in anticipation of demand. Copy for each region.

{
  "name": "sb-v1.0.0-chicago",
  "filter": "total_joinable_seats gt 0 and metadata.policy_name eq 'sb-v1.0.0-chicago'",
  "deployment_request": {
    "private_host_ids": [],
    "application": "my-game-server",
    "version": "2024.01.30-16.23.00-UTC",
    "users": [
      {
        "user_type": "geo_coordinates",
        "user_data": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-v1.0.0-chicago"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-v1.0.0-chicago",
        "is_hidden": false
      }
    ]
  },
  "minimum_active_instances": 10
}

Each region adds deployments as available capacity drops below a threshold.

{
  "name": "sb-mmo-chicago",
  "filter": "total_joinable_seats gt 5 and metadata.policy_name eq 'sb-mmo-chicago'",
  "deployment_request": {
    "private_host_ids": ["alpha-north-america-95fab093"],
    "application": "my-game-server",
    "version": "2024.01.30-16.23.00-UTC",
    "users": [
      {
        "user_type": "geo_coordinates",
        "user_data": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-mmo-chicago"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-mmo-chicago",
        "is_hidden": false
      }
    ],
    "webhook_on_terminated": {
      "url": "https://my-webhook.com"
    }
  },
  "minimum_active_instances": 3
}

One policy per server owner, passing a custom password used for server authentication.

{
  "name": "sb-owner-jnjnc8mid",
  "filter": "metadata.policy_name eq 'sb-owner-jnjnc8mid'",
  "deployment_request": {
    "private_host_ids": ["alpha-north-america-95fab093"],
    "application": "my-game-server",
    "version": "2024.01.30-16.23.00-UTC",
    "users": [
      {
        "user_type": "geo_coordinates",
        "user_data": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["community", "sb-owner-jnjnc8mid"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-owner-jnjnc8mid",
        "is_hidden": false
      },
      {
        "key": "SB_SERVER_PASSWORD",
        "value": "password1234",
        "is_hidden": false
      }
    ],
    "webhook_on_ready": {
      "url": "https://my-webhook.com"
    },
    "webhook_on_error": {
      "url": "https://my-webhook.com"
    },
    "webhook_on_terminated": {
      "url": "https://my-webhook.com"
    }
  },
  "minimum_active_instances": 1
}

One policy per group of servers. Game backend starts a primary node, which spawns replicas. Each node reads injected mesh group ID and search other nodes to network with.

{
  "name": "sb-meshgroup-pqyt8sxcb",
  "filter": "metadata.policy_name eq 'sb-meshgroup-pqyt8sxcb'",
  "deployment_request": {
    "private_host_ids": [],
    "application": "my-game-server",
    "version": "2024.01.30-16.23.00-UTC",
    "users": [
      {
        "user_type": "geo_coordinates",
        "user_data": {
          "latitude": 41.881832,
          "longitude": -87.623177
        }
      }
    ],
    "tags": ["sb-meshgroup-pqyt8sxcb"],
    "environment_variables": [
      {
        "key": "SB_POLICY_NAME",
        "value": "sb-meshgroup-pqyt8sxcb",
        "is_hidden": false
      },
      {
        "key": "SB_MESH_GROUP_ID",
        "value": "pqyt8sxcb",
        "is_hidden": false
      }
    ],
    "webhook_on_ready": {
      "url": "https://my-webhook.com"
    },
    "webhook_on_terminated": {
      "url": "https://my-webhook.com"
    }
  },
  "minimum_active_instances": 9
}

⚙️ Configuration

Server Browser API is generated from a JSON configuration specified when you create a new (or quick-restart) Server Browser. You may specify server and slot expiration, and custom metadata:

sb-simple-example-v1-0-0.json

{
	"version": "1.0.0",
	"server_instances": {
		"expiration_period": "1m",
		"indices": {
			"policy_name": "string",
			"name": "string"
		}
	},
	"server_instance_slots": {
		"indices": {}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "1m"
	}
}

sb-social-example-v1-0-0.json

{
	"version": "1.0.0",
	"server_instances": {
		"expiration_period": "15s",
		"indices": {
			"policy_name": "string",
			"name": "string",
			"third_party_id": "string",
			"level": "string",
			"mode": "string",
			"difficulty": "string",
			"seed": "string",
			"max_players": "int",
			"app_version": "string",
			"location.city": "string"
		}
	},
	"server_instance_slots": {
		"indices": {
			"third_party_id": "string",
			"max_players": "int",
			"avg_latency": "int",
			"player_ids": "string"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "30s"
	}
}

sb-cooperative-example-v1-0-0.json

{
	"version": "1.0.0",
	"server_instances": {
		"expiration_period": "15s",
		"indices": {
			"policy_name": "string",
			"name": "string",
			"third_party_id": "string",
			"level": "string",
			"mode": "string",
			"difficulty": "string",
			"avg_rank": "int",
			"max_players": "int",
			"app_version": "string",
			"tags": "string",
			"match_id": "string",
			"location.city": "string"
		}
	},
	"server_instance_slots": {
		"indices": {
			"third_party_id": "string",
			"max_players": "int",
			"player_ids": "string"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "30s"
	}
}

sb-competitive-example-v1-0-0.json

{
	"version": "1.0.0",
	"server_instances": {
		"expiration_period": "15s",
		"indices": {
			"policy_name": "string",
			"name": "string",
			"third_party_id": "string",
			"avg_rank": "int",
			"max_players": "int",
			"is_ranked": "bool",
			"app_version": "string",
			"cpu_frequency": "int",
			"match_id": "string",
			"location.city": "string"
		}
	},
	"server_instance_slots": {
		"indices": {
			"third_party_id": "string",
			"max_players": "int",
			"avg_rank": "int",
			"avg_latency": "int"
		}
	},
	"seat_reservations": {
		"expiration_period": "30s"
	},
	"scaling_policies": {
		"monitoring_interval": "10s",
		"deployment_registration_period": "15s"
	}
}

For best performance, avoid specifying indices for metadata not used for filtering or sorting. Non-indexed params can be still set and read with server instance or slot details API methods, see 📗 API.

☁️ Hosting Cluster

Server Browser is conveniently hosted and managed 24/7 around the clock by Edgegap.

Choose a hosting option best suited for your goal:

Free Cluster (shared) to test all features and explore synergies with your design,
- shuts down after 3 hours automatically, requiring restart to continue testing.
Private Cluster (dedicated) to ensure a stable environment for your production needs,
- pick your region and get 24/7 support for live games to release with confidence.

Private Cluster Tiers

We currently offer 3 private cluster tiers to cater to everybody’s needs:

Tier

Hobbyist Tier

Studio Tier

Enterprise Tier

Best Suited For

enthusiasts, solo developers

commercial releases

high-traffic launches

Resources

1 vCPU + 2GB RAM

6 vCPU + 12GB RAM

18 vCPU + 48GB RAM

Redundancy

1x virtual node

3x virtual nodes

Rate Limit (req/s)

200

750

2,000

Price, hourly

$0.0312

$0.146

$0.548

Price, 30 days (nonstop usage)

$22.464

$105.12

$394.56

Upgrade to a private cluster with one click to benefit from highly available hosting maintained by Edgegap team with 24/7 live support for publicly released games.

Resource requirements for your instance will depend on factors:

number of players - more players result in more API requests,
number of requests per player - faster retries increase service load and consume resources,
number of servers - more servers result in more data stored and more API requests,
client retry fallback logic - retrying with jittered backoff helps spread traffic burst peaks,
average match duration - shorter sessions require more frequent server browser interaction.

Our clusters use cloud machines featuring AMD/Intel CPUs with clock speed 2.4 - 3.2 GHz.

📗 API

Consider using our SDK for Unreal Engine or Unity to get started quickly with prebuilt examples.

Game Clients and Dedicated Servers send API requests throughout their lifecycle to Server Browser.

Unity/Android - consider using raw string interpolation to prevent code stripping of hardcoded JSONs.

Swagger Web UI: deploying your service will generate an openAPI specification and a convenient web UI. Open the URL in your browser to view and test all API endpoints, and to review payload examples.

83KB

mm-conf-simple-example.yaml

Open

Import API specification to Scalar API Web Client or Swagger Editor to inspect details.

Pagination

Server Browser provides cursor pagination to fetch filtered data incrementally in a specific order. This approach requires sending a cursor (starting point) and a page size (number of response items) whenever fetching more results, as opposed to the traditional limit-offset pagination.

Combined with our proprietary database indexing system developed for game server metadata, cursor pagination provides a fast, consistent, and flexible user experience for filtering highly dynamic data.

Our goal is for users to find a suitable server on the first page. For best experience, we recommend showing cached results for previous pages, and only refreshing results when the user clicks Search.

🔖 Changelog

Semantic Versioning

Our developer tools and managed services use official Semantic Versioning, indicating which updates are ✅ safe (minor, patch) and which may contain ⚠️ breaking changes (major).

Once a version is released, it will never be modified/changed.

The latest version of server browser is 1.0.0 . Keep an eye out for updates and announcements.

PreviousIn-Depth Look NextAdvanced Features

Last updated 4 days ago

Was this helpful?

hashtag✔️ Preparation

hashtagFunctions and Flow

hashtag▶️ Start Browsing

hashtagAuthenticate

hashtagDiscover Instance

hashtagAllocate Capacity

hashtagAuto-Assigned Reservation

hashtagSearch and Browse

hashtagReserve Seats

hashtagConnect to Server

hashtagAbandon Server

hashtag🚀 Automated Scaling

hashtagMonitor Capacity

hashtagFixed Capacity

hashtagPre-Warm Standby

hashtagDeploy Servers

hashtagExample Policies

hashtag⚙️ Configuration

hashtag☁️ Hosting Cluster

hashtagPrivate Cluster Tiers

hashtag📗 API

hashtagPagination

hashtag🔖 Changelog

hashtagSemantic Versioning

✔️ Preparation

Functions and Flow

▶️ Start Browsing

Authenticate

Discover Instance

Allocate Capacity

Auto-Assigned Reservation

Search and Browse

Reserve Seats

Connect to Server

Abandon Server

🚀 Automated Scaling

Monitor Capacity

Fixed Capacity

Pre-Warm Standby

Deploy Servers

Example Policies

⚙️ Configuration

☁️ Hosting Cluster

Private Cluster Tiers

📗 API

Pagination

🔖 Changelog

Semantic Versioning