From cf53783bf9b8121aa152301eb294ee343ce8f7ed Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Sun, 27 Sep 2026 01:13:41 -0700 Subject: [PATCH] Updates to docs and ci. --- .env.example | 6 +- .github/workflows/gradle.yml | 2 +- CONTRIBUTING.md | 24 ++--- Modrinth-Description.md | 2 +- ...scription.json => Project-Description.json | 2 +- Project-Description.md | 12 +++ Project.md | 10 +-- ProjectDescription.md | 16 ---- README.md | 90 ++++++++++--------- build.gradle | 2 +- gradle.properties | 5 +- src/main/resources/plugin.yml | 66 +++++++------- tools/publish-modrinth.sh | 20 ++++- 13 files changed, 136 insertions(+), 121 deletions(-) rename ProjectDescription.json => Project-Description.json (79%) create mode 100644 Project-Description.md delete mode 100644 ProjectDescription.md diff --git a/.env.example b/.env.example index da300c3..736c0b4 100644 --- a/.env.example +++ b/.env.example @@ -8,6 +8,7 @@ PAPER_USER_AGENT="majinnaibu-plugin-dev/1.0 (https://github.com/majinnaibu)" JAVA_OPTS="-Xms2G -Xmx2G" STOP_TIMEOUT=60 MINECRAFT_SERVER_JAR=paper-26.2-129.jar + # Relative paths are resolved from the project root; ~/ is expanded. MINECRAFT_SERVER_PATH=./server MINECRAFT_BACKUP_PATH=./backups @@ -16,8 +17,9 @@ MINECRAFT_BACKUP_PATH=./backups # Release version is read from Gradle and checked against the jar's plugin.yml. MODRINTH_TOKEN= MODRINTH_PROJECT_ID=5NYwxysp -MODRINTH_CHANGELOG="Release 0.2.2" -MODRINTH_GAME_VERSIONS=1.21,1.21.1,1.21.2,1.21.3,1.21.4,1.21.5,1.21.6,1.21.7 +# Optional Markdown override; empty generates notes from commits since the last tag. +MODRINTH_CHANGELOG= +MODRINTH_GAME_VERSIONS=26.2,26.3 MODRINTH_LOADERS=paper MODRINTH_VERSION_TYPE= MODRINTH_DEPENDENCIES= diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml index 09e6fca..78f72c0 100644 --- a/.github/workflows/gradle.yml +++ b/.github/workflows/gradle.yml @@ -66,4 +66,4 @@ jobs: - name: Generate and submit dependency graph uses: gradle/actions/dependency-submission@v5 with: - include-configurations: '^(compileClasspath|runtimeClasspath)$' + dependency-graph-include-configurations: '^(compileClasspath|runtimeClasspath)$' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e95f444..2000d29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,9 +12,9 @@ Setup our project folder. ```bash PROJECTS_DIR="$HOME/Projects" MINECRAFT_SERVER_PATH="$PROJECTS_DIR/MCServer" -# Set this to the latest download url on the Paper downloads page [https://papermc.io/downloads](https://papermc.io/downloads) and update the jar name. -MINECRAFT_SERVER_DOWNLOAD_URI="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar" -MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar" +# Use Paper 26.2 or 26.3 only. The project helper scripts resolve the configured Paper build. +MINECRAFT_SERVER_DOWNLOAD_URI="" +MINECRAFT_SERVER_JAR="paper-26.2-129.jar" mkdir -p "$MINECRAFT_SERVER_PATH" # Keep this shell open we will use these variables later. ``` @@ -23,9 +23,9 @@ mkdir -p "$MINECRAFT_SERVER_PATH" ```powershell $projectsDir="$HOME\Projects" $minecraftServerDir="$projectsDir\MCServer" -# Set this to the latest download url on the Paper downloads page [https://papermc.io/downloads](https://papermc.io/downloads) and update the jar name. -$minecraftServerDownloadUri="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar" -$minecraftServerJar="paper-1.21.8-25.jar" +# Use Paper 26.2 or 26.3 only. The project helper scripts resolve the configured Paper build. +$minecraftServerDownloadUri="" +$minecraftServerJar="paper-26.2-129.jar" New-Item -Type Directory $projectsDir New-Item -Type Directory $minecraftServerDir # Keep this shell open we will use these variables later. @@ -34,18 +34,18 @@ New-Item -Type Directory $minecraftServerDir ## Install the JDK **Linux / WSL** ```bash -apt install openjdk-21-jdk +apt install openjdk-25-jdk ``` **macOS** ```zsh -brew install --cask microsoft-openjdk@21 +brew install --cask microsoft-openjdk@25 ``` **Windows** From Powershell ```powershell -winget install --id Microsoft.OpenJDK.21 --source winget +winget install --id Microsoft.OpenJDK.25 --source winget ``` ## Setup a PaperMC Server @@ -108,7 +108,7 @@ Our scripts depend on two environment variables. You can set them each time you To set them for the current session run these commands. To set for every new session add these commands to your `.bashrc` or `.zshrc` file. ```bash MINECRAFT_SERVER_PATH="$HOME/Projects/MCServer" -MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar" +MINECRAFT_SERVER_JAR="paper-26.2-129.jar" ``` **Windows** @@ -116,13 +116,13 @@ MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar" To set them for a single session run these commands. ```powershell $env:MINECRAFT_SERVER_PATH = "$HOME\Projects\MCServer" -$env:MINECRAFT_SERVER_JAR = "paper-1.21.8-25.jar" +$env:MINECRAFT_SERVER_JAR = "paper-26.2-129.jar" ``` If you want them available in all of your powershell sessions you can set them permanently like this. ```powershell [Environment]::SetEnvironmentVariable("MINECRAFT_SERVER_PATH", "$HOME\Projects\MCServer", "User") -[Environment]::SetEnvironmentVariable("MINECRAFT_SERVER_JAR", "paper-1.21.8-25.jar", "User") +[Environment]::SetEnvironmentVariable("MINECRAFT_SERVER_JAR", "paper-26.2-129.jar", "User") ``` ### Start-Server.ps1 and start-server.sh diff --git a/Modrinth-Description.md b/Modrinth-Description.md index 41dafb8..33ae551 100644 --- a/Modrinth-Description.md +++ b/Modrinth-Description.md @@ -46,4 +46,4 @@ Other plugins can create buckets with `createBucket(id, singular, plural, initia ## Compatibility -Built for Paper and uses Bukkit and Adventure APIs. +Built exclusively for Paper 26.2 and 26.3 with the Paper API and Adventure APIs. Bukkit and Spigot servers are not supported. diff --git a/ProjectDescription.json b/Project-Description.json similarity index 79% rename from ProjectDescription.json rename to Project-Description.json index b8f4d3a..707ffc8 100644 --- a/ProjectDescription.json +++ b/Project-Description.json @@ -1,7 +1,7 @@ { "id": "scorekeeper", "title": "ScoreKeeper", - "description": "Paper Minecraft plugin for tracking and managing player scores.", + "description": "A reusable Paper 26.2/26.3 scoring engine with named buckets, custom reporting, persistent archives, high-score runs, player commands, and a public API for companion plugins.", "docId": "ScoreKeeper", "image": { "url": "https://image.pollinations.ai/prompt/pixel%20art%20Minecraft%20server%20scoreboard%20with%20a%20glowing%20diamond%20and%20number%20counters%2C%20clean%20square%20game%20plugin%20thumbnail%2C%20no%20text", diff --git a/Project-Description.md b/Project-Description.md new file mode 100644 index 0000000..84a48aa --- /dev/null +++ b/Project-Description.md @@ -0,0 +1,12 @@ +# ScoreKeeper + +ScoreKeeper is a reusable scoring engine for Paper 26.2 and 26.3. It gives events, competitions, and companion plugins a shared language for points: named buckets can have custom singular/plural labels, initial values, reporting policies, archives, and high-score runs. + +The plugin is both a player-facing command system and an extension point. Administrators can start target-based, timed, or manually stopped score runs, while other plugins can create buckets, award points, archive results, and build richer game loops through the public API. Scores, assignments, runs, and archives persist across server restarts. Bukkit and Spigot servers are not supported. + +## Engineering Notes + +- Built with Gradle and Java 25 for modern Paper. +- Uses UUID-based player identity and YAML-backed persistence. +- Includes server-free JUnit coverage for domain rules, commands, reporting, archives, and lifecycle behavior. +- Designed as the scoring foundation used by companion plugins such as MobScores. diff --git a/Project.md b/Project.md index 7226a05..244784a 100644 --- a/Project.md +++ b/Project.md @@ -7,7 +7,7 @@ ## 1. What is ScoreKeeper? -ScoreKeeper is a **Paper Minecraft plugin** (Java 21, Bukkit/Adventure APIs) that manages player +ScoreKeeper is a **Paper Minecraft plugin** (Java 25, Paper/Adventure APIs) that manages player score tracking. It exposes five in-game/console commands (`/score-get`, `/score-add`, `/score-subtract`, `/score-reset`, `/score-archive`) for manual score manipulation — no events, no timers, no automation. @@ -24,11 +24,11 @@ and scoring formulas are all **future scope**. See §4 for the gap between *what | Item | Value | |------|-------| | Language | Java 21 (Gradle auto-downloads toolchain) | -| Runtime target | Paper 1.21.7 (Bukkit + Adventure APIs) | +| Runtime target | Paper 26.2 and 26.3 | | Build tool | Gradle 8.14.3 (`gradlew`) | | Linting | Spotless (`googleJavaFormat()` + license header from `config/license-header.txt`) | | Versioning | `org.danilopianini.git-sensitive-semantic-versioning`; minimum version `0.2.1`; reads `vX.Y.Z` tags | -| External deps | **None at runtime.** `paper-api:1.21.7-R0.1-SNAPSHOT` is `compileOnly` only. | +| External deps | **None at runtime.** The Paper API is `compileOnly` only. | | CI/release entry point | Run `./gradlew spotlessCheck build`, tag the release commit (for example, `git tag -a v0.2.2 -m "Release v0.2.2"`), then rebuild to produce the stable release artifact | ### Build quickly @@ -104,7 +104,7 @@ ADMIN / CONSOLE / RCON ──▶ types a /score-* command ### File: ScoreKeeperPlugin.java (`ScoreKeeperPlugin`) -- `main` class in `plugin.yml` (Bukkit plugin entry point) +- `main` class in `plugin.yml` (Paper plugin entry point) - `HashMap _playerScores` at line 38 — the sole score store - `onEnable()` (line 52): wires five command executors, logs \"load not implemented\" warning - `onDisable()` (line 46): logs \"save not implemented\" warning — scores lost on shutdown @@ -227,7 +227,7 @@ asynchronously could corrupt state via non-atomic read-modify-write. ### Run locally (Paper server) -1. Download Paper 1.21.7 from `https://papermc.io` +1. Download Paper 26.2 or 26.3 from `https://papermc.io` 2. Copy the built jar into `plugins/` 3. Start the server, verify onEnable logs: ``` diff --git a/ProjectDescription.md b/ProjectDescription.md deleted file mode 100644 index c38bff5..0000000 --- a/ProjectDescription.md +++ /dev/null @@ -1,16 +0,0 @@ -# ScoreKeeper - -ScoreKeeper is a Paper Minecraft plugin for tracking player scores during server activities, events, or games. It keeps scores per player in memory and exposes commands for viewing, changing, resetting, and archiving scores. - -## Details - -- Built for Paper API 1.21.7 with Java 21 and Gradle. -- Registers `/score-get`, `/score-add`, `/score-subtract`, `/score-reset`, and `/score-archive`. -- Commands use the executing player when a player name is omitted. -- Scores are currently held in memory and are not persisted when the server stops. -- Score archiving is planned, but the current implementation reports that archiving is unavailable. -- The project is packaged as a Java plugin with a `plugin.yml` descriptor. - -## Image - -No project image asset is included in the repository. The JSON description includes a prompt-backed image URL for a future project thumbnail. diff --git a/README.md b/README.md index 865db7b..c4cb979 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,46 @@ -# ScoreKeeper Plugin - -## Running - -### Commands - -For commands with an optional player name, players can omit it to target themselves. Console and RCON must provide a player name for score get/add/subtract/reset commands. - -* `/score-get [playerName]` - Displays the target player's score in their active bucket. -* `/score-add ` - Adds an amount to your score in your active bucket. -* `/score-add ` - Adds an amount to the target player's score. -* `/score-subtract ` - Subtracts an amount from your score in your active bucket. -* `/score-subtract ` - 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 ` - 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 ` - Archives and resets every score in one bucket. -* `/score-archive-list` - Lists saved archive IDs, newest first. -* `/score-archive-list ` - Displays the saved scores in one archive. -* `/score-bucket` - Displays your active bucket. -* `/score-bucket ` - Switches your active bucket. -* `/score-bucket create [reporting]` - Creates a bucket. Reporting is `admin`, `global`, `player`, or `none` and defaults to `none`. -* `/score-bucket ` - Switches a player's active bucket. -* `/score-bucket all ` - Changes the server's default bucket and clears individual bucket assignments. -* `/score-run start target ` - Starts a run that ends when a score reaches the target. -* `/score-run start duration