> 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

### 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;
}
```

{% hint style="warning" %}
These are **server-side** APIs. Call them from `Game.is_server()` code.
{% endhint %}

### Example: send a player to another game

```go
GAME_ID_2V2 :: "your_game_id_here";

send_to_2v2_game :: proc(player: Player) {
    if !Game.is_server() return;

    Server.transfer_player_to_game(player, GAME_ID_2V2);
}
```

{% hint style="info" %}
There is currently no way to pass additional information when transfering 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 dedicate 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.allout.game/core-engine-concepts/matchmaking-hub-games.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.