> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiplayer skill for AI agents

> Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next. A Summer Engine skill for AI agents.

`multiplayer` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next.

| | |
| - | - |
| Status | Stable |
| Domains | Multiplayer, Project |
| Version | `1.0.0` |
| Engine version | `>=4.6` |
| Recommended set | Yes, installed by `--recommended` |

## When your agent uses it

* The user wants multiplayer, co-op, PvP, online play over the internet, or to play with friends in a Summer game
* The user asks for peer-to-peer, a player-hosted server, host migration, join-by-IP or a lobby
* Deciding how a multiplayer Summer game is structured before writing networking code
* A multiplayer game was built with @rpc or MultiplayerSynchronizer and needs moving to Summer's networking

## Install

`summer setup` installs every skill for your agent. To add only this one:

```bash theme={null}
npx -y summer-engine@latest skills install multiplayer --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option.

## The skill

Read this first, whatever the user asked for: "multiplayer", "co-op", "PvP",
"online", "play with friends", "lobby", "peer-to-peer", "host a game",
"netcode", "sync players". It explains the model in one page and sends you to
the skill that builds the next piece.

## The picture

A Summer multiplayer game is **one project with two entry scenes**:

* the **client** scene, which every player runs: input, camera, visuals, UI;
* the **authority** scene, which runs headless as the match server and owns
  the rules.

```text theme={null}
   each player's device                   Summer hosting (or Local Play)
  ┌──────────────────────┐  my pose       ┌──────────────────────────────┐
  │ client scene         │ ─────────────► │ authority scene = one World  │
  │ moves its own player │  "collect"     │ checks every pose and request│
  │ draws everyone else  │ ─────────────► │ owns score, doors, items...  │
  │                      │ ◄───────────── │                              │
  └──────────────────────┘  state, events └──────────────────────────────┘
```

* A running match is a **World**. Summer starts one authority for it; the game
  declares what a World is in `world.json` (a **WorldDefinition**).
* A player joins with `Summer.client.join(...)` and gets a verified
  **Session**: their seat in that World, with a verified player identity.
* Players find a World through a **queue** in `summer.build.json`. Hosted,
  Summer's matchmaking fills it; locally, **Local Play** starts the authority
  and N clients on your machine.
* The same code runs locally and hosted. No `if server`, no local-only
  branches, no IP addresses.

There is no player-hosted server, so there is no host migration, and a player
quitting never ends the match for the others.

## How data moves

Both sides load one **network composition** (`network/composition.tres`). It
declares every stream the game uses, and a **Spawner** node attaches it to the
World:

| You want | Use | Who writes it | Skill |
| - | - | - | - |
| My character moves | Owner-written State group, one per player | that player's client; the authority checks each pose | `multiplayer-movement` |
| Everyone sees the score, a door, the round timer | Authority-written State group, World audience | the authority | `multiplayer-state` |
| Only I see my wallet, hand, inventory | Authority-written State group, target-Session audience | the authority | `multiplayer-state` |
| A player wants to buy, open, collect, ready up | Command | client asks, authority accepts or refuses | `multiplayer-state` |
| A one-off effect (sparkle, sound, hit flash) | Event | the authority | `multiplayer-state` |

State is retained, so a late joiner gets the current value. Commands carry
the sender's verified Session. Events are fire-and-forget.

## The rules

1. **Each client moves its own character.** Movement feels instant on every
   connection. The authority accepts or refuses each pose, and a refused pose
   snaps the player back.
2. **The authority owns every other fact.** Clients never change shared
   state; they send a Command and show the result.
3. **Identity comes from the Session**, never from a field a client sent.
4. **Never use the stock high-level multiplayer API in a Summer game:** no
   `@rpc`, `MultiplayerSynchronizer`, `MultiplayerSpawner`,
   `ENetMultiplayerPeer`, `multiplayer.is_server()` or peer-ID branches. Their
   sender ids are transport peers, not verified players. Late joiners miss
   state, and the game cannot use Summer hosting, matchmaking or identity.
5. **Test under a bad network before calling anything done:** Local Play
   with latency, jitter and loss (`multiplayer-testing`).

## Words

| Word | Meaning |
| - | - |
| Game | Your game on Summer; its id is `gameId` in `summer.build.json`. `Summer.initialize()` takes no ID: Summer knows which game is running |
| World | One running match or shared place, simulated by one authority |
| WorldDefinition | `world.json`: which scenes run the client and the authority, lifetime, persistence |
| Queue | How players find a World; declared in `summer.build.json` |
| Session | One player's verified seat in a World |
| Composition | The network contract both sides load: State streams, Command and Event streams |
| State group | One retained value (a pose, a scoreboard); one writer, an audience |
| Command | A request from a client, answered by the authority |
| Event | A one-off message from the authority |
| Local Play | Runs the authority and N clients locally, with optional network emulation |

## Build it in this order

Each skill continues the same small game, so their code fits together:

1. **`multiplayer-project`**: the files, both entry scenes, joining, and a
   first Local Play run.
2. **`multiplayer-movement`**: each player moves their own character; others
   see it smoothly; the authority checks every pose.
3. **`multiplayer-state`**: score, doors, private inventories, Commands and
   Events.
4. **`multiplayer-testing`**: Local Play under latency and loss, bots, and
   what a passing run must show.
5. **`multiplayer-publish`**: export the summer.games bundle and upload it as
   a Build.
6. **`release-readiness`**: before players get a version, prove the server
   starts its authority scene and a real online join works.

## Add Summer services

| Skill | What it adds | Works in Local Play? |
| - | - | - |
| `summer-matchmaking` | Queues, match sizes, teams, the accept prompt, join failures | Yes, without the accept prompt |
| `summer-match-results` | Ending a match: winners, losers, rating changes | Yes |
| `summer-leaderboards` | Ratings and Game-wide leaderboards | Partly; reading boards needs hosting |
| `summer-parties` | Friends queue together as a party | No, hosted only |
| `summer-friends` | The player's Summer friends and direct messages | No, hosted only |
| `summer-player-data` | Progress that follows the player to any World | Yes, stored on disk |
| `summer-world-saves` | Worlds that persist between sessions | Yes, in memory |
| `summer-world-chat` | Text chat inside a World | No, hosted only |
| `summer-store` | Selling items for Sparks, owned items | Items yes; the store is hosted only |
| `summer-analytics` | Game events for your analytics dashboard | No, hosted only |

## What people ask for, and what Summer does

| They ask for | On Summer |
| - | - |
| "One player hosts", peer-to-peer | A headless authority per match, started by Summer or by Local Play |
| Host migration | Not needed: no player is the authority |
| Join by IP, invite code, server browser | Not available. Players join a queue; friends join as a party (`summer-parties`) |
| A lobby | A queue with `minPlayers`/`maxPlayers` and an accept prompt (`summer-matchmaking`) |
| "Sync the player's position" | An owner-written pose group (`multiplayer-movement`) |
| "Tell everyone the door opened" | An authority-written State group (`multiplayer-state`) |
| "The client asks the host to buy something" | A Command validated with the verified Session (`multiplayer-state`) |
| Save progress | Player data for the player, World saves for the place (`summer-player-data`, `summer-world-saves`) |

## Start

Check what exists: `summer.build.json`, `world.json`, `network/`,
`authority/`, `client/`.

* **None of them:** start with `multiplayer-project`.
* **They exist:** pick the skill for the piece you need from the tables above.
* **The game already uses `@rpc` or `MultiplayerSynchronizer`:** tell the user
  it needs moving to Summer's networking. Then follow `multiplayer-project`
  and port one system at a time: movement first, then state.

## From a shell

No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.

| In this skill | Command |
| - | - |
| `summer_get_scene_tree` | `summer engine get-scene-tree` |
| `summer_get_script_errors` | `summer engine get-script-errors` |
| `summer_project_setting` | `summer engine project-setting` |

## Related skills

* [`multiplayer-project`](/skills/multiplayer-project): Set up a Summer multiplayer project: entry scenes, World and queue files, joining, a first Local Play.
* [`multiplayer-movement`](/skills/multiplayer-movement): Movement in Summer multiplayer: owners move instantly, others glide, the authority checks each pose.
* [`multiplayer-state`](/skills/multiplayer-state): Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events.
* [`multiplayer-testing`](/skills/multiplayer-testing): Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run.
* [`multiplayer-publish`](/skills/multiplayer-publish): Ship a hosted Summer multiplayer game: the bundle, server preset, pre-upload checks, a new Build.
* [`release-readiness`](/skills/release-readiness): Before releasing a Summer game version, prove players can play it: server, online join, progress, files.
* [`summer-matchmaking`](/skills/summer-matchmaking): Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures.
* [`summer-player-data`](/skills/summer-player-data): Save a player's progress so it follows them to every match: authority load and commit, autosave, safe retries.

***

Source: [`library/skills/multiplayer/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/multiplayer/SKILL.md), rendered from `summer-engine@4.3.0` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.