> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/core-engine-concepts/matchmaking-hub-games.md).

# Matchmaking/Hub Games

We provide APIs/settings to manage how we matchmake players to servers in your game, and allow you to route players to new servers to support Hub game scenarios.

### Matchmaking Preferences

**Fill Mode:**

All Out hosts servers across the globe to deliver a low latency experience to players, however, if your game is just getting started you may want to compromise on latency to ensure players can play together in the same server. The fill modes are documented on the main page of the Creator portal and can be changed at any time.

**Instance Priority + Require High Priority Mode**

There is a special matchmaking mode that allows you to avoid sending players to specific servers with code.

Games can set a "priority" level for each instance based on round status, player count, etc using `Server.set_matchmaking_priority(priority)`.

Optionally you can request to enable "Require High Priority" mode for your game, which will **only** route players to instances with priority set to zero and will spin up **new servers** if there aren't any.

This can be useful if you have a round-based game where you don't want new players joining into already running games.

{% hint style="info" %}
This feature is available by request only since if your instances never/rarely get set to priority number 0, it will spin up a massive number of servers! Please [contact us](/going-all-out/developer-support.md)!
{% endhint %}

### Hub Games

Hub games are a common pattern that allows players to meet up and queue for a round-based game together. Examples would include:

* A lobby for Red Sun that lets players queue to play together and buy upgrades while waiting
* The Bed Wars hub that allows you select between gamemodes (like classes/vs classic)

### API Reference

```go
Server :: struct {
    // Transfer a player to another game (hub -> match, match -> hub, etc).
    transfer_player_to_game :: proc(player: Player, game_id: string);

    // Set matchmaking priority for this instance (0 = highest priority).
    set_matchmaking_priority :: proc(priority: int);

    // Kick a player from the server.
    kick_player :: proc(player: Player, reason: string = "Kicked.");

    // Queue system for custom matchmaking. These APIs are currently deprecated but may return. Prefer the transfer_player_to_game API.
    queue_add_player           :: proc(queue: string, player: Player);
    queue_remove_player        :: proc(queue: string, player: Player);
    queue_set_server_available :: proc(queue: string, available: bool);

    // Server identity.
    get_id :: proc() -> string;
    get_private_server_host_id :: proc() -> (string, bool);
}
```

`transfer_player_to_game`, `set_matchmaking_priority`, and `kick_player` take effect on the server. Call them from the normal shared gameplay path; the matching client call has no effect.

The two ID queries only return useful data on the server. Do not branch shared predicted gameplay on their results.

### Example: send a player to another game

```go
GAME_ID_2V2 :: "your_game_id_here";

send_to_2v2_game :: proc(player: Player) {
    Server.transfer_player_to_game(player, GAME_ID_2V2);
}
```

{% hint style="info" %}
There is currently no way to pass additional information when transferring a player to a new game, nor is there a way to dynamically configure servers at startup. If you'd like to have different modes (e.g. 1v1 vs 2v2) you'll need to create dedicated games and link them with the game parenting system.
{% endhint %}

{% hint style="info" %}
We recommend enabling [Cross-Game Products/Data](/data-and-persistence/cross-game-products-data.md) when using teleportation/hub APIs to ensure player purchases and save data can be easily reused between the two.
{% endhint %}