Leaderboards rankings and persistent high scores

The recipe

Author with project_apply_script_semantic_patch using the ai_safe op pack; the warehouse reads happen in a GessaScript body.

1. Persist each player's best: on run end, compare the new score to the stored best and writeTypedStateValue the larger (or incrementNumericState a running total) into a durable record keyed by the durable player id, in a leaderboard store (for example storeKey:"leaderboard", one record per player).
2. Track live scores in a match with ctx.match.addScore for a subject and read with ctx.match.getScore; mirror the current value to the HUD with wireHudStateBinding.
3. Build the ranked list: in a GessaScript body, ctx.warehouse.query the leaderboard store to read the records, then SORT them by the score field yourself. Records come back ordered by recordKey in canonical collation, not by value, so the ranking order is your computation, not the query.
4. Page large boards: pass the query result nextCursor back verbatim to walk pages; take the top N after sorting rather than assuming the first page is the top.
5. Show it: push the ranked names and scores into a UI panel (see ui-hud-panels-and-widgets) with ctx.ui.setWidgetValue, or bind a single headline stat with wireHudStateBinding.

Pitfalls

• Warehouse query does NOT sort by value; do not expect an orderBy. Read the records and rank them in the script.
• Key each record by the DURABLE player id, not a per-session id, or the board resets every match (the same rule as a persistent scoreboard subject key).
• Warehouse writes are prefetch-then-drain and authority-gated; update the best on the server at run end, not per tick.
• A giant board is costly to read every frame; recompute the ranking on score change or on a timer, not each tick.

Verify

• simulation_run (qa.run.start) to prove a new best updates the record and the ranked list reorders.
• project_get_graph_snapshot to confirm the score-write handlers and the HUD binding landed.