Adds build status badge.

Updated Gradle CI workflow to use newer action versions and added project version extraction step.

.env.example

@@ -1,9 +1,26 @@
-# Dev-server config for this project's tools/ scripts.
+# Configuration for tools/*.sh. Values are read as KEY=value data, not executed.
-# Plain KEY=value only (no shell expansion). Environment variables take precedence.
+# Unquoted values may contain spaces; matching outer quotes are removed.
 
+# Paper server
 PAPER_VERSION=26.2
 PAPER_BUILD=129
+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 this directory; ~/ is expanded.
+
+# Relative paths are resolved from the project root; ~/ is expanded.
 MINECRAFT_SERVER_PATH=./server
 MINECRAFT_BACKUP_PATH=./backups
+
+# Modrinth publishing
+# Release version is read from Gradle and checked against the jar's plugin.yml.
+MODRINTH_TOKEN=
+MODRINTH_PROJECT_ID=5NYwxysp
+# 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=
+MODRINTH_FILE=

.github/workflows/gradle.yml

@@ -0,0 +1,45 @@
+name: Java CI with Gradle
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    branches: [ "develop" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v6
+        with:
+          java-version: '25'
+          distribution: 'temurin'
+
+      - name: Setup Gradle 9.8.0
+        uses: gradle/actions/setup-gradle@v5
+        with:
+          gradle-version: '9.8.0'
+          cache-read-only: ${{ github.ref != 'refs/heads/develop' }}
+
+      - name: Build with Gradle Wrapper
+        run: ./tools/build-plugin.sh
+
+      - name: Extract Project Version
+        id: project_info
+        run: |
+          VERSION=$(./gradlew properties --no-daemon -q | awk -F ': ' '$1 == "version" {print $2}')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Upload Plugin Artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: ScoreKeeper-${{ steps.project_info.outputs.version }}
+          path: build/libs/*.jar
+          if-no-files-found: error
+          retention-days: 14

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.
+# Use Paper 26.2 or 26.3 only. The project helper scripts resolve the configured Paper build.
-MINECRAFT_SERVER_DOWNLOAD_URI="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar"
+MINECRAFT_SERVER_DOWNLOAD_URI=""
-MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar"
+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.
+# Use Paper 26.2 or 26.3 only. The project helper scripts resolve the configured Paper build.
-$minecraftServerDownloadUri="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar"
+$minecraftServerDownloadUri=""
-$minecraftServerJar="paper-1.21.8-25.jar"
+$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

Human-Tests.md

@@ -0,0 +1,55 @@
+# ScoreKeeper Human Testing
+
+Use this checklist on a disposable Paper 26.2 or 26.3 server. ScoreKeeper stores data in its plugin folder and interacts with online players, command senders, and scheduled high-score runs; a passing build alone does not verify these in-game workflows.
+
+## Test Setup
+
+- Use Java 25 or newer and a backed-up test server. Keep the server log available throughout testing.
+- Create at least two test players: one operator/admin and one ordinary player. Use a console or RCON session for console-sender cases.
+- Before each run, preserve `plugins/ScoreKeeper/scores.yml` and `archives.yml`, or use a fresh test server. Archive, reset, and bucket-wide commands intentionally change scores.
+- Record command sender, arguments, expected and observed messages, and score values before and after each operation.
+
+## Human Checklist
+
+### Startup and score commands
+
+- Start Paper and confirm ScoreKeeper enables, registers every documented command, and loads existing data without errors.
+- As a player, run `/score-get`, `/score-add`, `/score-subtract`, and `/score-reset`; check the displayed values and the configured initial value. Repeat with console/RCON, supplying a player name where required.
+- Try zero, negative, very large, missing, and non-numeric amounts. Confirm invalid input is handled clearly and does not unexpectedly alter a score.
+- Use two players to verify each player's score is independent. Change a player's Minecraft name if practical, then confirm their score remains associated with their UUID.
+- Check singular/plural unit labels at values of 1, 0, and multiple units, and confirm messages show the correct bucket and value.
+
+### Buckets and reporting
+
+- Create a test bucket with a nonzero initial value and distinctive singular/plural labels. Verify invalid IDs, blank labels, and duplicate IDs are rejected cleanly.
+- Switch one player to the bucket, add and subtract points, and confirm other players remain in their own active bucket. Switch back and verify the original score is unchanged.
+- Change the server-wide default with `/score-bucket all <bucketId>`. Confirm individual assignments are cleared, online players receive the appropriate change notice, and new players use the new default.
+- For each reporting policy (`none`, `player`, `admin`, `global`), change a score and verify exactly the intended audience receives the report. Test with an operator, a `scorekeeper.admin` player, an ordinary player, and the scored player.
+- Exercise bucket creation, switching, and administration as authorized and unauthorized senders. The README says archive, bucket administration, and run management require `scorekeeper.admin`; verify the behavior on the target server.
+- Note that the README says score get/add/subtract/reset currently have no permission checks and can target any online player. Confirm that exposure is acceptable for the server before enabling these commands publicly.
+
+### Archives
+
+- Archive one player's active-bucket score, then inspect `/score-archive-list` and `/score-archive-list <archiveId>`. Confirm the saved value and bucket are correct and the live score returns to that bucket's initial value.
+- Repeat for `/score-archive bucket <bucketId>` and `/score-archive all`. Confirm only the selected bucket or all buckets are archived and reset as requested.
+- Check archive IDs are listed newest first, then restart and confirm archives and their contents remain available.
+- Try an unknown archive ID or bucket ID and verify a useful failure without unrelated scores being changed.
+
+### High-score runs
+
+- Start a target-score run and a timed run using a test bucket and at least three players. Confirm the run starts with the requested top-N and reset setting.
+- Change scores for players inside and outside the current top-N. Verify individual score-change messages and global reporting for current top-N players match the run behavior.
+- End runs by reaching the target, expiration, and `/score-run stop`. Also start an `until-disabled` run and stop it manually.
+- Check final ranking order, ties, each online player's reported place, and the displayed top-N cutoff.
+- With reset enabled, verify scores begin at the bucket initial value and pre-run scores are restored after completion. With reset disabled, confirm scores remain as earned.
+- Restart while a run is active. Confirm the run and reset snapshot survive, timed runs expire at the intended time, and stopping or completing the run produces one final result rather than duplicate results.
+
+### Persistence and upgrades
+
+- Restart after changing scores, bucket definitions, reporting policies, the default bucket, and per-player bucket assignments. Verify all values and assignments persist.
+- Test a clean data folder and an existing/older `scores.yml` or `archives.yml` on a backed-up server. Confirm startup handles defaults, known legacy data, and malformed or unknown entries without silently corrupting valid data.
+- Check saved files after a clean shutdown and after a forced test restart; distinguish expected last-save behavior from data loss.
+
+## Automated Coverage
+
+There are currently no Java test sources or test dependencies in this project, and no integration-test source set. The Gradle `test` task therefore does not currently exercise ScoreKeeper behavior. All scenarios above should be treated as unverified until tested in-game; the “Ready” test tasks in `TODO.md` describe work that has not yet been added.

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.

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",

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.

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<UUID, Integer> _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:
    ```

ProjectDescription.md

@@ -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.

README.md

@@ -1,5 +1,9 @@
 # ScoreKeeper Plugin
 
+[![Java CI with Gradle](https://github.com/headhunter45/ScoreKeeper/actions/workflows/gradle.yml/badge.svg)](https://github.com/headhunter45/ScoreKeeper/actions/workflows/gradle.yml)
+
+ScoreKeeper supports Paper 26.2 and 26.3 only. Bukkit and Spigot servers are not supported.
+
 ## Running
 
 ### Commands

TODO.md

@@ -1,21 +1,3 @@
-## Migration TODOs for Paper Modernization
-
-- [x] Switch all player score storage to use UUID instead of Player as the key
-- [x] Update logger usage to use getLogger() from JavaPlugin
-- [x] Remove or modernize any old/deprecated event registration (use @EventHandler and registerEvents)
-- [x] Review and update player lookup logic to use getPlayerExact or handle case sensitivity
-- [x] Ensure all commands are properly defined in plugin.yml
-- [x] Initialize Gradle build system
-- [x] Set project metadata in build.gradle
-- [x] Add repositories and dependencies
-- [x] Configure Java version
-- [x] Ensure resource handling for plugin.yml
-- [x] Add Gradle plugins as needed (e.g., Shadow)
-- [x] Update .gitignore for Gradle
-- [x] Remove Maven files
-- [x] Update documentation and scripts
-- [x] Test the Gradle build
-
 ## Tasks
 
 |  ID   |  Status  | Title |
@@ -26,9 +8,10 @@
 | SK-04 |  Done    | Tell a player when their bucket changes. Something like "You are now tracking ${id}. You have ${score} ${plural or singular depending in score}." |
 | SK-05 |  Done    | Enable high score runs for a bucket. Admins or pugins should be able to start a run on a certain kind of score. The top n (configurable) players will have their scores reported globally for this bucket and the individual player will have their score reported to them when it changes. Scores will be optionally reset to their initialValue with the old score for this bucket saved. High score runs will have a lifetime of a target high score, a time like 4 hours or 1 week, or until-disabled. When the high score run is finished all players will be messaged a table with the top n places and their scores along with the individual user's place and score. The scores will be reset to their previous values if they were reset to their initialValue at the beginning otherwise they will be left alone. |
 | SK-06 |  Done    | Score archiving. Scores either all or within a given bucket should be able to be archived and reset to their initial value. The archived scores should be able to be listed via a command. |
-| SK-07 |  Ready   | Replace 'net.researchgate.release' with org.danilopianini.git-sensitive-semantic-versioning' for our versioning in our build.gradle file. Turn org.gradle.configuration-cache back on after this. Our current version is 0.2.1-SNAPSHOT. Use that as our default or 0.2.1 and tag the commit to update to 0.2.2. |
+| SK-07 |  Done    | Replace 'net.researchgate.release' with org.danilopianini.git-sensitive-semantic-versioning' for our versioning in our build.gradle file. Turn org.gradle.configuration-cache back on after this. Our current version is 0.2.1-SNAPSHOT. Use that as our default or 0.2.1 and tag the commit to update to 0.2.2. |
 | SK-08 |  Ready   | Add JUnit 5 test infrastructure and keep the default Gradle `test` task server-free. Use an in-memory Paper test harness such as MockBukkit for plugin lifecycle and Bukkit/Paper behavior; use Mockito only for narrow API boundaries where a harness is unnecessary. |
 | SK-09 |  Ready   | Add fast unit tests for score and bucket rules: bucket validation and duplicate IDs, initial values, UUID-isolated scores, default and per-player bucket selection, and add/subtract/reset behavior. Keep domain rules independent of a running Minecraft server. |
 | SK-10 |  Ready   | Test YAML persistence and archives using temporary plugin data directories: score/bucket/assignment round trips, active-run state, archive contents and resets, legacy score loading, and malformed or unknown stored entries. |
 | SK-11 |  Ready   | Test command validation and dispatch, reporting policies and messages, bucket-switch messages, and high-score run ranking/lifecycle (top-N ordering, ties, target/duration/manual finish, and score restoration). Use a controllable clock and in-memory scheduler where needed. |
 | SK-12 |  Ready   | Add a separate Gradle `integrationTest` source set/task only for behavior that needs a real Paper server, such as loading the built plugin jar, verifying actual command registration/dispatch, and persistence across a server restart. Run it only when explicitly requested; keep it out of the normal `test` and `build` tasks. |
+| SK-13 |  Ready   | Add a an option to `/score-get` to get the score for a specific bucket. |

build.gradle

@@ -1,5 +1,5 @@
 plugins {
-    id 'com.diffplug.spotless' version '6.22.0'
+    id 'com.diffplug.spotless' version '8.10.3'
     id 'java-library'
     id 'maven-publish'
     id 'org.danilopianini.git-sensitive-semantic-versioning' version '7.0.24'
@@ -23,7 +23,7 @@ tasks.withType(Javadoc).configureEach {
 }
 
 dependencies {
-    compileOnly 'io.papermc.paper:paper-api:1.21.7-R0.1-SNAPSHOT'
+    compileOnly 'io.papermc.paper:paper-api:26.2.build.129-stable'
 }
 
 java {
@@ -70,7 +70,7 @@ repositories {
 
 spotless {
     java {
-        googleJavaFormat('1.27.0')
+        googleJavaFormat('1.36.1')
         importOrder 'java', 'javax', 'com', 'net', 'org', ''
         licenseHeaderFile 'config/license-header.txt'
         target 'src/**/*.java'

gradle.properties

@@ -1,6 +1,5 @@
+org.gradle.configuration-cache=true
+org.gradle.daemon=true
 org.gradle.java.installations.auto-download=true
 org.gradle.java.installations.auto-detect=false
 org.gradle.java.installations.fromEnv=JAVA_HOME
-
-org.gradle.daemon=true
-org.gradle.configuration-cache=true

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/ScoreKeeperPlugin.java

@@ -27,6 +27,7 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Objects;
 import java.util.UUID;
 import java.util.logging.Level;
 
@@ -100,14 +101,16 @@ public class ScoreKeeperPlugin extends JavaPlugin {
 
   @Override
   public void onEnable() {
-    getCommand("score-get").setExecutor(new ScoreGetCommand(this));
+    Objects.requireNonNull(getCommand("score-get")).setExecutor(new ScoreGetCommand(this));
-    getCommand("score-add").setExecutor(new ScoreAddCommand(this));
+    Objects.requireNonNull(getCommand("score-add")).setExecutor(new ScoreAddCommand(this));
-    getCommand("score-subtract").setExecutor(new ScoreSubtractCommand(this));
+    Objects.requireNonNull(getCommand("score-subtract"))
-    getCommand("score-reset").setExecutor(new ScoreResetCommand(this));
+        .setExecutor(new ScoreSubtractCommand(this));
-    getCommand("score-archive").setExecutor(new ScoreArchiveCommand(this));
+    Objects.requireNonNull(getCommand("score-reset")).setExecutor(new ScoreResetCommand(this));
-    getCommand("score-archive-list").setExecutor(new ScoreArchiveListCommand(this));
+    Objects.requireNonNull(getCommand("score-archive")).setExecutor(new ScoreArchiveCommand(this));
-    getCommand("score-bucket").setExecutor(new ScoreBucketCommand(this));
+    Objects.requireNonNull(getCommand("score-archive-list"))
-    getCommand("score-run").setExecutor(new ScoreRunCommand(this));
+        .setExecutor(new ScoreArchiveListCommand(this));
+    Objects.requireNonNull(getCommand("score-bucket")).setExecutor(new ScoreBucketCommand(this));
+    Objects.requireNonNull(getCommand("score-run")).setExecutor(new ScoreRunCommand(this));
 
     _buckets.put("points", new ScoreBucket("points", "point", "points", 0));
     _bucketScores.put("points", new LinkedHashMap<>());
@@ -249,13 +252,13 @@ public class ScoreKeeperPlugin extends JavaPlugin {
     requireBucket(bucketId);
     Map<UUID, String> previousBuckets = new LinkedHashMap<>();
     for (Player player : getServer().getOnlinePlayers()) {
-      previousBuckets.put(player.getUniqueId(), getPlayerBucket(player));
+      previousBuckets.put(Objects.requireNonNull(player).getUniqueId(), getPlayerBucket(player));
     }
     _defaultBucketId = bucketId;
     _playerBuckets.clear();
     ScoreBucket bucket = requireBucket(bucketId);
     for (Player player : getServer().getOnlinePlayers()) {
-      if (!bucketId.equals(previousBuckets.get(player.getUniqueId()))) {
+      if (!bucketId.equals(previousBuckets.get(Objects.requireNonNull(player).getUniqueId()))) {
         sendBucketChangeMessage(player, bucket);
       }
     }
@@ -307,7 +310,7 @@ public class ScoreKeeperPlugin extends JavaPlugin {
 
   // region Utiilty Methods
   public void sendMessage(CommandSender reciever, Component message) {
-    reciever.sendMessage(_messagePrefix.append(message));
+    reciever.sendMessage(_messagePrefix.append(Objects.requireNonNull(message)));
   }
 
   private ScoreBucket requireBucket(String bucketId) {
@@ -404,13 +407,13 @@ public class ScoreKeeperPlugin extends JavaPlugin {
   private void reportHighScoreRunChange(
       Player player, ScoreBucket bucket, HighScoreRun run, int score) {
     String message = scoreMessage(player.getName(), bucket, score);
-    sendMessage(player, Component.text(message));
+    sendMessage(player, Component.text(Objects.requireNonNull(message)));
     List<ScoreEntry> standings = getRankedScores(bucket.getId());
     for (int place = 0; place < Math.min(run.topN, standings.size()); place++) {
       if (standings.get(place).playerId.equals(player.getUniqueId())) {
         for (Player recipient : getServer().getOnlinePlayers()) {
           if (recipient != player) {
-            sendMessage(recipient, Component.text(message));
+            sendMessage(recipient, Component.text(Objects.requireNonNull(message)));
           }
         }
         return;
@@ -455,7 +458,7 @@ public class ScoreKeeperPlugin extends JavaPlugin {
       ScoreEntry personalEntry = null;
       int personalPlace = -1;
       for (int place = 0; place < standings.size(); place++) {
-        if (standings.get(place).playerId.equals(player.getUniqueId())) {
+        if (standings.get(place).playerId.equals(Objects.requireNonNull(player).getUniqueId())) {
           personalEntry = standings.get(place);
           personalPlace = place + 1;
           break;
@@ -700,7 +703,7 @@ public class ScoreKeeperPlugin extends JavaPlugin {
     }
 
     String text = scoreMessage(player.getName(), bucket, score);
-    Component message = Component.text(text);
+    Component message = Component.text(Objects.requireNonNull(text));
     if (reporting == ScoreReporting.PLAYER) {
       sendMessage(player, message);
     } else if (reporting == ScoreReporting.GLOBAL) {
@@ -710,7 +713,8 @@ public class ScoreKeeperPlugin extends JavaPlugin {
     } else if (reporting == ScoreReporting.ADMIN) {
       logInfo(text);
       for (Player recipient : getServer().getOnlinePlayers()) {
-        if (recipient.isOp() || recipient.hasPermission("scorekeeper.admin")) {
+        if (Objects.requireNonNull(recipient).isOp()
+            || recipient.hasPermission("scorekeeper.admin")) {
           sendMessage(recipient, message);
         }
       }

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreAddCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
 import net.kyori.adventure.text.Component;
@@ -76,7 +78,8 @@ public class ScoreAddCommand implements CommandExecutor {
   }
 
   private void echoError(CommandSender sender, boolean rcon, String string) {
-    _plugin.sendMessage(sender, Component.text(string).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(string)).color(NamedTextColor.RED));
   }
 
   private void echoUsage(CommandSender sender, boolean rcon) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreArchiveCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
 import net.kyori.adventure.text.Component;
@@ -68,7 +70,8 @@ public class ScoreArchiveCommand implements CommandExecutor {
   }
 
   private void sendError(CommandSender sender, String message) {
-    _plugin.sendMessage(sender, Component.text(message).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(message)).color(NamedTextColor.RED));
   }
 
   private void sendUsage(CommandSender sender) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreBucketCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreBucket;
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreReporting;
@@ -121,7 +123,8 @@ public class ScoreBucketCommand implements CommandExecutor {
   }
 
   private void sendError(CommandSender sender, String message) {
-    _plugin.sendMessage(sender, Component.text(message).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(message)).color(NamedTextColor.RED));
   }
 
   private void sendUsage(CommandSender sender) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreGetCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
 import net.kyori.adventure.text.Component;
@@ -84,7 +86,8 @@ public class ScoreGetCommand implements CommandExecutor {
   }
 
   private void echoError(CommandSender sender, boolean rcon, String string) {
-    _plugin.sendMessage(sender, Component.text(string).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(string)).color(NamedTextColor.RED));
   }
 
   private void echoUsage(CommandSender sender, boolean rcon) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreResetCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
 import net.kyori.adventure.text.Component;
@@ -62,7 +64,8 @@ public class ScoreResetCommand implements CommandExecutor {
   }
 
   private void echoError(CommandSender sender, boolean rcon, String string) {
-    _plugin.sendMessage(sender, Component.text(string).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(string)).color(NamedTextColor.RED));
   }
 
   private void echoUsage(CommandSender sender, boolean rcon) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreRunCommand.java

@@ -18,6 +18,7 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
 import java.time.Duration;
+import java.util.Objects;
 
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
@@ -109,7 +110,8 @@ public class ScoreRunCommand implements CommandExecutor {
   }
 
   private void sendError(CommandSender sender, String message) {
-    _plugin.sendMessage(sender, Component.text(message).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(message)).color(NamedTextColor.RED));
   }
 
   private void sendUsage(CommandSender sender) {

src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/ScoreSubtractCommand.java

@@ -17,6 +17,8 @@ along with ScoreKeeper. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.minecraft.plugins.scorekeeper.commands;
 
+import java.util.Objects;
+
 import com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin;
 
 import net.kyori.adventure.text.Component;
@@ -76,7 +78,8 @@ public class ScoreSubtractCommand implements CommandExecutor {
   }
 
   private void echoError(CommandSender sender, boolean rcon, String string) {
-    _plugin.sendMessage(sender, Component.text(string).color(NamedTextColor.RED));
+    _plugin.sendMessage(
+        sender, Component.text(Objects.requireNonNull(string)).color(NamedTextColor.RED));
   }
 
   private void echoUsage(CommandSender sender, boolean rcon) {

src/main/resources/plugin.yml

@@ -1,7 +1,7 @@
 name: ScoreKeeper
 main: com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin
 version: ${version}
-api-version: 1.21
+api-version: '26.2'
 commands:
     score-get:
         description: Displays the player's score.

tools/backup-server.sh

@@ -8,8 +8,47 @@
 set -euo pipefail
 
 TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=setup-env.sh
+PROJECT_ROOT="$(cd "$TOOLS_DIR/.." && pwd)"
-source "$TOOLS_DIR/setup-env.sh"
+if [[ ! -r "$PROJECT_ROOT/.env" ]]; then
+  echo "Error: $PROJECT_ROOT/.env is missing or unreadable. Copy .env.example to .env and set its values." >&2
+  exit 1
+fi
+load_project_env() {
+  local env_line env_key env_value first_char last_char
+  while IFS= read -r env_line || [[ -n "$env_line" ]]; do
+    env_line="${env_line%$'\r'}"
+    [[ "$env_line" =~ ^[[:space:]]*(#|$) ]] && continue
+    [[ "$env_line" == *=* ]] || continue
+
+    env_key="${env_line%%=*}"
+    env_value="${env_line#*=}"
+    env_key="${env_key#"${env_key%%[![:space:]]*}"}"
+    env_key="${env_key%"${env_key##*[![:space:]]}"}"
+    [[ "$env_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    env_value="${env_value#"${env_value%%[![:space:]]*}"}"
+    env_value="${env_value%"${env_value##*[![:space:]]}"}"
+
+    if (( ${#env_value} >= 2 )); then
+      first_char="${env_value:0:1}"
+      last_char="${env_value:$((${#env_value} - 1)):1}"
+      if [[ "$first_char" == "$last_char" && ( "$first_char" == '"' || "$first_char" == "'" ) ]]; then
+        env_value="${env_value:1:$((${#env_value} - 2))}"
+      fi
+    fi
+
+    if [[ -z "${!env_key:-}" ]]; then
+      export "$env_key=$env_value"
+    fi
+  done < "$PROJECT_ROOT/.env"
+}
+load_project_env
+
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH:-MCServer}"
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_SERVER_PATH" == /* ]] || MINECRAFT_SERVER_PATH="$PROJECT_ROOT/$MINECRAFT_SERVER_PATH"
+MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH:-backups}"
+MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_BACKUP_PATH" == /* ]] || MINECRAFT_BACKUP_PATH="$PROJECT_ROOT/$MINECRAFT_BACKUP_PATH"
 
 FORCE=false
 LABEL=""

tools/deploy-plugin.sh

@@ -4,8 +4,43 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-# shellcheck source=setup-env.sh
+if [[ ! -r "$PROJECT_ROOT/.env" ]]; then
-source "$SCRIPT_DIR/setup-env.sh"
+  echo "Error: $PROJECT_ROOT/.env is missing or unreadable. Copy .env.example to .env and set its values." >&2
+  exit 1
+fi
+load_project_env() {
+  local env_line env_key env_value first_char last_char
+  while IFS= read -r env_line || [[ -n "$env_line" ]]; do
+    env_line="${env_line%$'\r'}"
+    [[ "$env_line" =~ ^[[:space:]]*(#|$) ]] && continue
+    [[ "$env_line" == *=* ]] || continue
+
+    env_key="${env_line%%=*}"
+    env_value="${env_line#*=}"
+    env_key="${env_key#"${env_key%%[![:space:]]*}"}"
+    env_key="${env_key%"${env_key##*[![:space:]]}"}"
+    [[ "$env_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    env_value="${env_value#"${env_value%%[![:space:]]*}"}"
+    env_value="${env_value%"${env_value##*[![:space:]]}"}"
+
+    if (( ${#env_value} >= 2 )); then
+      first_char="${env_value:0:1}"
+      last_char="${env_value:$((${#env_value} - 1)):1}"
+      if [[ "$first_char" == "$last_char" && ( "$first_char" == '"' || "$first_char" == "'" ) ]]; then
+        env_value="${env_value:1:$((${#env_value} - 2))}"
+      fi
+    fi
+
+    if [[ -z "${!env_key:-}" ]]; then
+      export "$env_key=$env_value"
+    fi
+  done < "$PROJECT_ROOT/.env"
+}
+load_project_env
+
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH:-MCServer}"
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_SERVER_PATH" == /* ]] || MINECRAFT_SERVER_PATH="$PROJECT_ROOT/$MINECRAFT_SERVER_PATH"
 
 if [[ -z "$MINECRAFT_SERVER_PATH" ]]; then
   echo "Error: MINECRAFT_SERVER_PATH environment variable is not set."

tools/publish-modrinth.sh

@@ -4,15 +4,44 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-# Load project config; credentials stay in the project .env.
+if [[ ! -r "$PROJECT_ROOT/.env" ]]; then
-# shellcheck source=setup-env.sh
+  echo "Error: $PROJECT_ROOT/.env is missing or unreadable. Copy .env.example to .env and set its values." >&2
-source "$SCRIPT_DIR/setup-env.sh"
+  exit 1
+fi
+load_project_env() {
+  local env_line env_key env_value first_char last_char
+  while IFS= read -r env_line || [[ -n "$env_line" ]]; do
+    env_line="${env_line%$'\r'}"
+    [[ "$env_line" =~ ^[[:space:]]*(#|$) ]] && continue
+    [[ "$env_line" == *=* ]] || continue
+
+    env_key="${env_line%%=*}"
+    env_value="${env_line#*=}"
+    env_key="${env_key#"${env_key%%[![:space:]]*}"}"
+    env_key="${env_key%"${env_key##*[![:space:]]}"}"
+    [[ "$env_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    env_value="${env_value#"${env_value%%[![:space:]]*}"}"
+    env_value="${env_value%"${env_value##*[![:space:]]}"}"
+
+    if (( ${#env_value} >= 2 )); then
+      first_char="${env_value:0:1}"
+      last_char="${env_value:$((${#env_value} - 1)):1}"
+      if [[ "$first_char" == "$last_char" && ( "$first_char" == '"' || "$first_char" == "'" ) ]]; then
+        env_value="${env_value:1:$((${#env_value} - 2))}"
+      fi
+    fi
+
+    if [[ -z "${!env_key:-}" ]]; then
+      export "$env_key=$env_value"
+    fi
+  done < "$PROJECT_ROOT/.env"
+}
+load_project_env
 
 # Required env:
 #   MODRINTH_TOKEN
-#   MODRINTH_PROJECT_ID or MODRINTH_PROJECT_SLUG
+#   MODRINTH_PROJECT_ID (project ID or slug)
-#   MODRINTH_VERSION
+#   MODRINTH_GAME_VERSIONS (optional comma-separated list; defaults to 1.21 through 1.21.7)
-#   MODRINTH_GAME_VERSIONS (optional, comma-separated list, default from project set)
 #   MODRINTH_LOADERS (optional, comma-separated, default paper)
 #   MODRINTH_CHANGELOG (optional)
 # Optional:
@@ -20,19 +49,59 @@ source "$SCRIPT_DIR/setup-env.sh"
 #   MODRINTH_FILE (optional path to the jar; defaults to build/libs/*.jar)
 
 MODRINTH_TOKEN="${MODRINTH_TOKEN:-}"
-MODRINTH_PROJECT_ID="${MODRINTH_PROJECT_ID:-${MODRINTH_PROJECT_SLUG:-5NYwxysp}}"
+MODRINTH_PROJECT_ID="${MODRINTH_PROJECT_ID:-5NYwxysp}"
-MODRINTH_VERSION="${MODRINTH_VERSION:-${VERSION:-$(grep -E '^version=' gradle.properties | head -n1 | cut -d= -f2-)}}"
+generate_changelog() {
-MODRINTH_CHANGELOG="${MODRINTH_CHANGELOG:-Auto release via publish-modrinth.sh}"
+  local current_tag previous_tag range commits
-MODRINTH_GAME_VERSIONS="${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}"
+  current_tag=$(git -C "$PROJECT_ROOT" describe --tags --exact-match HEAD 2>/dev/null || true)
+  if [[ -n "$current_tag" ]]; then
+    previous_tag=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 "${current_tag}^" 2>/dev/null || true)
+    range="${previous_tag:+$previous_tag..}$current_tag"
+  else
+    previous_tag=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 2>/dev/null || true)
+    range="${previous_tag:+$previous_tag..}HEAD"
+  fi
+  commits=$(git -C "$PROJECT_ROOT" log --no-merges --format='- %s (%h)' "$range" 2>/dev/null || true)
+  if [[ -z "$commits" ]]; then
+    commits='- No commit messages found for this release.'
+  fi
+  printf '%s\n\n%s\n' "## What's Changed" "$commits"
+}
+MODRINTH_CHANGELOG="${MODRINTH_CHANGELOG:-$(generate_changelog)}"
+MODRINTH_GAME_VERSIONS="${MODRINTH_GAME_VERSIONS:-26.2,26.3}"
 MODRINTH_LOADERS="${MODRINTH_LOADERS:-paper}"
+MODRINTH_VERSION_TYPE="${MODRINTH_VERSION_TYPE:-}"
 MODRINTH_FILE="${MODRINTH_FILE:-}"
 MODRINTH_DEPENDENCIES="${MODRINTH_DEPENDENCIES:-}"
 
+MODRINTH_VERSION=$(
+  "$PROJECT_ROOT/gradlew" -q -p "$PROJECT_ROOT" properties --property version \
+    | sed -n 's/^version: //p'
+)
+if [[ -z "$MODRINTH_VERSION" ]]; then
+  echo "Error: could not determine the project version from Gradle." >&2
+  exit 1
+fi
+if [[ -z "$MODRINTH_VERSION_TYPE" ]]; then
+  if [[ "$MODRINTH_VERSION" == *-* ]]; then
+    MODRINTH_VERSION_TYPE="beta"
+  else
+    MODRINTH_VERSION_TYPE="release"
+  fi
+fi
+case "$MODRINTH_VERSION_TYPE" in
+  release|beta|alpha) ;;
+  *) echo "Error: MODRINTH_VERSION_TYPE must be release, beta, or alpha." >&2; exit 1 ;;
+esac
+MODRINTH_VERSION_NAME="ScoreKeeper $MODRINTH_VERSION"
+
+if [[ -n "$MODRINTH_FILE" && "$MODRINTH_FILE" != /* ]]; then
+  MODRINTH_FILE="$PROJECT_ROOT/$MODRINTH_FILE"
+fi
+
 if [[ -z "$MODRINTH_TOKEN" ]]; then
   echo "Error: MODRINTH_TOKEN is not set in $PROJECT_ROOT/.env" >&2
   exit 1
 fi
-
 if [[ -z "$MODRINTH_FILE" ]]; then
   MODRINTH_FILE=$(ls -t "$PROJECT_ROOT"/build/libs/*.jar 2>/dev/null | grep -v -- '-all\.jar$' | head -n1 || true)
 fi
@@ -40,27 +109,61 @@ if [[ -z "$MODRINTH_FILE" || ! -f "$MODRINTH_FILE" ]]; then
   echo "Error: no jar found for Modrinth upload. Build the project first or set MODRINTH_FILE." >&2
   exit 1
 fi
+if ! command -v unzip >/dev/null; then
+  echo "Error: 'unzip' is required to verify the plugin version in the jar." >&2
+  exit 1
+fi
+JAR_VERSION=$(unzip -p "$MODRINTH_FILE" plugin.yml 2>/dev/null | sed -n 's/^version: //p' | head -n1 || true)
+if [[ -z "$JAR_VERSION" ]]; then
+  echo "Error: could not read the plugin version from $MODRINTH_FILE." >&2
+  exit 1
+fi
+if [[ "$JAR_VERSION" != "$MODRINTH_VERSION" ]]; then
+  echo "Error: jar version $JAR_VERSION does not match Gradle version $MODRINTH_VERSION. Rebuild the plugin and retry." >&2
+  exit 1
+fi
 
 csv_to_json_array() {
   jq -cn --arg csv "$1" '$csv | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))'
 }
 MODRINTH_GAME_VERSIONS_JSON=$(csv_to_json_array "$MODRINTH_GAME_VERSIONS")
 MODRINTH_LOADERS_JSON=$(csv_to_json_array "$MODRINTH_LOADERS")
-
 if [[ -n "$MODRINTH_DEPENDENCIES" ]]; then
-  MODRINTH_DEPENDENCIES_ARG=(--form "dependencies=$MODRINTH_DEPENDENCIES")
+  if ! MODRINTH_DEPENDENCIES_JSON=$(jq -ce 'if type == "array" then . else error("dependencies must be a JSON array") end' <<<"$MODRINTH_DEPENDENCIES"); then
+    echo "Error: MODRINTH_DEPENDENCIES must be a JSON array." >&2
+    exit 1
+  fi
 else
-  MODRINTH_DEPENDENCIES_ARG=()
+  MODRINTH_DEPENDENCIES_JSON='[]'
 fi
 
-curl -fsSL \
+MODRINTH_DATA=$(jq -cn \
-  -X POST "https://api.modrinth.com/v2/version" \
+  --arg project_id "$MODRINTH_PROJECT_ID" \
-  -H "Authorization: $MODRINTH_TOKEN" \
+  --arg name "$MODRINTH_VERSION_NAME" \
-  -F "project_id=$MODRINTH_PROJECT_ID" \
+  --arg version_number "$MODRINTH_VERSION" \
-  -F "version_number=$MODRINTH_VERSION" \
+  --arg version_type "$MODRINTH_VERSION_TYPE" \
-  -F "changelog=$MODRINTH_CHANGELOG" \
+  --arg changelog "$MODRINTH_CHANGELOG" \
-  -F "game_versions=${MODRINTH_GAME_VERSIONS_JSON}" \
+  --argjson featured false \
-  -F "loaders=${MODRINTH_LOADERS_JSON}" \
+  --argjson dependencies "$MODRINTH_DEPENDENCIES_JSON" \
-  -F "file=@$MODRINTH_FILE" \
+  --argjson game_versions "$MODRINTH_GAME_VERSIONS_JSON" \
-  "${MODRINTH_DEPENDENCIES_ARG[@]}" \
+  --argjson loaders "$MODRINTH_LOADERS_JSON" \
-  | jq .
+  '{project_id: $project_id, name: $name, version_number: $version_number, version_type: $version_type, featured: $featured, changelog: $changelog, dependencies: $dependencies, game_versions: $game_versions, loaders: $loaders, file_parts: ["file"], primary_file: "file"}')
+
+CURL_ARGS=(
+  -X POST "https://api.modrinth.com/v2/version"
+  -H "Authorization: $MODRINTH_TOKEN"
+  -F "data=$MODRINTH_DATA;type=application/json"
+  -F "file=@$MODRINTH_FILE"
+)
+
+HTTP_RESPONSE=$(curl -sS -w $'\n%{http_code}' "${CURL_ARGS[@]}")
+HTTP_STATUS="${HTTP_RESPONSE##*$'\n'}"
+HTTP_BODY="${HTTP_RESPONSE%$'\n'*}"
+if [[ "$HTTP_STATUS" != 2?? ]]; then
+  echo "Error: Modrinth API returned HTTP $HTTP_STATUS:" >&2
+  if ! printf '%s\n' "$HTTP_BODY" | jq -r '.description // .error // .' >&2; then
+    printf '%s\n' "$HTTP_BODY" >&2
+  fi
+  exit 1
+fi
+printf '%s\n' "$HTTP_BODY" | jq .

tools/restore-server.sh

@@ -9,8 +9,47 @@
 set -euo pipefail
 
 TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=setup-env.sh
+PROJECT_ROOT="$(cd "$TOOLS_DIR/.." && pwd)"
-source "$TOOLS_DIR/setup-env.sh"
+if [[ ! -r "$PROJECT_ROOT/.env" ]]; then
+  echo "Error: $PROJECT_ROOT/.env is missing or unreadable. Copy .env.example to .env and set its values." >&2
+  exit 1
+fi
+load_project_env() {
+  local env_line env_key env_value first_char last_char
+  while IFS= read -r env_line || [[ -n "$env_line" ]]; do
+    env_line="${env_line%$'\r'}"
+    [[ "$env_line" =~ ^[[:space:]]*(#|$) ]] && continue
+    [[ "$env_line" == *=* ]] || continue
+
+    env_key="${env_line%%=*}"
+    env_value="${env_line#*=}"
+    env_key="${env_key#"${env_key%%[![:space:]]*}"}"
+    env_key="${env_key%"${env_key##*[![:space:]]}"}"
+    [[ "$env_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    env_value="${env_value#"${env_value%%[![:space:]]*}"}"
+    env_value="${env_value%"${env_value##*[![:space:]]}"}"
+
+    if (( ${#env_value} >= 2 )); then
+      first_char="${env_value:0:1}"
+      last_char="${env_value:$((${#env_value} - 1)):1}"
+      if [[ "$first_char" == "$last_char" && ( "$first_char" == '"' || "$first_char" == "'" ) ]]; then
+        env_value="${env_value:1:$((${#env_value} - 2))}"
+      fi
+    fi
+
+    if [[ -z "${!env_key:-}" ]]; then
+      export "$env_key=$env_value"
+    fi
+  done < "$PROJECT_ROOT/.env"
+}
+load_project_env
+
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH:-MCServer}"
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_SERVER_PATH" == /* ]] || MINECRAFT_SERVER_PATH="$PROJECT_ROOT/$MINECRAFT_SERVER_PATH"
+MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH:-backups}"
+MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_BACKUP_PATH" == /* ]] || MINECRAFT_BACKUP_PATH="$PROJECT_ROOT/$MINECRAFT_BACKUP_PATH"
 
 ASSUME_YES=false
 SAFETY_BACKUP=true

tools/setup-env.sh

@@ -1,39 +0,0 @@
-#!/usr/bin/env bash
-# Source (bash or zsh) to export the shared server config from ../.env
-# (relative to this script):
-#   PAPER_VERSION, PAPER_BUILD, MINECRAFT_SERVER_PATH, MINECRAFT_SERVER_JAR, MINECRAFT_BACKUP_PATH
-
-_setup_env_self="${BASH_SOURCE[0]:-${(%):-%x}}"
-_setup_env_root="$(cd "$(dirname "$_setup_env_self")/.." && pwd)"
-_setup_env_file="${MINECRAFT_ENV_FILE:-$_setup_env_root/.env}"
-
-if [[ -f "$_setup_env_file" ]]; then
-  while IFS= read -r _line || [[ -n "$_line" ]]; do
-    _line="${_line%$'\r'}"
-    [[ "$_line" =~ ^[[:space:]]*(#|$) ]] && continue
-    _key="${_line%%=*}"
-    _value="${_line#*=}"
-    _key="${_key//[[:space:]]/}"
-    [[ "$_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
-    _value="${_value#\"}"; _value="${_value%\"}"
-    _value="${_value#\'}"; _value="${_value%\'}"
-    eval "_current=\"\${$_key:-}\""
-    [[ -z "$_current" ]] && export "$_key=$_value"
-  done < "$_setup_env_file"
-fi
-
-PAPER_VERSION="${PAPER_VERSION:-}"
-PAPER_BUILD="${PAPER_BUILD:-}"
-MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH:-MCServer}"
-MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH/#\~/$HOME}"
-[[ "$MINECRAFT_SERVER_PATH" == /* ]] || MINECRAFT_SERVER_PATH="$_setup_env_root/$MINECRAFT_SERVER_PATH"
-MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH:-backups}"
-MINECRAFT_BACKUP_PATH="${MINECRAFT_BACKUP_PATH/#\~/$HOME}"
-[[ "$MINECRAFT_BACKUP_PATH" == /* ]] || MINECRAFT_BACKUP_PATH="$_setup_env_root/$MINECRAFT_BACKUP_PATH"
-
-if [[ -z "${MINECRAFT_SERVER_JAR:-}" && -n "$PAPER_VERSION" && -n "$PAPER_BUILD" ]]; then
-  MINECRAFT_SERVER_JAR="paper-${PAPER_VERSION}-${PAPER_BUILD}.jar"
-fi
-
-export PAPER_VERSION PAPER_BUILD MINECRAFT_SERVER_PATH MINECRAFT_SERVER_JAR MINECRAFT_BACKUP_PATH
-unset _setup_env_self _setup_env_root _setup_env_file _line _key _value _current

tools/start-server.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Downloads (if missing) and runs a Paper server via the Fill v3 API.
-# Server settings come from ../.env relative to this script (see setup-env.sh).
+# Server settings come from the project .env file.
 #
 # Env vars:
 #   JAVA_OPTS              Extra JVM args (default: -Xms2G -Xmx2G)
@@ -8,8 +8,47 @@
 set -euo pipefail
 
 TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=setup-env.sh
+PROJECT_ROOT="$(cd "$TOOLS_DIR/.." && pwd)"
-source "$TOOLS_DIR/setup-env.sh"
+if [[ ! -r "$PROJECT_ROOT/.env" ]]; then
+  echo "Error: $PROJECT_ROOT/.env is missing or unreadable. Copy .env.example to .env and set its values." >&2
+  exit 1
+fi
+load_project_env() {
+  local env_line env_key env_value first_char last_char
+  while IFS= read -r env_line || [[ -n "$env_line" ]]; do
+    env_line="${env_line%$'\r'}"
+    [[ "$env_line" =~ ^[[:space:]]*(#|$) ]] && continue
+    [[ "$env_line" == *=* ]] || continue
+
+    env_key="${env_line%%=*}"
+    env_value="${env_line#*=}"
+    env_key="${env_key#"${env_key%%[![:space:]]*}"}"
+    env_key="${env_key%"${env_key##*[![:space:]]}"}"
+    [[ "$env_key" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    env_value="${env_value#"${env_value%%[![:space:]]*}"}"
+    env_value="${env_value%"${env_value##*[![:space:]]}"}"
+
+    if (( ${#env_value} >= 2 )); then
+      first_char="${env_value:0:1}"
+      last_char="${env_value:$((${#env_value} - 1)):1}"
+      if [[ "$first_char" == "$last_char" && ( "$first_char" == '"' || "$first_char" == "'" ) ]]; then
+        env_value="${env_value:1:$((${#env_value} - 2))}"
+      fi
+    fi
+
+    if [[ -z "${!env_key:-}" ]]; then
+      export "$env_key=$env_value"
+    fi
+  done < "$PROJECT_ROOT/.env"
+}
+load_project_env
+
+PAPER_VERSION="${PAPER_VERSION:-}"
+PAPER_BUILD="${PAPER_BUILD:-}"
+MINECRAFT_SERVER_JAR="${MINECRAFT_SERVER_JAR:-}"
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH:-MCServer}"
+MINECRAFT_SERVER_PATH="${MINECRAFT_SERVER_PATH/#\~/$HOME}"
+[[ "$MINECRAFT_SERVER_PATH" == /* ]] || MINECRAFT_SERVER_PATH="$PROJECT_ROOT/$MINECRAFT_SERVER_PATH"
 
 [[ -n "$PAPER_VERSION" ]] || { echo "Error: PAPER_VERSION is not set (see .env)." >&2; exit 1; }