hiscore

README

hiscore

The Mills Arcade leaderboard service — an opt-in, privacy-preserving high-score registry for the arcade's WebAssembly games, served under https://games.mills.io/api/v1.

Privacy

The service is deliberately boring about data:

• Opt-in only. Nothing is sent anywhere until the player chooses submit on the game-over screen and types a name.
• No accounts, no identity. A leaderboard entry is exactly three fields: a self-chosen pseudonym (1–12 characters), score, and a timestamp.
• No tracking. Client addresses are used in memory for rate limiting only; they are never logged or written to disk. No cookies, no analytics.

API

Method	Path	Purpose
GET	/api/v1/healthz	liveness
POST	/api/v1/sessions	open a play session for a game
POST	/api/v1/scores	submit a score (see below)
GET	/api/v1/scores/{game}?limit=N	top N (default 10, max 25)

Abuse resistance

Scores are cheap to fake, so submissions have to earn their way in:

• Signed sessions. A submission needs a session token issued by the server; tokens are HMAC-signed, bound to one game, and single-use.
• Play-time proof. The token's age must be at least the minimum plausible play time before a score is accepted, and sessions expire.
• Proof-of-work. Each submission must solve a small hashcash puzzle bound to the token, initials and score — imperceptible for one player, expensive at spam scale.
• Rate limits. Per-address token buckets on every endpoint, in memory only.
• Sanity checks. Same-origin enforcement for browsers, score caps, a name character whitelist, and the classic arcade blocklist.

Packages

• client — Go client used by the games (native and js/wasm).
• ui — a drop-in Ebitengine overlay: the opt-in prompt, name entry, proof-of-work and top-ten display, shared by every cabinet.
• pow — the hashcash puzzle, shared by client and server.
• api — wire types.

Running

go build -o hiscore . && ./hiscore -bind :8000 -data ./data

Or with Docker:

docker run -p 8000:8000 -v hiscore-data:/data prologic/hiscore

Configuration via flags or environment: BIND, DATA_DIR, GAMES, POW_BITS, MIN_PLAY_SECONDS, MAX_SESSION_HOURS, MAX_SCORE, ORIGINS.

License

MIT

Documentation

Overview

Command hiscore is the Mills Arcade leaderboard service, served under https://games.mills.io/api/v1. It keeps opt-in high scores — initials, score, timestamp; nothing else — for the arcade's games.