Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

๐Ÿ‘ฅ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.

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.

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.

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.

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

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.

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.

Last updated

Was this helpful?