# Multiplayer web game on the kits (rooms and invitations)

How to turn a game built on the Game Kits into a web game several people play together: pick the network model, open a
room, invite the other players, check it. Readable offline: `gripforge docs web-multiplayer`, or the MCP tool
`gripforge_docs` (topic `web-multiplayer`). The kits and their settings are in `gripforge docs net`.

## 1. Choose the model

Install one sync kit; it is the network model of the game (`gripforge docs net` has the table):

```text
gripforge_gamekit_install { project_id: "gkp_…", id: "net.claim" }   # brings net.transport
```

| Model | Pick it when | Notes |
| --- | --- | --- |
| `net.claim` | co-op, sandbox, cars, anything where your own avatar must answer at once | each client simulates what it owns; the server arbitrates; not for competitive play |
| `net.authoritative` | shooters, economies, rankings | the server simulates; clients predict; costs server CPU |
| `net.rollback` | duels, small deterministic arena games | inputs only; needs a deterministic simulation |
| `net.state` | cards, boards, turn games, hidden information | rules are data, validated on the server |

For a vehicle game (an arena with cars and a ball, a kart race) start with `net.claim`; for physics shared between peers
add `net.physics` and set the sync kit's `physics` to `shared`. The room reads the model, the sync settings and the
physics settings from the project (`config.net = { model, sync, physics }`); change them with
`gripforge_gamekit_configure`, never in the room.

## 2. Keep it playable alone

The audit flags `common.network_optional` when a sync kit is installed and nothing lets one player play without a server.
Add `coop.session` (role `solo`) or a solo entry in the menu; the room is the way to invite others, not the only way to
start.

## 3. Open a room

Open this address on the GripForge site, signed in to the workspace that owns the project:

```text
/play/online/host/<project_id>?players=4
```

`players` is the number of seats (2 to 16; default 2). The page creates a private room for the project (the server is
`gfnet-server` with the project's model), starts it, makes one personal invitation per other seat, and shows them as
links. Press Play to enter the game with your own seat: the game's menus and lobby run as in any other session. The
link of the room is `/play/online/<room_id>#<key>`; the key stays in the fragment, is used once and is not kept in the
address afterwards. Invitations last four hours. Opening a room needs the editor or owner role of the workspace.

Through the API: `POST /api/v1/network/rooms { projectId, minPlayers, maxPlayers, requireReady }`, then
`POST /api/v1/network/rooms/<id>/start`, `…/invitations { role: "player" }` for each invitation, `…/redeem { token }`.

## 4. Invite and check

- Send each link to one person; every link is one seat.
- To look at the game alone first, `gripforge_game_play_url` returns the project's play address (the solo preview); share
  it as finished only when `gripforge_game_audit` says complete and `gripforge_validate_release` says ready.
- Run `gripforge_game_test` before inviting anyone: the automatic player drives a vehicle with the throttle and steer
  inputs of the game as a person would, and reports a game that cannot start alone.

## Errors

| You see | Cause | What to do |
| --- | --- | --- |
| `not_networked` | the project installs no `net.claim` / `net.authoritative` / `net.rollback` / `net.state` | install one sync kit |
| `This game has no net.transport kit` | a sync kit without its transport | install `net.transport` |
| The service of rooms does not answer | the runtime of the rooms is offline | retry; rooms can still be prepared |
| `invalid_net` | a hand-made room whose `net.model` is not a string | pass `{ model, sync, physics }` or use a project |