> 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/how-multiplayer-works.md).

# How multiplayer works

Several players can share one match. The Sandbox hosts that match on a dedicated server. You build the game in Sandbox Studio. The platform supplies the server, the session, and matchmaking.

The server keeps the shared outcome: health, score, whether an attack landed, whether a player was allowed to join. Each client shows a copy of that outcome and sends requests. A client can predict movement and play effects locally so controls feel immediate. Those local results do not decide the match.

{% hint style="info" %}
*NOTE: Switching on a multiplayer option does not make existing gameplay shared. The rules that affect every player have to run with the networking systems.*
{% endhint %}

## What the platform handles

|              | The platform handles                                           | You handle                                                             |
| ------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Servers      | Dedicated servers for published matches                        | Gameplay rules, scenes, and what the server is allowed to decide       |
| Sessions     | Hosting the match and connecting players who were placed in it | Spawning each player into a character they control                     |
| Matchmaking  | Queues that group players into a supported match               | A way to start matchmaking, and UI for progress and failure            |
| Shared state | Carrying server updates to connected clients                   | Which values are shared, and the server checks behind each action      |
| Chat         | Relaying session text between players in the match             | Whether chat stays on, join and leave notices, and any extra filtering |
| Testing      |                                                                | More than one client in the editor, then a published match             |

Local Play mode can run a server and several clients on your machine. That checks networking during development. It does not show that the project has been packaged, accepted into matchmaking, or started on a hosted server.

## Key terms

| Term                | Meaning                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Dedicated server    | The process that owns the match. Published games use servers The Sandbox hosts.                                                  |
| Client              | A player's game. It sends input and requests, and shows replicated results.                                                      |
| `GameMode`          | The class that owns match rules and the player lifecycle: who may join, and what happens when they do.                           |
| Pawn                | The character a player controls.                                                                                                 |
| Replicated property | A gameplay value the server updates and connected clients observe. Health, score, and a match timer are typical examples.        |
| RPC                 | A method call that crosses the network. A player action goes to the server as a request. The server tells clients about effects. |
| Authority           | The server's copy of shared gameplay. Clients do not award themselves score, damage, or items.                                   |
| Matchmaking         | The platform flow that places players into a hosted session. Published multiplayer games use it.                                 |
| Play mode           | Where you test. For multiplayer, Play mode needs more than one connected client.                                                 |

## What your agent already knows

Name multiplayer in the first prompt. Say how many players there are, whether they compete or cooperate, how a match starts, and which rules the server decides. Ask for local Play mode with more than one client, and for the project to be ready to publish through the platform.

The project includes these skills. There is nothing to install.

| Skill                 | What it gives your agent                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `genesys-multiplayer` | Architecture, authority, replication, RPCs, spawning, and sessions. Start here.                         |
| `genesys-movement`    | Character movement, prediction, and correction.                                                         |
| `genesys-physics`     | Physics that can take part in networked play, including rewind where the movement system needs history. |
| `genesys-ui-kit`      | HUDs, scoreboards, and chat presentation.                                                               |

The prompt and the checks are on [Create a multiplayer game](/multiplayer/create-a-multiplayer-game.md).

The match has to use a queue the platform already offers. The known ids are `solo-1v1`, `duo-2v2`, `squad-4v4`, and `ffa-8`. `listQueues()` reports how many players each queue takes. A custom player count is not a setting you can assume.

## What players see

One player starts matchmaking from your game. That can be a Play button, an object, or another entry you build. The platform searches for a match, then places them in a hosted session.

After they connect, the server spawns their character. They control that character. Other players in the session see it. Shared values, such as the score, update from the server so every client shows the same result.

Session chat is on for multiplayer clients. The panel sits at the bottom-left. Enter, or the Chat button, opens it. Enter or Send submits the line. Escape closes it without sending and releases the mouse. Click the game to capture the pointer again.

Set `chatEnabled = false` on the `GameMode` to turn chat off. Set `chatJoinLeaveNotices = false` to hide the joined and left lines. Override `filterChatMessage(senderClientId, text)` to rewrite a line, or return `null` to drop it. The relay runs on the dedicated server when chat is enabled. The sender name is the server's `PlayerInfo.playerName`, so a client cannot spoof it. Render that name, and the message, as text. The rule is in the [UI kit widget reference](/the-editor/game-ui-kit-widget-reference.md).

Use that built-in chat. A second chat built from RPCs does not get this relay or the server's sender name.

The client and the server have to be the same engine build, with the same replicated game data registered. A mismatch closes the connection. The close reasons are `protocol-version-mismatch` and `schema-hash-mismatch`.

## Practical guidance

* Build the first match with the agent. [Create a multiplayer game](/multiplayer/create-a-multiplayer-game.md)
* Keep score, health, and match end on the server. [Share state and actions](/multiplayer/share-state-and-actions.md)
* Move characters with `MovementPawn`. [Networked movement](/multiplayer/networked-movement.md)
* Send published players through matchmaking. [Add matchmaking](/multiplayer/add-matchmaking.md)
* Test with at least two clients before you treat the game as multiplayer. [Test multiplayer locally](/multiplayer/test-multiplayer-locally.md)
* Publish through the platform matchmaking path. [Publish a multiplayer game](/multiplayer/publish-a-multiplayer-game.md)
* Bring an existing single-player game across in the same order. [Convert a single-player game](/multiplayer/convert-a-single-player-game.md)
* Look up a class or decorator. [Multiplayer reference](/multiplayer/multiplayer-reference.md)
* Play the uploaded build with enough people for the queue you chose. Editor Play mode does not cover that test.

## Common mistakes

| Mistake                                                           | What to do instead                                                                                                       |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Treating a project switch as the whole multiplayer setup          | Use server-side rules, replicated values, and RPCs for anything every player must agree on.                              |
| Letting the client decide damage, score, or inventory             | The client sends the request. The server checks it and updates the shared value.                                         |
| Testing in one Play mode window                                   | Run more than one client and confirm each player controls a different character.                                         |
| Publishing a direct-connect URL for players                       | Published matches go through platform matchmaking and hosted servers.                                                    |
| Planning a custom lobby size, bot fill, or a public drop-in queue | Build around the queues the platform provides.                                                                           |
| Showing player names or chat with HTML                            | Use text setters. See the safe UI warning in the [UI kit widget reference](/the-editor/game-ui-kit-widget-reference.md). |
| Building a second chat from RPCs                                  | Use the built-in session chat. The dedicated server relays it, and the sender name is `PlayerInfo.playerName`.           |
| Shipping a client and a server from different builds              | Keep the same engine build and the same replicated game data. A mismatch closes the connection.                          |

*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/how-multiplayer-works.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.
