5.9 KiB
Score Keeper
Score Keeper tracks player scores in configurable buckets. Use it for event points, competitions, or other server-side scoring systems, and integrate it with other plugins through the public API. Points are awarded by commands or companion plugins, not by built-in gameplay event listeners.
Installation
Requires Java 25 and Paper 26.2 or 26.3. Stop your server cleanly, back up plugin
data, and place the downloaded jar in plugins, removing older Score Keeper jars.
Restart and check the server log. The installed plugin ID and data folder remain
ScoreKeeper; the display name is Score Keeper.
Commands
Players can omit an optional player name to target themselves. Named targets must
be online. Console and RCON must provide a player name for score get/add/subtract/reset;
archive also accepts all and bucket scopes. Add/subtract accept signed 32-bit
integers, including zero and negative amounts. Bucket IDs are case-sensitive and
allow letters, numbers, _, and -; each command-created unit label is one argument.
/score-get [playerName]- Displays the target player's score in their active bucket./score-add <amount>- Adds an amount to your score in your active bucket./score-add <playerName> <amount>- Adds an amount to the target player's score./score-subtract <amount>- Subtracts an amount from your score in your active bucket./score-subtract <playerName> <amount>- Subtracts an amount from the target player's score./score-reset [playerName]- Resets the target player's active-bucket score to that bucket's initial value./score-archive- Archives and resets your score in your active bucket./score-archive <playerName>- Archives and resets the target player's score in their active bucket./score-archive all- Archives and resets scores in every bucket./score-archive bucket <bucketId>- Archives and resets every score in one bucket./score-archive-list- Lists saved archive IDs, newest first./score-archive-list <archiveId>- Displays the saved scores in one archive./score-bucket- Displays your active bucket./score-bucket <bucketId>- Switches your active bucket./score-bucket create <id> <singular> <plural> <initialValue> [reporting]- Creates a bucket. Reporting can beadmin,global,player, ornone(default)./score-bucket <playerName> <bucketId>- Switches a player's active bucket./score-bucket all <bucketId>- Changes the server's default bucket and clears individual bucket assignments./score-run start <bucketId> <topN> <true|false> target <score>- Starts a run that ends when a score reaches the target./score-run start <bucketId> <topN> <true|false> duration <time>- Starts a timed run. Use a positive number and lowercases,m,h,d, orw, such as4h./score-run start <bucketId> <topN> <true|false> until-disabled- Starts a run with no automatic end, including across clean restarts./score-run stop <bucketId>- Ends an active run.
Permissions
The scorekeeper.admin permission (default: operators) is required for
score-archive, bucket creation, switching another player/all players, and run
management. Viewing/selecting your own bucket is open. Score get/add/subtract/reset
and archive-list have no permission checks; add, subtract, and reset can target
any online player. Restrict access externally if this does not fit your server.
Features
- Create score buckets with custom singular/plural labels, initial values, and reporting policies.
- Reporting can notify operators/admins, everyone online, only the scored player, or nobody.
- Start target-score, timed, or until-disabled high-score runs with configurable top-N standings and optional score resets.
- Archive player, bucket, or all-bucket scores; archived scores reset to their bucket's initial value.
- Persist bucket definitions, assignments, scores, active runs, and archives in the plugin's data folder.
Reporting defaults to none, so successful score mutations can be silent; use
/score-get to inspect the number. Changed scores use singular units for exactly
1, plural otherwise. Scores may be negative and overflow is not checked.
Runs require top N of at least 1 and a literal true/false reset argument.
For example, /score-run start points 3 true duration 4h. Run reporting overrides
the bucket policy: the scored player always receives changes, and current top-N
players' changes are reported globally. Rankings include all recorded bucket
entries, even offline players; ties use case-insensitive name then UUID and
consecutive places. Final results include each online player's place. Reset runs
restore previous scores, while non-reset runs keep earned scores. Timed runs use
wall-clock time, including time offline; an existing target can finish a non-reset
run immediately.
Stop a run before archiving its bucket. Final run results are announced/logged,
not automatically archived. Archives and live state are saved to
plugins/ScoreKeeper/archives.yml and scores.yml on clean shutdown/plugin
disable, not after every command. Crashes can lose changes since the last save.
Do not edit data files while the server is running.
API
Other plugins can create buckets with
createBucket(id, singular, plural, initialValue, ScoreReporting), use bucket-aware
score methods, and manage runs with startTargetScoreRun, startTimedScoreRun,
startUntilDisabledScoreRun, and stopHighScoreRun. Declare a dependency on
ScoreKeeper and call the enabled plugin API on Paper's main thread.
See the integration reference.
Compatibility
Built exclusively for Paper 26.2 and 26.3 with the Paper API and Adventure APIs. Bukkit and Spigot servers are not supported.
Source and development instructions are in the repository. Licensed under GNU AGPL v3 or later.