Games Reference

All eight games

Every game shares the same session and result contract. What differs is match size, supported match types, and the extra fields attached to result.groups[].finalState.

Result reasons

Result envelope

Every ended session's result object follows one shape, whatever the game:

GameResult

{
  "reason": "checkmate",
  "duration": 692,           // seconds
  "winnerGroupId": "g_1",   // absent on a draw
  "groups": [
    { "id": "g_1", "players": [ /* … */ ], "won": true },
    { "id": "g_2", "players": [ /* … */ ], "won": false }
  ],
  "finalState": { /* game-specific snapshot, see each game below */ }
}

Chess additionally retains legacy top-level winner, pgn, and fen fields for backward compatibility with the original single-table schema.

game: "chess"

Classic two-player chess with running clocks, castling, promotion, and AFK forfeiture.

Result fields

Moves are exchanged over the socket in UCI notation (e.g. e2e4, e7e8q for promotion). An idle player receives an AFK warning at 60 seconds and is forfeited at 90.

game: "checkers"

Forced captures, multi-jump sequences, and king promotion on reaching the back row.

Result fields

A draw is recorded once the move-limit (200 moves) is reached without a capture-forced resolution.

game: "connect4"

Standard 7-column, 6-row drop board. First to connect four in any direction wins.

Result fields

game: "tictactoe"

The 3×3 classic. Lightweight enough to use as a demo or onboarding game.

No extra result fields beyond the shared envelope.

game: "pool"

8-ball rules. Groups (red / yellow) are assigned on the first legal pot; the black is only playable once a player has cleared their group.

How it's scored

Shot physics resolve on the client; the client reports the outcome of each turn (balls pocketed, fouls, first contact) back to the server, which validates and applies it. A foul on the black (potting it before clearing your group) ends the match in your opponent's favour; potting the cue ball is always a foul and grants ball-in-hand.

game: "chkobe"

A fast shedding card game for 2–4 players, played with a standard 52-card deck plus jokers. First to empty their hand wins.

House rules in play

Card weights used internally for bot heuristics and future rating math: Joker 40, Ace 11, Jack 20, Ten 10, King 2, Two 2, all others 1.

game: "archery"

Turn-based target archery for 2–8 players. Two sets of three arrows each, at a simulated 70-metre distance, with optional wind drift and hand tremor.

Scoring rings

Wind (up to 5 m/s) can change direction each set, and a small hand-tremor amplitude is applied to every shot — both configurable per deployment, both default to enabled.

game: "subway-runner"

Single-player endless runner. Created with matchType: "bot" — there's no opponent, "bot" simply denotes a solo session in the shared contract.

Result fields

Power-ups

Physics map variants

Six physics presets exist for tournament or seasonal variety — standard, moon, heavy_gravity, underwater, space_station, and wind_tunnel — each altering gravity, air resistance, and jump feel while reusing the same kinematics.

game: "ludo" — reserved

The engine, rules, and socket handlers exist and are functional, but POST /v1/sessions does not yet accept ludo as a valid game. Included here so integrators aren't surprised by the reserved type name.