docs(link): points.board, the leaderboards API, and what a real shard changed #69

wtclaude · 2026-07-29T02:07:32Z

wtclaude commented

2026-07-29 02:07:32 +00:00

What & why

Protocol 3.0 §7 lands across servuo-plugins #4, link #18 and website #114; this is the matching documentation. Order 4 of 6 in the v3 sequence.

`link/INTEGRATION.md`

points.board in the event catalog — one frame per system, never a delta, no points.remove (the shard's system set is fixed at startup). Four gotchas called out, all of them things a consumer gets wrong by default:
1. maxPoints: 0 means UNCAPPED, not "zero allowed" — and on a real shard it is the common case, so anything rendering points / maxPoints must special-case it or divide by zero on the happy path.
2. nameString is usually null, with a cliloc in nameNumber — so humanising the system key is the primary display path, not a fallback.
3. players counts players actually holding points, not table size: ten of the ~25 systems keep a zero-point row per character ever created, so the raw count would report the shard's whole census as one system's participants.
4. Entries carry serial + name only, never acct/webId.
The char.profile points block, and why rank is absent by default.
GET /points and /points/:system, including why 404 (never published) and 200-with-empty-top (published, nobody scored) are different answers.

`link/v3.md`

B/2 marked done in both the progress table and §9.
NEW §7.5, "what the run against a real shard changed" — the same record §6.1 and §6.2 keep for Part C. Four corrections the plan could not have anticipated from reading PointsSystem.cs, the sharpest being that (long)double.MaxValue is an unchecked conversion yielding long.MinValue, which published "maxPoints": -9223372036854775808 on the first live sweep. Also records that GetEntry/GetPoints mutate the world on AutoAdd systems and so cannot be used in a read model, and the one deliberate deviation from §7.4: the visibility field rule must key on the wire's name, not the descriptive characterName, or it is silently inert.

`website/BACKEND_DESIGN.md`

shard_points_boards — including why the top-N list stays in the payload and why listing orders by COALESCE(name, system) — plus the two new public routes.

`link/PLAN.md`

3.0 phasing brought current: the spawn atlas and points.board added to what has shipped, and the Points* keys noted in the config-key paragraph.

How it was tested

Documentation only — no code. Every claim here was written after the corresponding behaviour was observed running, not from the plan:

the maxPoints overflow and its fix were both reproduced against a live 43,011-mobile ServUO world (servuo-plugins #4);
the "nameString is usually null" and "uncapped is the common case" claims come from counting what that shard actually emitted (4 of 5, and 3 of 5, respectively);
the route behaviours (404 vs empty top, the :system constraint) were exercised against the running sidecar and website (link #18, website #114).

PROJECT_TREE.md files are deliberately untouched — they are CI-generated by the sync-project-tree workflow and say so in their header.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally. (Markdown only.)
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Protocol 3.0 **§7** lands across servuo-plugins #4, link #18 and website #114; this is the matching documentation. Order 4 of 6 in the v3 sequence. ### `link/INTEGRATION.md` - **`points.board` in the event catalog** — one frame per system, never a delta, no `points.remove` (the shard's system set is fixed at startup). Four gotchas called out, all of them things a consumer gets wrong *by default*: 1. **`maxPoints: 0` means UNCAPPED**, not "zero allowed" — and on a real shard it is the **common** case, so anything rendering `points / maxPoints` must special-case it or divide by zero on the happy path. 2. **`nameString` is usually `null`**, with a cliloc in `nameNumber` — so humanising the `system` key is the *primary* display path, not a fallback. 3. **`players` counts players actually holding points**, not table size: ten of the ~25 systems keep a zero-point row per character ever created, so the raw count would report the shard's whole census as one system's participants. 4. Entries carry `serial` + `name` only, **never `acct`/`webId`**. - The **`char.profile` `points` block**, and why `rank` is absent by default. - **`GET /points`** and **`/points/:system`**, including why `404` (never published) and `200`-with-empty-`top` (published, nobody scored) are different answers. ### `link/v3.md` - B/2 marked done in both the progress table and §9. - **NEW §7.5, "what the run against a real shard changed"** — the same record §6.1 and §6.2 keep for Part C. Four corrections the plan could not have anticipated from reading `PointsSystem.cs`, the sharpest being that **`(long)double.MaxValue` is an unchecked conversion yielding `long.MinValue`**, which published `"maxPoints": -9223372036854775808` on the first live sweep. Also records that `GetEntry`/`GetPoints` **mutate the world** on `AutoAdd` systems and so cannot be used in a read model, and the one deliberate deviation from §7.4: the visibility field rule must key on the wire's `name`, not the descriptive `characterName`, or it is silently inert. ### `website/BACKEND_DESIGN.md` `shard_points_boards` — including why the top-N list stays in the payload and why listing orders by `COALESCE(name, system)` — plus the two new public routes. ### `link/PLAN.md` 3.0 phasing brought current: the spawn atlas and `points.board` added to what has shipped, and the `Points*` keys noted in the config-key paragraph. ## How it was tested Documentation only — no code. Every claim here was written *after* the corresponding behaviour was observed running, not from the plan: - the `maxPoints` overflow and its fix were both reproduced against a live 43,011-mobile ServUO world (servuo-plugins #4); - the "`nameString` is usually null" and "uncapped is the common case" claims come from counting what that shard actually emitted (4 of 5, and 3 of 5, respectively); - the route behaviours (`404` vs empty `top`, the `:system` constraint) were exercised against the running sidecar and website (link #18, website #114). `PROJECT_TREE.md` files are deliberately **untouched** — they are CI-generated by the `sync-project-tree` workflow and say so in their header. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. *(Markdown only.)* - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-29 02:07:33 +00:00

docs(link): points.board, the leaderboards API, and what a real shard changed 8e857a9c8d

Protocol 3.0 §7 lands across servuo-plugins, link and website; this is the
matching documentation.

INTEGRATION.md
  - points.board in the event catalog: one frame per system, never a delta, no
    points.remove (the shard's system set is fixed at startup). Four gotchas
    called out, all of them things a consumer gets wrong by default:
      1. maxPoints: 0 means UNCAPPED, not "zero allowed" — and on a real shard
         it is the COMMON case, so anything rendering points/maxPoints must
         special-case it or divide by zero on the happy path.
      2. nameString is usually null, with a cliloc in nameNumber — so
         humanising the system key is the primary display path, not a fallback.
      3. players counts players actually holding points, not table size: ten of
         the ~25 systems keep a zero-point row per character ever created, so
         the raw count would report the shard's whole census.
      4. Entries carry serial + name only, never acct/webId.
  - The char.profile `points` block, and why `rank` is absent by default.
  - GET /points and /points/:system, including why 404 (never published) and
    200-with-empty-top (published, nobody scored) are different answers.

v3.md
  - B/2 marked done in both the progress table and §9.
  - NEW §7.5, "what the run against a real shard changed" — the same record §6.1
    and §6.2 keep. Four corrections the plan could not have anticipated from
    reading PointsSystem.cs, the sharpest being that (long)double.MaxValue is an
    unchecked conversion yielding long.MinValue, which published
    "maxPoints": -9223372036854775808 on the first live sweep. Also records that
    GetEntry/GetPoints mutate the world on AutoAdd systems and so cannot be used
    in a read model, and the one deliberate deviation from §7.4: the visibility
    field rule must key on the wire's `name`, not the descriptive
    `characterName`, or it is silently inert.

BACKEND_DESIGN.md — shard_points_boards (including why the top-N list stays in
the payload and why listing orders by COALESCE(name, system)), plus the two new
public routes.

PLAN.md — 3.0 phasing brought current: the spawn atlas and points.board added to
what has shipped, and the Points* keys noted in the config-key paragraph.

PROJECT_TREE.md files are deliberately untouched — they are CI-generated and say
so.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-29 07:52:20 +00:00

whitlocktech merged commit f715323aa0 into edge

2026-07-29 07:52:30 +00:00

whitlocktech deleted branch feat/points-board

2026-07-29 07:52:31 +00:00

whitlocktech referenced this issue from a commit

2026-07-29 07:52:31 +00:00

Merge pull request 'docs(link): points.board, the leaderboards API, and what a real shard changed' (#69) from feat/points-board into edge

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#69