Game Rooms

Change the game room settings of this site. Only send what changes; reset lists settings to return to their default. enabled (default false) switches rooms on; false closes every open room at once. host_auth: who may open rooms, ["visitor","tenant"] (signed-in visitors via visitor auth, tenant members via tenant_auth). Limits: max_players, lobby_ttl_minutes, idle_ttl_minutes, hard_ttl_hours, max_state_kb, max_string_length, nickname_max, max_concurrent_rooms, max_rooms_per_host, join_rate_per_ip (per hour). allow_undefined_games lets hosts open rooms for games without a definition (custom mode). late_join is the default for letting players join after the start. Owner only.

Current settings, the stored overrides, the defaults and the platform ceilings.

No input parameters required.

Create or replace a game definition; every room of this game uses it. rules_mode "custom": the game's own code decides what is legal (the engine still keeps seats, privacy, versions, sizes, fair dealing and dice). rules_mode "config": rules = {turn_mode: free|round_robin|host|simultaneous, advance: explicit|after_update, turn_timeout_seconds (round_robin), writers: {state_key: any|turn|host|own_seat|none}, default_writer (default "none"), max_updates_per_turn (0 = no limit), state_schema (JSON Schema subset: type, properties, required, items, enum, minimum, maximum, minLength, maxLength, minItems, maxItems, additionalProperties)}. own_seat keys hold an object keyed by seat number; a seat may only change its own entry. decks = {"main": [card, ...]} (max 200 cards of 256 bytes); in config mode hosts can only deal these decks. The engine owns the state keys rolls, reveals, commit_status, deck_counts and hand_counts. Use initial_state_json / rules_json / decks_json (JSON strings) to keep empty objects {} and numeric keys exactly as written.

One game definition with its version.

All game definitions of this site (summary).

No input parameters required.

Delete a game definition. Open rooms keep running until they end or expire.

Open rooms of this site with status and player counts. No game state and no nicknames.

Close a room at once (its players see that the room ended).

Open rooms and players now, plus daily counters (rooms created, joins, failed joins, moves, version conflicts).

No input parameters required.

Open a room as host (seat 0). Needs a signed-in visitor or tenant session allowed by host_auth. Returns the seat token (keep it, it is the only key to this seat), the join code and the room. initial_state / initial_state_json only for custom games.

Join a room with its code and a nickname (plain text, no links, e-mail addresses or phone numbers). Returns a seat token and the room.

The room as this seat sees it; with since_version {changed:false} when nothing changed. Pages poll /game-rooms/poll instead (the SDK does).

Change the shared state: state_json (whole new state) or patch_json (RFC 7396 merge patch), based on expected_version. 409 VERSION_CONFLICT when the room changed first: read again and redo. 422 when the move breaks the game rules.

Replace this seat's private data (only this seat can read it), e.g. a secret code.

Pass the turn to the next player (round_robin games). The seat on turn or the host.

Host: start the game. Closes the join code unless late_join is on.

Host: remove a player from the room.

Host: finish the game. The final state stays readable until the room expires.

Host: close and delete the room now.

Leave the room. A leaving host hands over to the next player; the last player leaving closes the room.

Host: shuffle a deck on the server and deal per_seat cards to every player. deck = a deck name from the game definition; custom games may send their own list (deck / deck_json, name). Cards go to each player's private hand; the rest stays hidden on the server.

Take n cards from a dealt deck into your hand.

Play cards from your hand onto a list in the public state (target). Only cards that are in your hand. In config games the target must be a key listed in rules.writers; give it writer "none" so cards only get there by play.

Hand in a secret move for a round. When every player has committed, all moves appear at once in state.reveals[round].

Host: reveal a round now; players who did not commit get null.

Roll dice on the server (fair). The result is added to state.rolls for everyone to see.