# Multiplayer API

> An HTTP API that makes any game multiplayer, whatever the genre.
> Player accounts, matchmaking, shared state, peer-to-peer WebRTC, leaderboards,
> and anti-cheat. Nothing is game-type-specific: everything is declared.

Base: `https://multiplayerapi.com/v1`

## Integrate in three lines

```js
import { Multiplayer } from 'https://multiplayerapi.com/sdk/mp.esm.min.js';
const mp = new Multiplayer({ key: 'mp_pk_your_key' });
await mp.login();                    // instant guest account
const room = await mp.quickmatch();  // join or create a room
```

Get a key with no UI, in one call:

```bash
curl -X POST https://multiplayerapi.com/v1/games \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Game","preset":"realtime_arena"}'
```

## What to understand before writing code

Three channels — pick based on what the data carries:

- `room.send(data)` — direct between players, best-effort, zero server cost. For a
  position, an animation, anything that will be replaced within 100 ms.
- `room.set(path, value)` — shared state, guaranteed, persists in the match and
  reaches late joiners. For hit points, score, whose turn it is.
- `room.emitEvent(topic, data)` — ordered and guaranteed event, no persistence.
  For a chat message, a rematch request.

Picking the wrong channel is the main source of bad integrations: sending a
position through `set()` costs a lot for nothing; storing hit points through
`send()` loses them on the first reconnect.

## Documentation

- [Full agent reference](https://multiplayerapi.com/llms-full.txt): everything
  needed to integrate without further reading, endpoints and examples included.
- [OpenAPI 3.1](https://multiplayerapi.com/openapi.json): machine schema.
- [Guide](https://multiplayerapi.com/docs/): human-facing documentation.
- [JavaScript SDK](https://multiplayerapi.com/sdk/mp.esm.min.js): 5.9 KB gzip, no dependencies.
- [Unity SDK](https://multiplayerapi.com/sdk/): UPM package, optional WebRTC.
- [Playable demos](https://multiplayerapi.com/demo/): tic-tac-toe, arena, FPS, and
  slither.io, source readable as-is.

## Recipes by genre

Full code for each in the “Recipes” section of
[llms-full.txt](https://multiplayerapi.com/llms-full.txt), or in the
[guide](https://multiplayerapi.com/docs/#recettes):

- Turn-based (cards, board, puzzle): everything in shared state, turn lock via
  `room.cas('turn', me, opponent)`, move and handoff sent together with
  `room.flush({ atomic: true })`.
  [Demo](https://multiplayerapi.com/demo/morpion/)
- Realtime (arena, .io, FPS): positions via `room.send()`, hit points and score
  in state. [Arena](https://multiplayerapi.com/demo/arene/) ·
  [Slither](https://multiplayerapi.com/demo/slither/) ·
  [FPS](https://multiplayerapi.com/demo/fps/)
- Co-op (shared world, survival): writes by everyone with a bounded `rate`,
  `room.setnx()` to claim a unique item without conflict.

## Good to know

- Accounts are scoped per game: a player in your game does not exist elsewhere.
- A player can join as spectator (`mp.watch(code)`): they read the match, do not
  take a seat in capacity, and the server rejects anything they would write.
  Enable with `max_spectators` in the game configuration.
- Your server can be notified of notable events (`match.ended`,
  `cheat.flagged`, `player.banned`) via a signed notification, rather than
  polling the API.
- Password reset is two steps: your server requests a token with
  `POST /v1/auth/recover` using the secret key, then delivers it to the player
  however it wants. The API sends no email.
- A guest account left sixty days with no login is deleted; an account upgraded
  with `upgrade` is kept.
- The public key goes in the client; the secret key stays on your server.
- The server only validates what you declare in the game rules; without rules,
  a player may only write under `players.<their id>`.
- Once peer-to-peer is up, the client only calls the server once every five
  seconds. State writes stay immediate: the SDK notifies other players on the
  direct channel, which costs nothing.
- Only turn peer-to-peer off if you have a specific reason, even for a turn-based
  game: without it, the client must poll the server much more often to stay
  responsive.
- If the dashboard Usage tab shows direct connections often failing, declare a
  TURN server (`turn` in the configuration): it is the only setting that brings
  players behind hostile networks back to direct.