# Rooms Service (presence, challenges, one server per match) (net.rooms)

## What it is for

Provides an always-on rooms service in front of match servers: presence, optional login with the game's own token, a directory of players and matches, expiring one-to-one challenges and one server per match.

It needs `net.transport`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "net.rooms" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.rooms",
                              config: { "challengeTtlMs": 30000, "maxChallengeTtlMs": 120000 } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "net.rooms" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.rooms",
                              config: { "challengeTtlMs": 30000, "maxChallengeTtlMs": 120000 } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `challengeTtlMs` | integer | `30000` | 1000–600000 | A challenge not answered in time expires. |
| `maxChallengeTtlMs` | integer | `120000` | 1000–600000 | Largest delay a challenger may ask for. |
| `requirePick` | boolean | `true` |  | A player picks (a character, a deck…) before it can be ready. |
| `observable` | boolean | `true` |  | Running matches are listed with their address, for spectators. |
| `launchTimeoutMs` | integer | `30000` | 1000–600000 | A match whose server is not up in time ends with server_unavailable. |
| `keep` | integer | `16` | 1–256 | Closed challenges and ended matches kept in the shared state. |
| `placement` | string | `"hosted"` | `hosted`, `declared`, `both` | Where a challenge's match goes: hosted (the host starts a server), declared (a free declared server of the studio, none =… |
| `auth` | boolean | `false` |  | Players log in with the game's own token (connect(name, url, token)); the service's host validates it and names the player. |
| `hooks` | array | `[]` |  | Rooms actions the service's host validates first (the game's own rules), refused with the game's reason. |
| `view` | boolean | `true` |  | Show the ready-made rooms view (a ui.webui fragment, the same on the web and the engines): players, challenges, seats, picks,… |
| `choices` | array | `[]` |  | What a player may pick in the ready-made view (characters, decks, cars…); none: a free text pick. |
| `match` | object | `{"preset": "simultaneous-duel"}` |  | net.state config of every match server (default: the simultaneous-duel preset); the service adds the seats and tickets, clients… |

## Services, events, variables

- Service `net.rooms`: connect(name, url?, token?), login(token), disconnect(), view() → { connected, seat, presence, players, incoming, outgoing, match, observable, servers, server, ticket, watching, closed, results, error, play }, challenge(seat, ttlMs?), accept(id), decline(id), cancel(id), pick(choice), ready(value), 
- Events emitted:
  - `rooms.changed` (`presence`, `match`) — The view of the rooms changed (directory, challenges, match setup, error): this player's presence and match.
  - `rooms.challenged` (`id`, `from`) — A new challenge for this player.
  - `rooms.match_ready` (`match`, `slot`) — The match server of this player's match is up: its address and seat ticket are in view().ticket (joinMatch() opens it).
  - `rooms.match_ended` (`match`, `reason`, `result`) — A match of this player ended (finished, left, disconnect_timeout, server_unavailable… and the match server's result); the player is back in the rooms.
  - `rooms.match_aborted` (`match`, `reason`) — The match this client opened went away without an end: its match server stopped (server_unavailable) or the link closed for good first…

## Hooks and modding

This kit declares no hook and no collection to mod.

## Engines

Declared targets: `web`, `rust`. `gripforge kit api net.rooms` lists the exact settings and services of your version.

## Versions

Kit version 1.0.0.