2026-08-05
HISCORE: a score you can post anywhere
Four required fields, one line of code, no account and no SDK. The whole definition fits on this page on purpose, because a protocol nobody can read in one sitting does not spread.
AI generated
Text. Disclosure under Article 50 of the EU AI Act, Regulation (EU) 2024/1689.
Tamed by yours truly tastemaster and AI dragon rider Jamji Jamaramji.
This is the definition. It is short because the history says short wins: the cost of a first correct implementation decides adoption, and every complete specification lost to a crude one.
The name is provisional. Nothing on the wire depends on it.
The record
A score is one JSON object.
`` { "game": "polytopia", "player": "jamji", "score": 12345, "mode": "domination/imperius", "unit": "points", "dir": "high", "rules": "1.4.2", "at": "2026-08-05T09:30:00Z" } ``
Required: game, player, score. That is it. Everything else has a default and can be left out.
| Field | Meaning | Default |
|---|---|---|
game | who produced this. Any stable string, ideally one you own, like a domain or a slug | required |
player | who did it. Any stable string | required |
score | a number | required |
mode | mode, ruleset, faction, difficulty, anything that makes two scores incomparable. Slash-separated | "" |
unit | points, ms, s, count | points |
dir | high if more is better, low if less is better | high |
rules | version of the game or ruleset this was scored under | "" |
at | when, in UTC | time of receipt |
Why those four extra fields exist
Three of them are not decoration. They are the difference between a leaderboard and a pile of numbers.
dir and unit, because otherwise you cannot sort. A time of 42 beats a time of 61. A score of 42 loses to a score of 61. Without a declared direction the collector has to guess, and it will guess wrong for every racing game ever made.
mode, because a score is only comparable inside its own rules. Polytopia has different tribes. A speedrun has categories. Without this field, every board silently merges games that were never the same game.
rules, because a patch changes the sport. A score set in 1.0 is not a score set in 1.4 if something was rebalanced in between. Chess would not put pre-1880 and modern games in one table.
The rest of the design is one sentence: anything you cannot fill in honestly, leave out.
How you send it
One line in your head, one call when the run ends.
`` <script src="https://gamesareeatingtheworld.com/gs.js" data-key="YOUR_KEY"></script> <script>GS.submit(score)</script> ``
Or, without any of our code, post the object yourself:
`` POST https://gamesareeatingtheworld.com/api/scores Content-Type: application/json ``
No SDK, no build step, no callback, no login for your players.
One thing is not free: the game id has to be claimed once. Write to john@mcgrinsey.com with the id you want and it exists a few minutes later. That is a deliberate gate, not an oversight. An endpoint that accepts writes from anyone under any name is exactly what killed trackback, and a claim step is the cheapest defence that still costs an honest developer almost nothing.
If any of this is more work than the game itself deserves, we have already lost.
Four things we promise, so you can leave
Every cross-game leaderboard ever built died, and mostly by being acquired. Asking anyone to depend on us requires saying what happens when we stop.
Your scores are yours and exportable. GET /api/scores?key=… returns everything, no key required to read.
No exclusivity. Send the same record to three collectors. The format does not care, and that is the point: a record any collector can accept means we can be replaced instead of mourned.
A long notice if we shut down. OpenFeint gave developers under thirty days. That is the specific thing we are promising not to do.
We say how sure we are. Every score carries how it arrived: submitted, or measured, or imported from elsewhere. A number without its provenance is a rumour.
What this does not solve, said plainly
Anyone can post any number. Trackback had verification and died of spam anyway, because the attacker satisfied the check rather than breaking it. We do not pretend to have solved this.
What we do instead is tiers, not truth. A run that took under half a second, or a value a hundred times the median of its board, is stored and flagged and does not appear. Twin Galaxies reached the same answer over forty years: separate lists with separate rules, because verified and unverified are both useful and only dangerous when mixed.
A player id is free, so one person can hold a thousand. Any fix for that costs adoption, and adoption is the thing a protocol dies without. We chose adoption and we are telling you which side we picked.
A cross-game identity is a tracking identifier. That is not a metaphor, it is what the law calls it. The name is chosen by the player, is not required to be a real one, and on our own site it is stored only with consent.
Status
Not a standard. A convention with one implementation.
robots.txt ran for twenty-eight years before anyone wrote it down as RFC 9309, and the RFC documented a convention that had already won. That is the order we are copying. If this spreads, it can be formalised. If it does not, no committee was harmed.
Adopt it, fork it, or ignore it. It is four fields.
This piece also runs in the McGrinsey magazine. mcgrinsey.com