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

# Multiplayer reference

Names you meet while building a multiplayer game, checked in `@gnsx/genesys.js` 19.0.0-beta.456. How to use them is on the linked pages. Import the package as `ENGINE`, the same way as [Project code fundamentals](https://studio-docs.sandbox.game/best-practices/project-code-fundamentals.md).

## Which process is running

| Name                             | What it does                                             | Notes                                                      |
| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| `NetRuntime.isDedicatedServer()` | True on the dedicated server                             | Same check as `isHeadless()`                               |
| `NetRuntime.isClient()`          | True on a connected client                               | A browser that has connected to a remote server            |
| `NetRuntime.isStandalone()`      | True when the game is running on its own, with no server | An uninitialized browser starts here                       |
| `NetRuntime.isServer()`          | True for standalone and for the dedicated server         | False only for a connected client. Usual authority guard   |
| `NetRuntime.isHeadless()`        | True when the process is the dedicated server            | An uninitialized Node.js process starts here               |
| `NetRuntime.getType()`           | `Standalone`, `Client`, or `DedicatedServer`             | Read it in `beginPlay` or later, not in a node constructor |

`GameLoop` sets `NetRuntime` before `beginPlay`. Do not read it in a node constructor.

## Spawning players and objects

The scene setup is on [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md).

| Name                           | What it does                                                     | Notes                                                                                                                          |
| ------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GameMode`                     | Match rules and the player lifecycle                             | Constructed on clients too, when the world has a game-mode class. Run match rules, spawning, and `restartPlayer` on the server |
| `GameMode.getPlayerSpawner()`  | Returns the level's `PlayerSpawner`                              | Throws when the level has none                                                                                                 |
| `GameMode.canPlayerJoin`       | Accepts or refuses the join at handshake                         | Runs before the level loads. Return `{ allowed: false, reason }`. Do not spawn gameplay nodes here                             |
| `GameMode.canPlayerRejoin`     | Accepts or refuses a returning player                            | Runs at handshake, with `canPlayerJoin`                                                                                        |
| `GameSessionInfo`              | Replicated match fields                                          | Spawned through `PlayerSpawner`                                                                                                |
| `PlayerSpawner`                | Spawns the controller, Pawn, `PlayerInfo`, and `GameSessionInfo` | One in every multiplayer level                                                                                                 |
| `PlayerStart`                  | Marks where a Pawn appears                                       | `GameMode` picks an unoccupied one                                                                                             |
| `PlayerInfo`                   | The joining player's record                                      | Created before the controller and Pawn. Holds `playerName` and, for rejoin, `identityToken`                                    |
| `MultiplayerSpawner`           | Spawns objects during play so other clients get them             | Scene-placed. `world.add` on the server does not replicate                                                                     |
| `MultiplayerSpawner.despawn()` | Removes a spawned object by its spawn id                         | Server only. `destroy()` is the other removal                                                                                  |
| `@ENGINE.SpawnMethod()`        | Marks a method the spawner can call to build an object           | `audience: 'owner'` takes the owner `ClientId` first and strips it. An omitted audience is every connected client              |

## Shared state

Property and RPC setup is on [Share state and actions](https://studio-docs.sandbox.game/multiplayer/share-state-and-actions.md).

| Name                                    | What it does                                                 | Notes                                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `isRoot`                                | Marks the root of an entity                                  | Set this with `replicated` on the root. A replicated entity stops at a nested root                                    |
| `replicated`                            | On an `isRoot` node, creates that entity's replication info  | Changing it after registration throws. Setting it on a client has no effect. Game code does not call `registerEntity` |
| `ensureReplicationInfo()`               | Returns the replication info for an `isRoot` replicated node | Holds the `NetId`, owner, and role                                                                                    |
| `NetId`                                 | Server-assigned id for a replicated entity                   | `uint32`. `0` is invalid                                                                                              |
| `ClientId`                              | Id assigned at handshake                                     | `uint16`. `0` is the server, or no owner. A new id is assigned on every connection                                    |
| `netOwningClientId`                     | Owner of the replicated entity                               | `0` means server-owned                                                                                                |
| `@ENGINE.property({ replicate: true })` | Replicates one field from the server to clients              | A client write stays local. Optional `net.netType`, such as `'uint16'`                                                |
| `net.replicateTo`                       | Who receives a replicated field                              | `'all'`, `'owner'`, or `'non-owner'`. There is no per-tick distance check                                             |
| `onRepScore()`                          | Called on the receiver when `score` arrives                  | The suffix is the property name, capitalized                                                                          |
| `hasAuthority()`                        | True on the authority copy                                   | Also true when the node has no replication info                                                                       |
| `isLocalAutonomousProxy()`              | True on the character this client controls                   |                                                                                                                       |
| `isSimulatedProxy()`                    | True on a character or object someone else controls          |                                                                                                                       |
| `isOwnedByLocalClient()`                | True when this client owns the entity                        |                                                                                                                       |

## Remote calls

| Name                     | What it does                             | Notes                                                                                    |
| ------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| `@ENGINE.ServerRPC()`    | Owning client asks the server            | Default `{ reliable: true }`. Also runs locally when called with authority on the server |
| `@ENGINE.ClientRPC()`    | Server tells the owning client           | No owner means the call is not sent                                                      |
| `@ENGINE.MulticastRPC()` | Runs on the server, then on every client | Not an authority guard. A direct call on a client runs locally and sends nothing         |
| `@ENGINE.RemoteRPC()`    | Either side calls the other side only    | The method does not run on the caller                                                    |

Pass `{ reliable: false }` when a lost call is acceptable. On WebSocket, every frame is ordered and reliable. On WebTransport, unreliable RPCs and replication travel as datagrams. The default send rate for replication is 30 Hz. A destroyed entity is a tombstone. A late joiner replays the current spawner journal.

## Movement

Prediction and rewind are on [Networked movement](https://studio-docs.sandbox.game/multiplayer/networked-movement.md).

| Name                                        | What it does                                                | Notes                                                                                                                                           |
| ------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `MovementPawn`                              | Pawn with networked movement                                | Owns a movement node                                                                                                                            |
| `BasePawnMovementNode`                      | Movement node that predicts and corrects                    |                                                                                                                                                 |
| `NetMovementPredictor`                      | Stores recent inputs for that correction                    | Created with `MovementPawn`                                                                                                                     |
| `NetPredictionManager.initialize(world)`    | Starts rewind for this world                                | Call from `GameMode.onBeforeBeginPlay`, before rewindable nodes begin play. Calling it again on the same world does not create a second manager |
| `NetPredictionManager.shutdown(world)`      | Stops it                                                    | Call from `GameMode.onAfterEndPlay`                                                                                                             |
| `NetPredictionManager.getGameTimeMs(world)` | Shared clock for snapshots and timestamps                   | Local UI clocks can keep using local game time                                                                                                  |
| `IRewindable`                               | A node whose earlier pose can affect a predicted simulation | Register it. Leave static geometry and cosmetic meshes unregistered                                                                             |
| `NetRewindablePhysicsProp`                  | Physics prop that records history for rewind                | Register the manager first                                                                                                                      |

## Matchmaking and connection

The flow is on [Add matchmaking](https://studio-docs.sandbox.game/multiplayer/add-matchmaking.md).

| Name                                                    | What it does                                           | Notes                                                                                                                                   |
| ------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `gameLoop.findMatch({ queueId })`                       | Queues the player, polls, then connects                | Also takes `skill`, `onStatus`, and `onTicket`                                                                                          |
| `gameLoop.acceptMatch(true)`                            | Accepts or declines while `findMatch` is still running | `false` returns the ticket to `SEARCHING`                                                                                               |
| `gameLoop.matchmaking.createParty`                      | Starts a party for one queue                           | Takes a minimum and a maximum. Follow with `setReady`, `startParty`, and `followParty`. `autoStart` defaults to true                    |
| `connectToServer({ transport, serverUrl, joinParams })` | Opens a direct connection                              | A string URL is WebSocket. WebTransport needs `serverCertificateHashes`. A direct call sends no `sessionId`, `playerId`, or `authToken` |
| `startServer`                                           | Dedicated server listen                                | Matchmaking does not replace this or `GameMode`                                                                                         |
| `disconnectFromServer`                                  | Intentional leave                                      | Returns the world to standalone. An unexpected drop reconnects with backoff, up to five attempts                                        |
| `GameMode.canPlayerJoin`                                | Server accepts or refuses the join                     | Details are in the spawning table. Check placement fields against the match this process was started for                                |
| `GameMode.generatePlayerName(clientId)`                 | Name assigned when a player joins                      | `joinParams` are not copied into the name. Render it as text                                                                            |
| `chatEnabled`                                           | Built-in session chat                                  | On by default. Set `false` on the `GameMode` to turn it off. Do not build a second chat on RPCs                                         |
| `chatJoinLeaveNotices`                                  | Join and leave lines in session chat                   | Set `false` to silence them                                                                                                             |
| `filterChatMessage(senderClientId, text)`               | Rewrites or drops a chat line                          | Return `null` to drop it. The sender name is the server's `PlayerInfo.playerName`                                                       |
| `defaultServerScene`                                    | Scene the dedicated server opens                       | Set **Server Default Scene** in Project Settings. A multiplayer upload is blocked until it is set                                       |

Ticket statuses: `QUEUED`, `SEARCHING`, `REQUIRES_ACCEPTANCE`, `PLACING`, `COMPLETED`, `CANCELLED`, `FAILED`, `TIMED_OUT`.

`PLACING` means a match exists and connection info may not be ready yet. `CANCELLED`, `FAILED`, and `TIMED_OUT` throw `MatchmakingError`. A protocol or schema mismatch closes the connection: `protocol-version-mismatch` or `schema-hash-mismatch`.

## Lag in Play mode

Local testing is on [Test multiplayer locally](https://studio-docs.sandbox.game/multiplayer/test-multiplayer-locally.md).

| Name                       | What it does                             | Notes                                                                                                     |
| -------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Multiplayer**            | Local dedicated server and extra clients | Checkbox in the network menu next to Play. Does not change the cloud game                                 |
| **Clients**                | How many clients Play mode starts        | 1 to 4. The editor viewport is the first. Extra windows are this count minus one                          |
| **Transport**              | WebSocket or WebTransport                | Chosen in the same menu                                                                                   |
| **Server Lag Simulation**  | Lag on connections the server accepts    | Separate switch from client lag                                                                           |
| **Clients Lag Simulation** | Lag on the client's connection           | Separate switch                                                                                           |
| **Latency**                | One-way delay                            | 0–500 ms                                                                                                  |
| **Jitter**                 | Variation in that delay                  | 0–100 ms                                                                                                  |
| **Packet Loss**            | How often a message is dropped           | 0–100%. Reliable messages are delayed and kept. Unreliable replication and unreliable RPCs can be dropped |

*Last verified 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/multiplayer-reference.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.
