Rating reference

Config

rating({
  games: [
    { key: "duel", algorithm: "elo", xp: { win: 20, draw: 10, loss: 5 } },
  ],
  serverAuthoritative: true,
  recordScope: "rating:record",
})
Game fieldDefault
key—A URL path segment
algorithm—elo · glicko · trueskill · your own id
players2Must be within the algorithm’s supported range
poolthe game keyName one to share a ladder
xp—Per outcome
levels—Worst to best. Classified on read
hideSkillfalseStill drives matchmaking
sharedRoomCountsfalseWhether a game with a friend earns XP
algoParams—Validated by the algorithm

Top level: serverAuthoritative (default true), recordScope, basePath (default /rating). Which algorithm to name is the algorithms; what pool does is pools; the calls are Using Rating. Refusals carry an ordinary error code.

Algorithms

PlayersTeamsSkill numberMain dial
elo2noThe ratingK, default 32
glicko2norating − 2·RDτ, default 0.5
trueskill2+yesμ − 3·σβ, τ, draw probability

Validated at assembly, not at the first result.

A pool is rated by exactly one algorithm, and changing it is a new pool rather than a migration. Two games that share a pool with different algorithms are refused at assembly, naming both, as validation/invalid_input. Tuning may differ by game.

Routes

RouteVerified by
POST /rating/games/:game/outcomesuser + record scope when server-authoritative
GET /rating/games/:game/meuser
GET /rating/games/:game/players/:userIduser

No public surface. Without auth composed, every route denies.

Management

With the control plane composed, a management client reads ratings and repairs one with its own credential. Every path sits under admin/, so none can collide with a player route, and each is built from the mounted basePath.

RouteScope
GET /rating/admin/poolsrating:players:readEvery pool, its algorithm, and the games that rate it
GET /rating/admin/pools/:pool/playersrating:players:readThe pool’s ratings, highest skill first, keyset-paged. Takes cursor and limit
GET /rating/admin/pools/:pool/players/:userIdrating:players:readOne player’s rating and the outcomes behind it, newest first, keyset-paged. A player with no rating is rating: null, not a 404
POST /rating/admin/pools/:pool/players/:userId/recalculaterating:players:adjustRebuild the rating by replaying the player’s logged outcomes through the pool’s algorithm
POST /rating/admin/pools/:pool/players/:userId/resetrating:players:adjustReturn the rating to the algorithm’s starting state. Experience and games played are kept

Each act takes an idempotencyKey and a required reason. A replayed key answers what the first request did, writes nothing and emits nothing; a key already spent on another act, pool or player is core/conflict. An unknown pool is rating/pool_not_found on every route that names one, and an act on a player with no rating is core/not_found.

A recalculation replays the outcome log, each opponent entering at the state the log kept for them, so it lands where live application did. A later recalculation replays from a reset, not through it. A rating with no logged outcome behind it is refused with core/conflict and nothing written, rather than reset in silence: it predates the log, and there is nothing to replay. A rating older than the log replays from where the log first saw it.

Each act is recorded in pithy_rating_adjustments with the rating before and after, and writes one audit event, rating/player_recalculated or rating/player_reset, with both. The read is all GETs, so pithy dashboard connect grants it by default; the acts are POSTs and never are.

Voiding a result. A capability composed beside rating calls ratingPeer.voidResult with a result id: every outcome recorded with that id is marked void, and every player it touched is recalculated from the outcomes that remain, reported before and after. It is idempotent.

The outcome body

{ "ranks": { "u1": 1, "u2": 2 } }

Finishing place per user id. 1 wins; ties share a place.

Optional: teams for a team format, sharedRoom, and resultId, the id of the result this outcome comes from. The log keeps it, so voiding that result takes the outcome back out of every rating it moved. Nothing else — pool from config, algorithm from the pool, timestamp from the server.

The tables

pithy_rating_ratings — one row per (pool, player).

Column
The algorithm’s state blobValidated against the recorded algorithm on read
SkillIndexed — a matchmaking bucket is a range read
XPMonotonic
Games played
Updated at

The outcome log sits beside it, written in the same D1 batch that moves the ratings, so when the log cannot be written no rating moves. It is append-only; a void marks an outcome rather than deleting it.

Table
pithy_rating_outcomesOne row per applied outcome: pool, game, placements, teams, the resultId when one was given, when, and whether it was voided
pithy_rating_outcome_playersOne row per participant: the state, experience and game count they entered with, and the experience gained
pithy_rating_adjustmentsOne row per control-plane act, with the rating before and after. Unique on the idempotency key

No board table and no config in the database. Ratings recorded before the log have no rows in it.

Bindings

BindingKind
DBD1

pithy add rating writes it into every environment. Nothing needs provisioning beyond the database you already have.

Error codes

Code
rating/game_not_found
rating/pool_not_found
rating/record_forbiddenServer-authoritative, and no record scope
rating/unknown_algorithm
rating/unsupported_player_countCaught on deploy, not at the first result
rating/invalid_paramsThe algorithm refused them

Registering your own

registerRatingAlgorithm(yourAlgorithm) in your Worker entry, before the capability assembles.

Declare an id, a params schema with defaults, a state schema, supported player counts, and pure initial, update and skill functions.

ESC