96 lines
5.9 KiB
Markdown
96 lines
5.9 KiB
Markdown
**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 be `admin`, `global`, `player`, or `none` (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 lowercase `s`, `m`, `h`, `d`, or `w`, such as `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.
|
|
|
|
## 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](https://github.com/headhunter45/ScoreKeeper/blob/develop/docs/plugin-integration-and-event-wiring.md).
|
|
|
|
## 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](https://github.com/headhunter45/ScoreKeeper). Licensed under GNU AGPL v3 or later.
|