Config
rating({
games: [
{ key: "duel", algorithm: "elo", xp: { win: 20, draw: 10, loss: 5 } },
],
serverAuthoritative: true,
recordScope: "rating:record",
})| Game field | Default | |
|---|---|---|
key | — | A URL path segment |
algorithm | — | elo · glicko · trueskill · your own id |
players | 2 | Must be within the algorithm’s supported range |
pool | the game key | Name one to share a ladder |
xp | — | Per outcome |
levels | — | Worst to best. Classified on read |
hideSkill | false | Still drives matchmaking |
sharedRoomCounts | false | Whether 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
| Players | Teams | Skill number | Main dial | |
|---|---|---|---|---|
elo | 2 | no | The rating | K, default 32 |
glicko | 2 | no | rating − 2·RD | τ, default 0.5 |
trueskill | 2+ | 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
| Route | Verified by |
|---|---|
POST /rating/games/:game/outcomes | user + record scope when server-authoritative |
GET /rating/games/:game/me | user |
GET /rating/games/:game/players/:userId | user |
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.
| Route | Scope | |
|---|---|---|
GET /rating/admin/pools | rating:players:read | Every pool, its algorithm, and the games that rate it |
GET /rating/admin/pools/:pool/players | rating:players:read | The pool’s ratings, highest skill first, keyset-paged. Takes cursor and limit |
GET /rating/admin/pools/:pool/players/:userId | rating:players:read | One 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/recalculate | rating:players:adjust | Rebuild the rating by replaying the player’s logged outcomes through the pool’s algorithm |
POST /rating/admin/pools/:pool/players/:userId/reset | rating:players:adjust | Return 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 blob | Validated against the recorded algorithm on read |
| Skill | Indexed — a matchmaking bucket is a range read |
| XP | Monotonic |
| 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_outcomes | One row per applied outcome: pool, game, placements, teams, the resultId when one was given, when, and whether it was voided |
pithy_rating_outcome_players | One row per participant: the state, experience and game count they entered with, and the experience gained |
pithy_rating_adjustments | One 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
| Binding | Kind |
|---|---|
DB | D1 |
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_forbidden | Server-authoritative, and no record scope |
rating/unknown_algorithm | |
rating/unsupported_player_count | Caught on deploy, not at the first result |
rating/invalid_params | The 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.