LogoLogo
edgegap.comDashboard
  • 📘Learning Center
    • Getting Started
    • Unity Games
      • Getting Started - Servers
      • Developer Tools
    • Unreal Engine Games
      • Getting Started - Servers
      • Developer Tools
    • Matchmaking
      • Getting Started
      • Matchmaker In-Depth
      • Ping Beacons
    • Advanced Features
      • Apps and Versions
      • Deployments
      • Managed Clusters
  • API Reference
    • Dedicated Servers
    • Integration
    • Matchmaking
    • Peer to Peer
  • Release Notes
  • 📚Documentation
    • Sample Projects
      • Unity Netcodes
        • Unity NGO
        • Photon Fusion 1
        • Photon Fusion 2
        • Mirror
        • Mirror WebGL
        • Fishnet
        • Fishnet WebGL
        • Photon Bolt
      • Unreal Top-Down Sample
      • NuxtJS
      • Ruby On Rails
      • Unity Lobbies
      • Unity Matchmaker
    • Tools & Integrations
      • Container
        • What is Docker
        • Your First Docker
        • SSH in Your Container
        • External Registries
          • Docker Hub
          • AWS ECR
          • GCP GCR
          • Gitlab registry
      • Deploy from Nakama
      • EOS Lobby Integration
      • Switch From Gamelift
      • Switch From Multiplay
      • Playfab Bridge
    • Deployment
      • Endpoint Storage
        • How to Save Logs
        • Upload File to Deployment
      • Webhooks
    • Application
      • Command and Arguments
      • 1:1 Port Mapping
    • Session
      • How They Work
      • Application Version Configuration
      • Manage Request
      • Selectors Filtering
    • Fleet
      • Fleet Policy
      • Policy Filter
      • Linking Version
      • Fleet's Deployment
    • Container Registry
    • Distributed Relay
      • Matchmaker/Lobby
      • Relay Edgegap API
      • Transport Samples
    • Lobby
      • Lobby Service
      • Functions
    • Glossary
    • SLA Terms
Powered by GitBook
LogoLogo

Connect with Community

  • Discord
  • Linkedin
  • X

Read More

  • Release Notes
  • Blog
  • Enterprise
  • Legal
  • edgegap.com

© 2025 Edgegap

On this page
  • ✔️ Preparation
  • Matchmaking Architecture
  • 🍀 Simple Example
  • 1. Set Up on Free Tier
  • 2. Explore Configuration
  • 3. Review Instance Details
  • 4. Test Tickets API
  • 5. Game Integration
  • 🏁 Advanced Example
  • 🎾 Custom Lobby
  • 🥛 Backfill Showcase
  • ⚔️ Competitive Games
  • 🤝 Cooperative Games
  • 🎈 Social Games

Was this helpful?

  1. Learning Center
  2. Matchmaking

Getting Started

PreviousMatchmakingNextMatchmaker In-Depth

Last updated 9 days ago

Was this helpful?

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

See Matchmaker In-Depth for detailed explanations and more tips on customization.

Our matchmaking philosophy is driven by player perspective, with core principles of matchmaking:

  • maximizing match fill rate and social integration (friends and lobbies),

  • fast matches and high match quality controls (low latency, similar preferences),

  • high service availability, observability, analytics, and user-friendly error handling.

✔️ Preparation

Testing our Matchmaker 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:

  • ,

  • uploaded and configured your server application on Edgegap,

    • Getting Started - Servers (Unity),

    • Getting Started - Servers (Unreal Engine),

  • successfully connected from a game client to your server on Edgegap.

Matchmaking Architecture

Understanding matchmaking architecture is easy:

Our matchmaker reference architecture involves several flows of data:

  • Deployments API is used to deploy, scale, and manage your Dedicated Servers by Matchmaker.

    • Edgegap is not involved in this communication.

This guide will focus on Matchmaking API and Backfill API.

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

🍀 Simple Example

Start with a simple example and test the core matchmaking player flow:

1. Set Up on Free Tier

☑️ Click on Create Matchmaker first, then input:

  • matchmaker name - for your own reference, e.g. quickstart-dev ,

  • upload our Simple Example JSON configuration.

🍀 Simple Example (Minimal Recommended Configuration):

Make sure to change the application name and version to match your Apps and Versions.

{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "simple-example": {
      "application": {
        "name": "",
        "version": ""
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 2,
              "max_team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 100,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

Troubleshooting and FAQ:

☑️ If no validation errors appear, hit Create and Start and wait for the process to complete. This will result in a new free cluster starting, with your Simple Example matchmaker.

✅ You may now proceed to the next step.

2. Explore Configuration

  • 🔥 major versions include breaking changes and require integration review,

  • 🌟 minor versions include substantial backwards-compatible improvements,

  • 🩹 patch versions include bug fixes and minor improvements.

To ensure that unexpected client crashes or abandoned tickets do not linger and take up your matchmaker resources, tickets will be cancelled after ticket_expiration_period causing their status to change to CANCELLED and then permanently deleted after ticket_removal_period .

  • name of your choosing, e.g. - match size,

  • rule type, also known as operator, e.g. - player_count,

  • and lastly operator attributes, e.g. team_count or max_team_size.

Player Count Rule

This is a special rule defining how many players need to match to initiate assignment:

  • team_count refers to number of teams, 1 team may be used for cooperative or free-for-all modes,

  • min_team_size refers to the minimum number of players per team.

  • max_team_size refers to the maximum number of players per team.

Our simple example demonstrates a cooperative game with 2 players.

Player Count rule is required and may only be defined once in your initial configuration rules.

Latencies Rule

Use this rule to provide the lowest possible ping for all players.

Latencies rule may only be defined once in your initial configuration rules.

✅ You may now proceed to the next step.

3. Review Instance Details

☑️ Review details of your new matchmaker in our dashboard once it’s initialized:

  • Status indicates service health, may be ONLINE, OFFLINE, or ERROR.

  • Identifier helps Edgegap staff find your matchmaker quickly if you need help troubleshooting.

  • Started at can be useful to track down the latest update time.

  • API URL will be used by Game Clients and Game Servers to communicate with your matchmaker.

  • Swagger URL is a handy openAPI specification GUI we provide to explore API schema.

  • Auth Token is a unique secret token used by Game Clients and Game Server for authentication.

Edgegap staff will never ask for your tokens. Regenerate your token if you suspect a security breach.

To test your new matchmaker, you will need the Swagger URL, API URL and Auth Token.

✅ You may now proceed to the next step.

To update your matchmaker rules in development, edit your configuration and restart it.

4. Test Tickets API

Please wait for up to 5 minutes after starting your matchmaker to allow DNS propagation to complete.

☑️ First, open your Swagger URL to inspect your openAPI schema in the swagger GUI:

☑️ Click on Authorize 🔒, paste your Auth Token, and confirm by clicking on Authorize.

☑️ Scroll down to Ticket API - POST /tickets, expand and click Try it out.

  • attributes include values for your matchmaker rules, in this case for the latencies rule,

    • rule player_count is the only rule which doesn’t require any attributes in player tickets.

☑️ Click Execute and review the response to your player ticket request:

  • id is your unique matchmaking ticket ID, save this to check on your ticket later,

  • group_id is a unique group ID issued to every ticket, a solo player is represented as a group of 1,

    • each team can contain multiple groups, not exceeding the configured team size,

  • player_ip is the resolved public IP address of the player, regardless of the identification method,

  • assignment is set to null to indicate the ticket has not been matched or assigned to a server,

  • created_at provides information about when the player ticket was created for game UI usage,

  • status indicates the current status of the ticket, all tickets start in SEARCHING ,

☑️ Create a second ticket by hitting Execute again, so our two players match and a server is started.

☑️ Collapse POST /tickets and open GET /tickets/{ticketId}, then click Try it out.

☑️ Input ticket ID from the response in previous step and click Execute.

☑️ Review the updated assignment for your player ticket:

  • status changed to MATCH_FOUND first, while keeping assignment set to null to indicate players have matched and a server is being assigned,

☑️ Click Execute again to check on your ticket, and review the updated assignment for your ticket:

  • status changed to HOST_ASSIGNED with assignment containing details of the assigned server.

Troubleshooting & FAQ

My ticket is stuck in SEARCHING .

  • Please verify that you’ve created enough tickets with overlapping criteria adhering to your configuration.


My ticket is stuck switching between MATCH_FOUND and TEAM_FOUND repeatedly.

  • Free Tier accounts are limited to 1 deployment at a time. Please consider upgrading or stop your current deployment to start a new one.


My ticket goes straight to CANCELLED.

  • Your ticket reached it’s expiration. Recreate a new ticket or increase the expiration period in your configuration for testing purposes.


I receive HTTP 404 Not Found when checking on my ticket.

  • Your ticket was removed either by a DELETE request, or by reaching it’s removal period (starts after ticket is expired, defined in your configuration). Recreate a new ticket or increase the expiration/removal periods in your configuration for testing purposes.

  • notice each deployment is tagged with all ticket IDs and profile for added traceability.

☑️ Try connecting from your game client to the assigned server.

The external port of your Deployment on Edgegap cloud will be chosen at random, so that a potential attacker (hacker) is slowed down and detected before they can cause damage.

☑️ Once you verify you’re able to connect to your Deployment without issues and are done testing, Stop your Deployment to free up capacity in your account for the next build.

✅ You may now proceed to the next step.

Find the openAPI specification for testing at {matchmaker-url}/swagger/v1/swagger.json.

5. Game Integration

As indicated by Matchmaking Architecture above, Matchmaker integrates:

  • with Dedicated Server, to:

    • process player preferences passed through their tickets,

☑️ In Game Client, ensure you’re handling non-retryable errors:

  • HTTP 404 Not Found - ticket has been deleted,

  • HTTP 500 Internal Server Error - temporary service outage.

☑️ In Game Server, process player preferences and initial server context. API usage is not required:

☑️ Once players connect, Game Server and Game Clients start a loading scene to perform synchronization steps (e.g. selecting and loading a map/scene/level). We recommend a full fledged 3D scene, a lobby-like social UI, or a loading screen with a progress bar, to indicate initialization is progressing.

☑️ Once Game Clients fully loaded, players load/travel to the main gameplay scene.

  • no players join the match,

  • all players have left the match,

  • match concludes correctly.

🙌 Congratulations, you’ve completed Matchmaking integration! To learn more, keep reading.

🏁 Advanced Example

🎾 Custom Lobby

Add custom-lobby-example profile in your existing matchmaker to support custom lobbies.

🥛 Backfill Showcase

⚔️ Competitive Games

Competitive games focus on players competing against each other to achieve victory, whether as individuals (free for all) or teams. Matchmaking is crucial to ensure fair and balanced matches by pairing players or teams of similar skill levels. Maintain the pace of the game by quickly finding opponents with low latency to ensure fair competition.

You may define multiple teams with 1 or more players each, for example:

  • 1v1 fighting game, with team count of 2 and team size of 1, require 2 players per game.

  • 10 player free-for-all, with team count of 1 and team size of 10, require 10 players per game.

  • 20x3 battle royale, with team count of 20 and team size of 3, require 60 players per game.

  • For all matches:

    • slowly relax latency restrictions over time to find more players,

  • For casual matches:

    • omit rank restrictions to maximize match speed and match fill rate,

    • let players provide their map preferences to find a map suitable for everyone,

    • specify backfill group size to replace leavers without exceeding team sizes,

    • remove latency limitations to guarantee a match after 3 minutes (180s) of queue time.

  • For competitive matches:

    • restrict rank to only allow opponents with similar skill level,

    • use rank-up or rank-down ranks to match players at the league's rank extremes.

  • For the top 1% of high skill matches (challengers):

    • use numerical skill ratings (ELO) to gain fine control over skill distribution in matches,

    • wait longer before relaxing latency requirements due to lower amount of players.

Using multiple profiles to separate casual game modes, competitive game modes, and top-tier challenger players allows you to customize rules and expansions for each type of player separately.

🤝 Cooperative Games

With team count 1 and maximum team size of 4, require up to 4 players per match.

  • start with minimum of 4 players to keep players in queue and maximize match fill rate,

  • let players choose a particular game difficulty to suit everybody’s skill level,

  • let players provide their map preferences to find a map suitable for everyone,

  • restrict player level difference to require similar degree of game progression,

  • specify backfill group size to replace leavers without exceeding server capacity,

  • use moderation flags to separate low-karma players and cheaters from general population,

  • relax latency restrictions over time to find more players,

  • increase allowed player level difference to find more players,

  • decrease minimum team size to require less players and start the game sooner,

  • set minimum team size to 1 to launch the game solo after 150s of queue time

🎈 Social Games

With team count 1 (free for all) and maximum team size of 50, require up to 50 players per match.

  • let players provide their game mode preferences and find a mode suitable for everyone,

  • specify backfill group size to replace leavers without exceeding server capacity,

  • use moderation flags to separate low-karma players and cheaters from general population,

  • relax latency restrictions over time to find more players,

  • slowly decrease minimum team size to require less players and start the game sooner,

  • set minimum team size to 1 to launch the game solo after 150s of queue time.

is used by Game Clients to communicate with Matchmaker:

to check on matchmaking service status,

and to manage ,

optionally to retrieve Ping Beacons.

are used to communicate between Game Clients and Dedicated Servers:

Optionally, is used by Dedicated Servers to replace or add more players.

creating the matchmaker instance on the shared ,

defining rules and settings in your matchmaker ,

testing player flow and managing with .

☑️ and open the .

As we release updates to Matchmaker, each new version uses to clearly communicate the impact of changes by interpreting format major.minor.patch:

Use to better understand and debug possible matchmaking flows while in development. We recommend disabling inspect API for your live matchmaker.

Some . We attempt to resolve this by retrying deployment up to max_deployment_retry_count times automatically (without client confirmation).

The core of our matchmaking logic is configured in . Each profile is a completely isolated matchmaking queue, pointing to with pre-defined amount of required CPU and memory (RAM) resources.

in the initial rule set must be met for players to be grouped together, each defined by three properties:

Size corresponds to one of our .

See for live games and zero-downtime updates.

☑️ Preview your request:

notice player_ip set to null - this will cause Matchmaker to use the IP address automatically added to your request (see for alternatives),

profile refers to your ,

profile confirming the choice of ,

see for matchmaking with your friends or lobbies,

team_id is a unique team ID issued to every ticket once reaches TEAM_FOUND status,

see for grouping up players in multiple teams,

see for details.

☑️ :

If you’re experiencing high latency, your netcode integration may be configured to simulate network latency. Disable VPN when testing for more realistic conditions and receive a .

with Game Client, to manage ,

optionally to support to add or replace players after starting.

☑️ In Game Client, we recommend providing ticket status updates throughout to players using in-game UI for best player experience. See:

See for additional information regarding Matchmaker service health.

Read to retrieve initial players’ matchmaking data.

Read for version parameters, settings, and secrets.

Read for deployment information, IP, location, etc...

☑️ Optionally, Game Server may create and manage and player capacity (add or replace players who leave).

☑️ Ensure your properly using , if:

A full fledged configuration utilizing all matchmaking features including , , with may look like this:

Custom lobbies (private lobbies, sandbox levels) are a very popular option for couch multiplayer and testing new features in games before they enter main game modes. These games typically require the least amount of restrictions, but aim to ensure that players can .

may use Custom Lobby profiles to support inviting friends reliably.

Building on 🍀 Simple Example, this configuration showcases with .

Define multiple for game mode specific rules and settings, and .

restrict to prevent matching players far away,

for pre-made parties and prevent exceeding team sizes,

allocate more CPU or memory with different for specific profiles,

Cooperative games require players to work together as a team towards a common goal, or AI opponent. Efficient matchmaking helps align players with similar preferences, gameplay habits, replaces players who leave, and improves to provide a responsive player experience.

Define multiple for game modes specific rules and settings:

restrict to prevent matching players far away,

for pre-made parties and to fill teams without exceeding server capacity,

allocate more CPU or memory using different for other profiles.

Start with the ideal conditions, and to ensure quick matches:

server may fill empty slots with AI teammates, or use to add players later,

Social games focus on building connections and relationships between players through collaboration, communication, and shared experience. Efficient matchmaking supports high number of players, maximizes match fill rate, aligns player preferences and gameplay habits, replaces players who leave, and ensures high to provide a responsive player experience.

Define for game modes specific rules and settings:

restrict to prevent matching players far away,

for pre-made lobbies or to fill teams without exceeding server capacity,

allocate more CPU or memory using different for other profiles.

Start with the ideal conditions, and to ensure quick matches:

server may fill empty slots with AI players, or use to add players later,

📘
Netcode Transports
Register for your free Edgegap account
Matchmaker dashboard page
Pricing Tiers
Inspect your new deployment in our dashboard
deployment will be stopped
🟢 Connection Quality
🟢 Connection Quality
matchmaking latency
matchmaking latency
matchmaking latency
🏷️ App Versions
🏷️ App Versions
🏷️ App Versions
Injected Environment Variables (App Versions)
🏷️ App Versions
  • Unreal Engine :

    • (free for Personal use),

    • and customize for your needs.

  • Unity by Edgegap:

    • ,

    • and customize for your needs,

install from Fab Marketplace
download example project
install package using Unity Package Manager for free
import simple example
The application configuration is not valid for profile XYZ.
  • We couldn’t find your Apps and Versions, please verify application values.

Docker image for '2024.01.30-16.23.00-UTC' is not cached.

to unlock .

  • 4GB+ server images may take longer to deploy, resulting in . Consider optimizing your server image size ( / ).

  • You may proceed anyway, though we recommend testing your deployment time.

🌟 Upgrade to Pay as You Go tier

latencies is a special rule matching players within a specific difference range in ping values:

  • this presents a “soft” solution to splitting your player base, enabling matching with neighboring regions, especially improving match speed for less populated regions,

  • max_latency should be specified to discard locations above a given threshold,

Our example beacons rule above with "difference": 100, "max_latency": 200 initially:

Alice and Bob will match:

  • Tokyo is discarded (>200 ms),

  • latency for Chicago within 100 ms absolute difference.

Beacon City
Match
abs(A - B) [ms]
Alice [ms]
Bob [ms]

Chicago

75.0

12.3

87.3

Los Angeles

113.2

145.6

32.4

Tokyo

n/a

n/a

233.2

253.2

Alice and Charlie will never match:

  • no beacons have < 200 ms latency for both players,

  • Alice lives in North America - Illinois,

  • Charlie lives in Asia - Japan.

Beacon City
Match
abs(A - B) [ms]
Alice [ms]
Charlie [ms]

Chicago

n/a

n/a

12.3

215.6

Los Angeles

n/a

n/a

145.6

238.3

Tokyo

n/a

n/a

233.2

24.2

Use or to get variable values.

✅
❌
✅
❌
❌
❌
❌
❌
❌
❌
GetEnvironmentVariable in C#
GetEnvironmentVariable in C++
🏁 Advanced Example (Complete Example Configuration)
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
    "advanced-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 125
            }
          },
          "elo_rating": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 50
            }
          },
          "selected_game_mode": {
            "type": "string_equality"
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "elo_rating": {
              "max_difference": 150
            },
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          },
          "60": {
            "elo_rating": {
              "max_difference": 200
            }
          },
          "180": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            },
            "beacons": {
              "difference": 99999,
              "max_latency": 99999
            }
          }
        }
      }
    }
  }
}
🎾 Custom Lobby Example
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "custom-lobby-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "lobby_id": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "10": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            }
          }
        }
      }
    }
  }
}
Backfill Configuration Example
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "backfill-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 100,
              "max_latency": 200
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {}
      }
    }
  }
}
🥛
⚔️ Competitive Game Example
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "casual-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          },
          "180": {
            "beacons": {
              "difference": 99999,
              "max_latency": 99999
            }
          }
        }
      }
    },
    "competitive-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "versus_ranks": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "120": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          }
        }
      }
    },
    "challenger-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "elo_rating": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 50
            }
          }
        },
        "expansions": {
          "120": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          }
        }
      }
    }
  }
}
🎈 Social Game Example
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "social-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "attributes": {
              "team_count": 1,
              "min_team_size": 50,
              "max_team_size": 50
            },
            "type": "player_count"
          },
          "beacons": {
            "attributes": {
              "difference": 125,
              "max_latency": 150
            },
            "type": "latencies"
          },
          "selected_mode": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "moderation_flags": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "15": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            },
            "match_size": {
              "team_count": 1,
              "min_team_size": 20,
              "max_team_size": 50
            }
          },
          "30": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 10,
              "max_team_size": 50
            }
          },
          "150": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 50
            }
          }
        }
      }
    }
  }
}
⚡ Edgegap Integration Kit by Betide Studio
⭐ Matchmaking SDK
📗 API
/monitor
/tickets
/group-tickets
🎫 Player Tickets
/locations/beacons
Backfill
☁️ Hosting Cluster
📏 Configuration
🎫 Player Tickets
📗 API
Semantic Versioning
#inspect-api
Profiles
Rules
⏩ Rolling Updates
🎫 Player Tickets
Server to Server
Profiles
Profiles
Join as Group
Matchmaking Process
Teams
Matchmaking Process
🎫 Player Tickets
Backfill
Matchmaking Process
/monitor
Backfill
Profiles
Application and Versions
Rules
Rule Expansion
Join as Group
Backfill
Backfill
Join as Group
Join as Group
Profiles
Join as Group
Backfill
Profiles
Join as Group
Backfill
Injected Environment Variables (Matchmaker)
Profiles
expand as needed
expand restrictions
expand restrictions
Injected Environment Variables

To initiate successful backfill:

    • adding backfill_group_size to tickets, listing group sizes up to available team capacity.

    • or mock tickets data fabricated to match specific (real) player tickets,

    • including value "1" if the player is matchmaking alone, or number of group members,

    • additionally including value "new" if players wish to allow starting new games,

    • or omitting value "new" if players only wish to join a game in progress (backfill).

To create a Backfill-only profile, set min_team_size to 999,999 in your matchmaking profile.

Backfills ignore player_count rule, and always match a single group. Values in backfill_group_size dictate how many players may be matched. Creating one backfill per team ensures team round-robin strategy, with server creating new backfills to fill remaining seats as needed.

🥛 Backfill Example (Backfill Showcase)
🥛 Backfill Assignment Example (Backfill Showcase)

Once game server initialization concludes, your server should continually:

  • Start idle disconnect countdown for each new player (recommend up to 3 min):

    1. Start a loading scene/level while players connect - a full fledged 3D scene, a lobby-like social UI, or a loading screen with a progress bar, to indicate initialization is progressing.

    2. Trigger loading for new players on server initialization.

    3. Trigger loading for players replacing leavers (joining via Backfills).

  • Keep track of new player connections or existing players leaving over time:

    1. Listen to custom client RPCs containing new player ticket IDs (initial or backfilled), to pair tickets to netcode entities/actors.

    2. Create new Backfills for unused player capacity (leavers).

    3. Renew expired Backfills, which are deleted after ticket_expiration_period.

4. Deployment Error

Use to replace Seat/Match sessions. Matchmaker only supports Default session type.

Server creates for each team separately, with values:

real assignment data retrieved from (deployment).

real tickets data retrieved from (matchmaker),

Clients create or with backfill_group_size array:

proceeds to assignment and clients connect to the server.

Read and verify assigned_ticket player data retrieved from .

Delete any leftover Backfills once the :

Unity - callback,

Unreal Engine - or callback.

See and for player connection monitoring.

understood Edgegap’s “just in time” deployment model
deployments may result in Errors
low-latency deployment
Injected Environment Variables (Deployment)
{
  "profile": "backfill-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "public_ip": "192.168.2.14",
      "ports": {
        "game": {
          "internal": 7777,
          "external": 56890,
          "link": "cd28e6c66554.pr.edgegap.net:56890",
          "protocol": "UDP"
        },
        "web": {
          "internal": 22,
          "external": 57440,
          "link": "cd28e6c66554.pr.edgegap.net:57440",
          "protocol": "TCP"
        },
        "server": {
          "internal": 80,
          "external": 50110,
          "link": "cd28e6c66554.pr.edgegap.net:50110",
          "protocol": "TCP"
        }
      },
      "location": {
        "city": "Montreal",
        "country": "Canada",
        "continent": "North America",
        "administrative_division": "Quebec",
        "timezone": "America/Toronto"
      }
    }
  },
  "tickets": {
    "c3d057h5h6f7j889fk43": {
      "player_ip": "174.25.48.238",
      "attributes": {
        "beacons": {
          "New York": 12.2,
          "Los Angeles": 45.3,
          "Paris": 78.3
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "192bb97e-7fd6-4d86-8ce4-61c53c9fef16",
      "id": "c3d057h5h6f7j889fk43",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqg0bg9583s738h9dkf6": {
      "player_ip": "217.34.85.142",
      "attributes": {
        "beacons": {
          "New York": 21.0,
          "Los Angeles": 30.2,
          "Paris": 101.1
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": null
}
{
  "profile": "backfill-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "public_ip": "192.168.2.14",
      "ports": {
        "game": {
          "internal": 7777,
          "external": 56890,
          "link": "cd28e6c66554.pr.edgegap.net:56890",
          "protocol": "UDP"
        },
        "web": {
          "internal": 22,
          "external": 57440,
          "link": "cd28e6c66554.pr.edgegap.net:57440",
          "protocol": "TCP"
        },
        "server": {
          "internal": 80,
          "external": 50110,
          "link": "cd28e6c66554.pr.edgegap.net:50110",
          "protocol": "TCP"
        }
      },
      "location": {
        "city": "Montreal",
        "country": "Canada",
        "continent": "North America",
        "administrative_division": "Quebec",
        "timezone": "America/Toronto"
      }
    }
  },
  "tickets": {
    "c3d057h5h6f7j889fk43": {
      "player_ip": "174.25.48.238",
      "attributes": {
        "beacons": {
          "New York": 12.2,
          "Los Angeles": 45.3,
          "Paris": 78.3
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "192bb97e-7fd6-4d86-8ce4-61c53c9fef16",
      "id": "c3d057h5h6f7j889fk43",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqg0bg9583s738h9dkf6": {
      "player_ip": "217.34.85.142",
      "attributes": {
        "beacons": {
          "New York": 21.0,
          "Los Angeles": 30.2,
          "Paris": 101.1
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": {
    "profile": "backfill-example",
    "player_ip": "244.13.201.244",
    "attributes": {
      "beacons": {
        "New York": 30.2,
        "Los Angeles": 10.5,
        "Paris": 123.9
      },
      "backfill_group_size": [
        "new",
        "1"
      ]
    },
    "id": "cqg0bg550h7uujd77khg",
    "group_id": "e0cf41c0-f88f-456e-a032-03b1d6821a9a",
    "created_at": "2024-08-20T13:38:08.251393+00:00",
    "status": "HOST_ASSIGNED"
  }
}
Backfill
/backfills
Injected Environment Variables
/tickets
/group-tickets
Matchmaking Process
Injected Environment Variables
5. Deployment Stopped
#backfills
🤝 Cooperative Game Example
{
  "version": "3.0.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "cooperative-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "selected_difficulty": {
            "type": "string_equality"
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "player_level": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 10
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "moderation_flags": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            },
            "player_level": {
              "max_difference": 20
            }
          },
          "60": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 2,
              "max_team_size": 4
            }
          },
          "150": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            }
          }
        }
      }
    }
  }
}
OnApplicationQuit
OnWorldDestroyed
PreExit
Mirror Seat Management
FishNet Seat Management
instant deployments with Caching
Unreal Engine
Unity