Skip to content

docs(guide): document ScoreKeeper and PersistWallet#52

Merged
BCook98 merged 1 commit into
mainfrom
uplift/scorekeeper-guide-docs
Jun 17, 2026
Merged

docs(guide): document ScoreKeeper and PersistWallet#52
BCook98 merged 1 commit into
mainfrom
uplift/scorekeeper-guide-docs

Conversation

@BCook98

@BCook98 BCook98 commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Problem

The flagship leaderboard/wallet abstractions ScoreKeeper and
PersistWallet/PersistBest (kit.go ~93-99, internal/game/scorekeeper.go)
had zero mentions in GUIDE.md. Game authors were therefore steered into
the manual r.Post + KV-clobber footgun these helpers were built to eliminate:
forgetting to re-post on disconnect, never posting an abandoned-but-ticking
continuous world, and racing KV writes that clobber durable wallets at merge
time.

Fix

Add a "Bank scores the easy way: ScoreKeeper" subsection under
Scores and leaderboards in GUIDE.md documenting:

  • what ScoreKeeper does and the one-keeper-on-the-room idiom (with example);
  • when to use it, including continuous / never-ending (LifecycleResident) games via FlushAll from OnWake;
  • cadence semanticsOnImprove vs OnChange, and the always-post-first-sighting rule;
  • the three post points: live Record (always StatusFinished), FlushLeave (DNF, no-op when untracked, lower-is-better caveat), FlushAll (deterministic AccountID order, timer-free / replay-safe);
  • PersistBest (MergeMax) and PersistWallet (MergeSum + MergeMax) for resume KV, with a note that these feed KV only, not the board;
  • an explicit prefer this over manual r.Post + KV writes callout.

Docs only — no code changes.

Verification

  • go build ./... — pass
  • go vet ./... — pass
  • go test . -run ScoreKeeper -v — all 6 ScoreKeeper tests pass

Every documented claim (cadence behaviour, statuses, no-op, merge rules,
deterministic order, timer-free design) was checked against
internal/game/scorekeeper.go and scorekeeper_test.go. Intra-doc anchor
links (#scores-and-leaderboards, #choosing-a-lifecycle,
#durable-state-the-per-player-kv) verified against the actual headers.

No changeset added: this is docs-only with no module-surface change, so it
should not drive a version bump / release.

For reviewers

Confirm the API descriptions match the source and that the
prefer-ScoreKeeper framing reads right alongside the existing manual
Post/End guidance.

🤖 Generated with Claude Code

GUIDE.md never mentioned ScoreKeeper/PersistWallet (kit.go ~93-99,
internal/game/scorekeeper.go), so authors were steered into the manual
r.Post + KV-clobber footgun these abstractions exist to eliminate.

Add a "Bank scores the easy way: ScoreKeeper" subsection under Scores and
leaderboards covering: what it does, when to use it (esp. continuous /
never-ending games), an idiomatic example, cadence semantics
(OnImprove/OnChange), the live/FlushLeave/FlushAll post points,
PersistBest/PersistWallet, and an explicit prefer-this-over-manual-r.Post
note. Docs only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@BCook98
BCook98 marked this pull request as ready for review June 17, 2026 02:21
@BCook98
BCook98 merged commit 11cc3bc into main Jun 17, 2026
6 checks passed
@BCook98
BCook98 deleted the uplift/scorekeeper-guide-docs branch June 17, 2026 02:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant