> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/multiplayer/add-matchmaking.md).

# Add matchmaking

Published multiplayer games place players through The Sandbox matchmaking service. You add the entry point and the status the player sees. The platform searches for a match and returns a server placement. Spawning after that connection is on [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md).

A direct server address is for a local editor test. Published play calls `gameLoop.findMatch`. That call polls the queue, then connects and acknowledges the placement. `connectToServer` on its own is not a second way to host a published game.

A known server URL skips matchmaking. Pass an options object with `transport`, `serverUrl`, and `joinParams`. A string URL is WebSocket. WebTransport needs `serverCertificateHashes`. Handshake, level load, and `PlayerSpawner` stay the same either way.

The dedicated server listens with `startServer`. Matchmaking does not replace that call or `GameMode`.

## Step 1: Pick the queue

Use a queue the platform already offers. The choice, and the player counts in the engine demo, are on [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md).

Name that queue in the prompt. A custom player count is not a matchmaking setting.

## Step 2: Ask your agent for an entry point

Matchmaking can start from a Play button, an object in the level, or a terminal. It does not have to be a main menu.

In your agent, ask:

```
Add a Play control that joins a supported matchmaking queue. Tell me which queue you used.

Use gameLoop.findMatch with a supported queue id. Show the ticket status while it runs.
If the status is REQUIRES_ACCEPTANCE, call gameLoop.acceptMatch(true) or acceptMatch(false) while findMatch is still running.
Do not call connectToServer for published play. findMatch connects when the ticket completes.

A finished ticket is not a spawned player yet.
```

Wait until the agent finishes.

## Step 3: Show every ticket status

`findMatch` reports these ticket statuses. Show a short line of copy for each one.

| Status                | What the player should see                                       |
| --------------------- | ---------------------------------------------------------------- |
| `QUEUED`              | They are in the queue                                            |
| `SEARCHING`           | The platform is looking for a match                              |
| `REQUIRES_ACCEPTANCE` | They need to accept or decline                                   |
| `PLACING`             | A match exists. Connection info may not be ready yet             |
| `COMPLETED`           | The placement is ready. `findMatch` connects and acknowledges it |
| `CANCELLED`           | The request was cancelled. The wait throws `MatchmakingError`    |
| `FAILED`              | Matchmaking failed. The wait throws `MatchmakingError`           |
| `TIMED_OUT`           | The request timed out. The wait throws `MatchmakingError`        |

While the status is `REQUIRES_ACCEPTANCE`, call `gameLoop.acceptMatch(true)` or `gameLoop.acceptMatch(false)`. The `findMatch` call is still running. Decline sends the ticket back to `SEARCHING`. Accept waits until every player in the match agrees.

`COMPLETED` means the placement is ready. `findMatch` connects and tells matchmaking the player arrived. The gameplay scene still has to load, and the server still has to spawn that player's character. If the socket connects and the acknowledgement fails, the player stays connected and the result includes `ackError`.

## Step 4: Check the placement

`findMatch` turns the placement into the connection. It can also take `skill`, along with `onStatus`. A WebSocket placement uses `ws://host:port`. A WebTransport placement uses the URL and certificate hashes in that payload.

`joinParams` on that placement include `sessionId` and `playerId`, plus `authToken` when the placement returned one. A direct `connectToServer` sends none of these. `GameMode.canPlayerJoin` is where that join is accepted or refused. When the server must reject guests, check those fields against the match this process was started for. A non-empty token is not proof the token was issued for this session. A missing acknowledgement can backfill the seat or fail it.

A new `ClientId` is assigned on every connection. To restore a player after a disconnect, store an `identityToken` on `PlayerInfo` and send the same token in `joinParams` on the next `connectToServer`. The engine does not store that token for you.

## Parties

A party enters the queue as one group so matchmaking does not split it across matches. The calls are on `gameLoop.matchmaking`:

1. `createParty` with the queue, a minimum, and a maximum.
2. `setReady(true)` for each member.
3. `startParty` when `autoStart` is false. It defaults to true, which queues the party once everyone is ready.
4. `followParty` on each member. They share that ticket. They do not each call `findMatch`.

Leave parties out of the first Play button. Add them after a solo queue connects and spawns.

## What You've Done

Players can ask for a match, see the ticket move through the statuses, and connect when a placement is ready. The server spawn that follows is on [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md).

*Checked against `@gnsx/genesys.js` 19.0.0-beta.456 on 16 October 2026.*


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://studio-docs.sandbox.game/multiplayer/add-matchmaking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
