Why the protocol is shaped like this

This piece is not the definition. The definition is the standard page, which carries every field with its maturity and a changelog, and hiscore.txt, which is the same thing written for a machine with no argument in it.

This is the argument. Why the thing is shaped the way it is, which choices were forced, and which four we got wrong and had to reverse in public.

Three fields, because the fourth is where protocols die

game, player, score. Everything else is optional.

That is not minimalism as a style. It is the only lever that reliably decides adoption. The history of protocols says the same thing every time: the cost of a first correct implementation beats completeness, elegance and governance combined. RSS beat Atom on this. Trackback spread and then died on a different problem. WS-* was more complete than anything that replaced it and is gone.

So the test for every proposed field was: does a game that omits it still work? If yes, it is optional. If no, it does not go in.

The optional fields are all one idea

There is exactly one reason for the optional fields, and it is this: two numbers that are not comparable must not end up in the same column.

• mode is content. World 2, hard, playing as the wizard.
• rules is a constraint that changes the ranking. No items, tournament rules.
• unit and dir say what the number is and which end wins. A time is not a point score, and for a time the smaller value is better.

Together with game they form the comparison key: game + mode + rules + unit + dir. Two scores are ranked against each other exactly when all five match. That sentence was missing until version 1.0, and a reviewer was right to ask for it. Five fields affect comparability and only one rank comes back, so the rule has to be written down or every implementer guesses differently.

The four we got wrong

Worth reading even if you never implement this, because these are the mistakes the shape invites.

We claimed a name could be reserved. The design promised that twenty people can be called RONAN, distinguished by a surname. The code locked the name as soon as the first RONAN claimed it, so there could only ever be one, and the surname was decoration. The secret now selects which identity you are instead of locking the name. Guests under the same name keep working, which they always should have.

We called signed scores unforgeable. They are not. An Ed25519 signature proves a score came from the game's own server. It says nothing about whether the number is real: a server that signs whatever a browser hands it will happily sign a lie. The label describes the channel, not the truth, and it now says so.

We said waiting time cannot be parallelised. It can. An attacker opens ten thousand sessions and waits in all of them at once. The narrower claim survives and is still useful: you cannot make one session age faster than the clock.

We rate-limited signed scores by sender address. Signed scores arrive from the game's server, so every player of that game shares one address. A game with thirty people playing would have died at twenty-one scores a minute. Signed traffic is now limited per game.

None of these were found by us. They came from outside readers, which is the argument for publishing a specification before it is finished rather than after.

Gate the visibility, not the write

An endpoint that accepts writes from anyone under any name is exactly what killed trackback. The usual fix, an account, has the cost backwards: a real hurdle for an honest developer, nothing at all for a spammer with a script.

So the gate sits somewhere else. Claiming is free and instant. Being seen is what costs something.

• The proof is a page you already have. A one-time token has to appear at an address that actually serves your game. A spammer has to publish something real, at a real host, for every fake game. You had to publish anyway.
• Your own board is live the second you verify. Link it, test it, put it in your game.
• The public index is not. A game joins the front page once three different people have posted a score. Until then it carries noindex, so claiming an id buys exactly zero attention.

Spam wants to be seen. An honest developer wants it to work. Those are separable, so we separated them, and the gate sits on the one nobody honest is in a hurry for.

Two tiers, because half the games cannot hold a secret

A game that is nothing but files, uploaded to itch.io or GitHub Pages, has no runtime where a private key could live. Anything the browser knows, a forger knows. There is no authentication there and there cannot be.

A game with a server can do better. So there are two tiers, and the agent doing the integration decides which one it can deliver by reading the project. The human still pastes one line.

That decision belongs to the agent for a practical reason: a developer asked "open or signed?" will pick wrong, because the answer depends on the deployment target rather than on preference.

Provenance is set by us, never by the sender

Every score carries how it arrived: submitted, signed, measured, imported, verified. The server decides, always.

A sender that can label its own score as verified does not have a trust level, it has a text field. That is the whole reason the field exists on our side of the line.

And the labelling is the honest half of a problem nobody has solved. Browser scores are forgeable. We rate-limit, we flag impossible runs and absurd values, we can withdraw a flood in minutes with a record of what happened. That is mitigation, and calling it anything stronger would be the first lie in a system whose only currency is not lying.

What is still open

replay is named in the field list and does not exist. A clickable recording next to a record would be the moment a leaderboard stops being a table, but inventing a format before anyone needs one is the reliable way to get a format nobody uses.

There is no federation. If a second collector appears, nothing here describes how the two reconcile. Send to both. They are cheap.

And names are not identities in a strong sense. A secret picks which identity you are; lose it and you pick a new surname. An account makes that recoverable, and an account is never required to play or to report.

If you have a game, none of this matters to you: paste hiscore.txt into your coding agent and it is done in five seconds of your time. This page is for the people who want to know why it is shaped this way before they build on it, which is a reasonable thing to want.

Adopt it, fork it, or build something better. The point is that a standard exists.