maj/ScoreKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updates docs.

Browse Source
This commit is contained in:
Tom Hicks
2026-10-10 22:57:27 -07:00
parent 4bc838cbe7
commit 7135acbfed
17 changed files with 1135 additions and 959 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/modrinth-description.md
View File

@@ -1,10 +1,24 @@
**ScoreKeeper Plugin**
**Score Keeper**
ScoreKeeper 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.
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. Console and RCON must provide a player name for score get/add/subtract/reset 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.
@@ -23,14 +37,18 @@ Players can omit an optional player name to target themselves. Console and RCON
* `/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> <reset:true|false> target <score>` - Starts a run that ends when a score reaches the target.
* `/score-run start <bucketId> <topN> <reset: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> <reset:true|false> until-disabled` - Starts a run with no automatic end.
* `/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 archive commands, bucket creation/administration, and high-score run management. Score get/add/subtract/reset and archive-list commands currently have no permission checks; add, subtract, and reset can target any online player.
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
@@ -40,10 +58,38 @@ The `scorekeeper.admin` permission (default: operators) is required for archive
* 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, reporting)`, use bucket-aware score methods, and start or stop high-score runs with `startTargetScoreRun`, `startTimedScoreRun`, `startUntilDisabledScoreRun`, and `stopHighScoreRun`.
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.