Games and moves

Overview

Active games are stored as GAME records. The sort key encodes metaGame, completion bit (0 = in progress), and game id:

pk: GAME
sk: <metaGame>#0#<gameid>

When a game completes, the completion bit becomes 1 and summary rows are written to COMPLETEDGAMES* families. The live dashboard is built from CURRENTGAMES# merged with USERGAME# overlays (seen, lastChat) for active games. Legacy USER.games[] on the USER record is retired (Phase 5).

Lifecycle

  1. Created — from an accepted challenge, tournament/event pairing, or start_solo_game (1-player, always unrated).
  2. In progress — submit_move validates via @abstractplay/gameslib, updates state, clocks, and toMove.
  3. Automove — for games with the automove flag, if the next player has only one legal move, the backend plays it automatically.
  4. Time loss — timeloss (auth or internal) ends games when clocks expire.
  5. Abandoned — abandoned handles resign/abandon flows.
  6. Completed — archived to COMPLETEDGAMES#* indexes; removed from active lists after the user has seen the result.

Key queries

Query Endpoint Purpose
submit_move auth Play a move
get_game public / auth Fetch game state
timeloss auth Report timeout
abandoned auth Abandon game
invoke_pie auth Pie rule — reverse player order
start_solo_game auth Start solo play (numPlayers: 1, rated: false, optional challengeSeed)
set_game_state auth Admin state injection
update_game_settings auth Per-game settings
submit_comment auth Game chat (GAMECOMMENTS)
update_note auth Per-user notes (NOTE)

Pie rule

invoke_pie reverses the player list in the GAME record and updates watcher summaries. Pie eligibility uses engine.getFlags() (not static gameinfo.flags) so variant-gated pie / pie-even matches the front. Challenge and tournament creation use effectiveFlags() for perspective, rotate90, and EOG emails use it for scores. The stream projector refreshes each participant's CURRENTGAMES# row on the next GAME modify.

Playground

Users can save unlimited playground positions. Each save is stored as pk: PLAYGROUND#<userid>, sk: <uuid> with name, metaGame, date, and body (JSON; auto-compressed when large). Queries: list_playground_saves, get_playground_save, create_playground_save, save_playground_save, delete_playground_save.

Record types

Related