Score Keeper

Score Keeper tracks player scores in named buckets for server events, competitions, and companion plugins. Buckets support custom units, initial values, reporting, archives, and target-based or timed high-score runs. Gameplay does not award points automatically: use commands or another plugin calling the public API.

Supports Paper 26.2 and 26.3 only, with Java 25. Bukkit and Spigot servers are not supported. The display name is Score Keeper; the repository and installed plugin identifier remain ScoreKeeper.

Installation

Obtain a plugin jar from Modrinth or build it using CONTRIBUTING.md.
Stop your Paper server cleanly. Back up existing plugin data.
Put ScoreKeeper-<version>.jar in the server's plugins directory, removing older Score Keeper jars so only one version loads.
Start the server and verify the plugin enables without errors.

Scores, bucket definitions, reporting, player assignments, and active runs load from plugins/ScoreKeeper/scores.yml; archives load from plugins/ScoreKeeper/archives.yml. Both are saved on plugin disable/clean shutdown, not after every command. Crashes or forced termination can lose changes since the last successful save. Do not edit these files while running.

Running

Commands

For commands with an optional player name, players can omit it to target themselves. Named targets must be online. Console and RCON must provide a player name for score get/add/subtract/reset; archive also supports all and bucket scopes. Bucket IDs are case-sensitive and allow letters, numbers, _, and -. Command-created singular/plural labels each occupy one argument. Add/subtract accept signed 32-bit integers, including zero and negative amounts.

/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 score in their active bucket 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 is admin, global, player, or none and defaults to none.
/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 followed by lowercase s, m, h, d, or w (for example, 4h).
/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.

The reset argument for a run is the literal true or false, not reset:true. Top N must be at least 1. For example:

/score-bucket create event point points 0 player
/score-bucket event
/score-run start event 3 true duration 4h
/score-add 10
/score-get
/score-run stop event
/score-archive bucket event

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 requires no admin permission. Score get/add/subtract/reset and archive-list currently have no permission checks; add, subtract, and reset can target any online player. Restrict command access externally if that is inappropriate for your server's scoring rules.

Reporting, runs, and archives

When a player's active bucket changes, they are told the bucket name and their current score with its singular or plural unit.

Bucket reporting defaults to none; admin notifies operators and score admins and logs the change, global notifies all online players, and player notifies only the scored player. Only changed values produce reports. With none, a successful add/subtract/reset can be silent; use /score-get to inspect the numeric score. Scores can go negative and arithmetic overflow is not checked.

Each bucket can have one active run. During it, players receive their own score changes regardless of the bucket reporting policy; changes by players in the top N after the update are reported globally. Rankings include all recorded bucket entries, even offline players. Ties sort by case-insensitive name, then UUID, and have consecutive places. Finished runs announce/log the top-N table and each online player's place. Reset runs restore the pre-run bucket scores; non-reset runs leave earned scores intact. Timed runs use wall-clock time, including time offline. An existing target can end a non-reset run immediately.

Run results are not automatically archived. Stop the run before archiving its bucket. Archives snapshot the selected recorded scores and reset them to the bucket initial value; they become durable at clean shutdown.

Plugin API

Other plugins can create buckets with createBucket(id, singular, plural, initialValue, ScoreReporting) and use bucket-aware score methods. Existing no-bucket methods use the player's active bucket. Runs use startTargetScoreRun, startTimedScoreRun, startUntilDisabledScoreRun, and stopHighScoreRun.

Declare a dependency on plugin ID ScoreKeeper, obtain the enabled ScoreKeeperPlugin instance, and call it on Paper's main thread. There is no separate service registration or automatic gameplay integration. See plugin integration and event wiring for setup, overloads, and failure handling.

Development

Start with CONTRIBUTING.md and the shared rules in AGENTS.md. The project uses Gradle 9.8.0, Java 25 toolchains, and Spotless. The compile toolchain can be downloaded automatically, but the wrapper still needs a compatible JVM to start.

There are currently no automated Java tests; a passing build does not exercise plugin behavior. Use human-tests.md before releases. See the contributor guide's project overview for architecture and the modernization plan for remaining work.

License

Score Keeper is licensed under the GNU AGPL v3 or later.

7.4 KiB Raw Blame History