> 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/share-state-and-actions.md).

# Share state and actions

A value that every player must agree on, including someone who joins later, is a replicated property. A button press, an attack, or a burst of visual effects is an RPC. The server checks the request, then writes the property. Who owns the match is on [How multiplayer works](https://studio-docs.sandbox.game/multiplayer/how-multiplayer-works.md).

A player action, such as an attack or using an object, is the request. The shared result, such as health or score, is the property. Asking the agent for the match, then checking both, is on [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md).

## Replicated properties

The server changes the value. Connected clients receive that change and update what they show.

Health, scores, a match timer, who holds an objective, whether a door is open, and whether a pickup has been taken are all properties. Put the field on the replicated entity:

```typescript
@ENGINE.property({ replicate: true })
score = 0;
```

Decorators come from `@gnsx/genesys.js`, the same import as [Project code fundamentals](https://studio-docs.sandbox.game/best-practices/project-code-fundamentals.md).

A Pawn already sets `isRoot` and `replicated`. For your own root, set both before the node registers with the network. Setting `replicated` on an `isRoot` node creates its replication info. `replicated` on its own, on a node that is not a root, does not make that node the entity. Changing `replicated` after registration throws. Setting `replicated` on a client has no effect.

The entity registers with the network on `beginPlay`. Game code does not call `registerEntity`.

The server writes replicated fields. A client write stays on that client. Only members of a replicated entity take part.

When a replicated value arrives, the engine calls `onRep` plus the property name with its first letter capitalized, on the receiver. A field named `score` calls `onRepScore`:

```typescript
onRepScore(): void {
  // Refresh the scoreboard from this.score.
}
```

There is no per-tick distance check. Limit who receives a field with `net.replicateTo` set to `'all'`, `'owner'`, or `'non-owner'`. A `MultiplayerSpawner` audience is the other way to limit who sees a spawned object.

Updates go from the server to clients at a default send rate of 30 Hz. Clients acknowledge snapshots. Later packets are deltas from the last acknowledged tick. A destroyed entity is sent as a tombstone. A late joiner replays the current spawner journal, so objects that already exist still appear.

## Remote calls

An RPC is a method on a replicated entity. It runs on the other side of the connection.

| Decorator                | What it is for                                                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@ENGINE.ServerRPC()`    | The owning client asks the server to do something. Validate on the server before changing state                                                       |
| `@ENGINE.ClientRPC()`    | The server tells the owning client something, such as a hit result only that player should see. No owner means the call is not sent                   |
| `@ENGINE.MulticastRPC()` | Runs on the server, then on every client, such as an impact effect. Call it from the server. 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                                                                          |

Import the package as `ENGINE`, then write `@ENGINE.ServerRPC()`. The function names are `ServerRPC`, `ClientRPC`, `MulticastRPC`, and `RemoteRPC`.

A player attack runs in this order:

1. The player presses attack.
2. The owning client sends a `@ENGINE.ServerRPC()`.
3. The server decides whether the attack is allowed.
4. The server applies the result, usually by changing a replicated property such as health.
5. Clients show the new health. A multicast or client RPC can play the swing or the hit effect.

The damage number lives on the property. The swing can live on the RPC. An effect can be missed for a frame. A health value cannot.

Each of those decorators defaults to `{ reliable: true }`. Pass `{ reliable: false }` when a lost call is acceptable, such as a high-frequency effect.

On WebSocket, every frame is ordered and reliable. On WebTransport, unreliable RPCs and replication travel as datagrams.

`@ENGINE.MulticastRPC()` is not an authority guard. Call it from the server when every peer must run it. Keep lasting state, including anything a late joiner must see, on a replicated property.

`@ENGINE.ServerRPC()` also runs locally when the caller already has authority on the server. Wrap that call in `if (ENGINE.NetRuntime.isClient())` when the server should not trigger it.

## Which copy of the entity is running

The same SceneNode class runs on the server and on each client. The role tells you which copy this is.

| Role             | Which copy                                  |
| ---------------- | ------------------------------------------- |
| Authority        | The server's copy                           |
| Autonomous proxy | The character this client controls          |
| Simulated proxy  | A character or object someone else controls |

Checks you can make from gameplay code include `hasAuthority()`, `isLocalAutonomousProxy()`, `isSimulatedProxy()`, and `isOwnedByLocalClient()`.

On a node with no replication info, `hasAuthority()` returns true. Call it on a node that already has `isRoot` and `replicated` set.

## Practical guidance

Ask the agent to keep shared results, such as health, score, or inventory, on replicated properties. Ask it to send player actions through a server RPC, and to reject the action in that method when the player is not allowed to take it.

```
Keep shared results on replicated properties. When a player takes an action, send a server RPC. The server checks that action, then updates the property. A client write stays on that client.
```

Use a multicast RPC for a shared effect that does not need to be true for a late joiner. Use a replicated property when a late joiner must still see the result.

Character movement is a separate path from these calls. [Networked movement](https://studio-docs.sandbox.game/multiplayer/networked-movement.md) covers prediction and correction.

## Common mistakes

| Mistake                                                                                  | What to do instead                                                                                                                                                             |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Storing a shared result only on the client that caused it                                | Write it on the server and replicate it                                                                                                                                        |
| Sending the damage amount from the client and applying it unchanged                      | Send the action. The server decides the result                                                                                                                                 |
| Using an RPC as the only record of health or score                                       | Keep the lasting value on a replicated property                                                                                                                                |
| Calling `hasAuthority()` on an ordinary scene object and treating the match as networked | Use it on an entity that is already set up to replicate                                                                                                                        |
| Spawning a projectile with a normal scene add and expecting other players to see it      | Spawn it through a scene-placed `MultiplayerSpawner` on the server. See [Create a multiplayer game](https://studio-docs.sandbox.game/multiplayer/create-a-multiplayer-game.md) |
| Calling a multicast RPC on the client and expecting other players to see it              | Call it from the server. A client call runs locally and sends nothing                                                                                                          |
| Writing a replicated score on the client                                                 | The write stays on that client. The server is the copy that updates everyone else                                                                                              |


---

# 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/share-state-and-actions.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.
