ScoreKeeper/Project.md

ScoreKeeper — Project Reference

Purpose of this document. A fast reference for the team so anyone can understand what ScoreKeeper is, how it is built, and what is and isn't done — without having to read the whole codebase first. Read this before touching the code. Source: everything here is grounded in the current code (see "Where things live" / "Status") and the repo's own docs (README.md, CONTRIBUTING.md, TODO.md, .cursor/plans/Modernize.md). Treat the code as the single source of truth where any doc disagrees.

---

1. What this project is

ScoreKeeper is a Minecraft server plugin (Bukkit / PaperMC plugin API) that tracks a numeric score for each player and is intended to keep a high-score table. It is a small, early-stage Java plugin.

• It is a plugin for a Minecraft server (Paper/Spigot/Bukkit). It runs on the server and exposes in-game commands.
• Core capability today: record, read, add, subtract, and reset a player's score via in-game commands.
• Intended future capability: a "High Scores" table that persists scores (see §6 — this part is not implemented yet).

Audience / job-to-be-done: server admins and other plugins should be able to adjust and read player scores. The authors intend the mutating commands to be admin-oriented and expect that, eventually, another plugin will call the score methods directly rather than having players run the commands themselves (see README.md). Permissions to back that are not yet implemented (§6).

License: AGPL-3.0. Every Java file must carry the AGPL-3.0 license header (the header text lives in config/license-header.txt and is enforced by Spotless — §5).

---

2. Tech stack & key facts

Item	Value	Source
Language	Java	—
Java version	Java 21, via Gradle Java Toolchains	build.gradle, gradle.properties
Server API	PaperMC (io.papermc.paper:paper-api), 1.21.7-R0.1-SNAPSHOT	build.gradle
Plugin API version (runtime)	1.21	src/main/resources/plugin.yml
Build tool	Gradle 8.14.3 via wrapper (./gradlew / gradlew.bat)	gradle/wrapper/...
Plugin version	0.2.2-SNAPSHOT	gradle.properties
Group / coordinates	com.majinnaibu.minecraft.plugins / ScoreKeeper	build.gradle
Output artifact	build/libs/ScoreKeeper-<version>.jar	build.gradle
Format/lint	Spotless (Google Java Format)	build.gradle
Releases	net.researchgate.release plugin	build.gradle
Repo remote	git@github.com:headhunter45/ScoreKeeper.git	git remote -v

Java toolchain / "automatic JDK download"

gradle.properties sets org.gradle.java.installations.auto-download=true, and settings.gradle applies the Foojay resolver plugin (org.gradle.toolchains.foojay-resolver-convention). Together these let Gradle auto-download a Java 21 JDK when one isn't present, so a developer doesn't have to hand-install a JDK just to build. (The plugin also still recommends installing JDK 21 — see CONTRIBUTING.md.)

⚠️ Version caveat — read this before building

The Paper API version is pinned to 1.21.7 in build.gradle, but README.md / CONTRIBUTING.md reference a 1.21.8 server jar (paper-1.21.8-25.jar). These don't match yet. Confirm which MC/Paper version is the target before treating either number as authoritative. Everything else in this doc is safe; this one mismatch is a real gotcha.

---

3. Commands

The plugin registers five commands, all declared in plugin.yml and all backed by a dedicated CommandExecutor class. Each executor takes ScoreKeeperPlugin via its constructor (dependency injection by hand), talks to the plugin through its public methods, and replies with adventure Component messages (colored text).

Command	plugin.yml usage	What it does	Handler class
/score-get	[playerName]	Shows a player's current score	ScoreGetCommand
/score-add	[playerName] <amount>	Adds points to a player's score	ScoreAddCommand
/score-subtract	[playerName] <amount>	Subtracts points	ScoreSubtractCommand
/score-reset	[playerName]	Resets a player's score to 0	ScoreResetCommand
/score-archive	[playerName]	Unimplemented — prints "archive command unimplemented"	ScoreArchiveCommand

Behavior notes (read these):

• [playerName] is optional for in-game players. If a player omits the name, the command acts on the executor/invoker themselves.
• RCON / console callers must always pass a player name — there is no "self", so the executors print usage and refuse.
• Player lookup uses getServer().getPlayerExact(name), which only matches online players by exact name. Offline / unknown names produce "Can't find a player with that name" — this is a known limitation the team has noted (see Modernize.md / §6).
• Amounts are parsed with Integer.parseInt; non-integer amounts produce "amount must be an integer" and do not change anything.
• Messages are prefixed with a colored [ScoreKeeper] banner (_messagePrefix), and log lines are prefixed with [ScoreKeeper] (_logPrefix).
• All mutating commands are admin-oriented (per README.md), but there is no permission check yet (§6).

---

4. Architecture

4.1 Where things live

ScoreKeeper/
├── build.gradle              # build config, plugins, deps, spotless, release
├── settings.gradle           # project name + Foojay (toolchain auto-download)
├── gradle.properties         # version + auto-download flag
├── config/license-header.txt # AGPL header enforced on all .java files
├── tools/
│   ├── bash/                 # build-plugin.sh, deploy-plugin.sh, start/stop-server.sh
│   └── powershell/           # same 4 scripts, .ps1 form (Windows)
├── .cursor/plans/Modernize.md# old modernization checklist (see §6)
└── src/main/
    ├── java/com/majinnaibu/minecraft/plugins/scorekeeper/
    │   ├── ScoreKeeperPlugin.java   # plugin entry point + score store + methods
    │   └── commands/                # one CommandExecutor per command
    │       ├── ScoreAddCommand.java
    │       ├── ScoreGetCommand.java
    │       ├── ScoreSubtractCommand.java
    │       ├── ScoreResetCommand.java
    │       └── ScoreArchiveCommand.java
    └── resources/
        └── plugin.yml            # plugin metadata + command declarations

4.2 The one core class

ScoreKeeperPlugin (extends JavaPlugin) is the heart of the plugin:

• Score store: HashMap<UUID, Integer> _playerScores — keyed by the player's UUID (not name — this was a deliberate modernization, see §6). An unknown player is lazily seeded to 0.
• Public command surface (what the command classes call): addScore, subtractScore, getScore, resetScore, setScore, archiveScore.
• Lifecycle:
  • onEnable() wires up all five executors (getCommand("score-…").setExecutor(new …(this))) and logs that it's on.
  • onDisable() currently does nothing except log a warning.
• Logging helpers: logInfo, logWarning, logError (all via getLogger() with the [ScoreKeeper] prefix).
• Messaging: sendMessage(CommandSender, Component), which prepends the [ScoreKeeper] prefix component.

4.3 Data flow

player/rcon ──► /score-* ──► <Name>Command.onCommand()
                              │  parse args, find Player via getPlayerExact
                              ▼
                     ScoreKeeperPlugin.addScore / getScore / ...
                              │  read/write HashMap<UUID,Integer>
                              ▼
                     reply via sendMessage() (adventure Component, colored)

There is no external storage today — the map is in-memory only.

---

5. Build, test, and deploy

5.1 Build

• Linux/macOS (and WSL): ./gradlew build
• Windows: .\gradlew.bat build
• Produces build/libs/ScoreKeeper-<version>.jar (version comes from gradle.properties).
• Wrappers exist for the common tasks:
  • tools/bash/build-plugin.sh / tools/powershell/Build-Plugin.ps1
  • tools/bash/deploy-plugin.sh / tools/powershell/Deploy-Plugin.ps1
  • tools/bash/start-server.sh / tools/powershell/Start-Server.ps1
  • tools/bash/stop-server.sh / tools/powershell/Stop-Server.ps1

5.2 Spotless (format + license check)

The build.gradle configures Spotless with googleJavaFormat(), removeUnusedImports(), a fixed import order (java, javax, com, net, org, ''), and the AGPL license header. release binds spotlessCheck before build, so formatting is enforced on release. Run ./gradlew spotlessApply to auto-format before committing; a bad format will fail the build.

5.3 Deploy & server scripts

The helper scripts operate on two environment variables you must set:

• MINECRAFT_SERVER_PATH — root dir of your Paper server.
• MINECRAFT_SERVER_JAR — the server jar filename relative to that path.

start-server launches the Paper server; stop-server kills it; deploy-plugin copies the newest build/libs/*.jar into the server's plugins/ dir (and warns if the jar is older than your source files). Full setup, including the EULA step and client connection, is in CONTRIBUTING.md.

5.4 Releases

The net.researchgate.release plugin drives versioning: it reads/writes the version from gradle.properties, builds spotlessCheck + build, tags releases as v$version, and reverts the version bump on failure (revertOnFail = true).

5.5 What's NOT tested

There are no automated tests in the repo and no test task is configured. "Testing" today means running the plugin on a local Paper server via the scripts above. This is a candidate for the team to add (CI, e.g. Minebench/PaperTests, is a reasonable first step).

Note: this reference document was authored without running a build. To confirm the build is green, run ./gradlew build on a dev machine (requires network to fetch the Paper API + toolchain JDK on first run) and confirm the jar in build/libs loads on a Paper 1.21.x server.

---

6. Status & known gaps (what is / isn't done)

This is the most useful section for the team — it captures what the project-aspirations say vs. what the code actually does.

6.1 What is done

Area	State
Five in-game commands (/score-*)	✅ Wired up and functional for get/add/subtract/reset
Per-player UUID-keyed score store	✅ In-memory HashMap<UUID,Integer>
Modern Paper API, no deprecations	✅ getPlayerExact, getLogger(), @... (no legacy event code in active path)
Java 21 + auto-download toolchain	✅
Gradle build + wrapper + release plugin + Spotless	✅
Bash + PowerShell dev scripts	✅
License headers on all .java	✅ (enforced by Spotless)

6.2 What is NOT done (in code, not just doc)

These are the real "high score table" features the README aspires to but the code doesn't yet do:

Gap	Where it shows up	Notes
/score-archive unimplemented	ScoreArchiveCommand.onCommand just sends "archive command unimplemented"; ScoreKeeperPlugin.archiveScore only logs a warning	This is the central "high scores" feature and it's a stub
No persistence on save	onDisable() logs logWarning("Unable to save scores to file. This feature is not implemented yet.")	All scores lost on restart or /score-archive today
No persistence on load	onEnable() logs logWarning("Unable to load scores from file. ...")	Same feature, load side
No permissions / access control	No permission fields in plugin.yml, no hasPermission check in any executor	README.md states the mutating commands should be admin-only; that isn't enforced yet
No automated tests	No test sources / test task	Testing is manual on a running server
Case-sensitive offline lookup	getPlayerExact(name) returns null for offline players	Noted in Modernize.md; players must be online to be looked up by name

Important re: "High Scores table" in the README. The README advertises /score-archive as "Saves the player's score to a 'High Scores' table and resets their current score to 0." That table does not exist yet. The command and the archive method are both stubs. Do not assume it works. When a teammate asks "does the high-score table exist?", the honest answer today is: no, it's planned and stubbed out.

6.3 Historical / superseded docs

• .cursor/plans/Modernize.md is a pre-migration plan (Maven → Gradle, Player key → UUID, old event registration → modern, etc.). The substantive modernization is mostly done and merged — the TODO checklist at the top of that file is checked, and the current code reflects it. Treat the appendix (API comparisons, Gradle-vs-Maven notes) as background only.
• TODO.md (the "Migration TODOs for Paper Modernization") is similarly mostly checked — the migration is effectively complete. It is a historical artifact for the modernization effort, not the active roadmap.
• README.md "Permissions support is coming AFTER I get archive to work." This line still reflects the original intent and remains true: archive is still not worked, permissions are still not there.

6.4 Suggested next steps (open, not committed)

These are candidates — not a decision; surface in grooming/planning:

1. Implement archive + a real high-scores table with on-disk persistence (the obvious first product step).
2. Reconcile the 1.21.7 vs 1.21.8 version question (see §2).
3. Add a basic permission check on the mutating commands (score-add, score-subtract, score-reset, and later score-archive).
4. Introduce a lightweight test harness for the score store and command parsing (the pure-logic portions of the *Command classes are amenable to unit tests even without a running server).
5. Decide offline lookup strategy — getPlayerExact requires the player to be online.

---

7. Conventions & gotchas

• Formatting: Spotless with Google Java Format. Run ./gradlew spotlessApply before committing.
• License header: Every .java file must start with the AGPL-3.0 block from config/license-header.txt. Spotless enforces it.
• Log vs. message: logInfo/logWarning/logError write server-side logs (with [ScoreKeeper] prefix). sendMessage sends colored in-chat messages from the [ScoreKeeper] banner.
• Command design: each <Name>Command class is the pattern. To add a new command: add an entry to plugin.yml, write a CommandExecutor in src/main/java/.../commands/, register it in ScoreKeeperPlugin.onEnable, and expose any new behavior via a new public method on ScoreKeeperPlugin.
• UUID, not name, is the key. All internal storage is by UUID. Names are only used at the command edge.
• Adventure Component, not raw strings. Messages are built with net.kyori.adventure.text.Component; new messages should follow suit.
• Dev scripts use env vars. MINECRAFT_SERVER_PATH and MINECRAFT_SERVER_JAR must be set for the tools/ scripts to work. See CONTRIBUTING.md for the full setup.
• Naming: the plugin's own coordinates, package, and group are com.majinnaibu.*; the public GitHub repo is headhunter45/ScoreKeeper. If a teammate is confused by the two names, this is why.

---

8. Where to read next

Read this to	Open
Understand the original intent / use the plugin	README.md
Set up a dev environment	CONTRIBUTING.md
See the original modernization plan (historical)	.cursor/plans/Modernize.md
See the original migration TODO list (historical)	TODO.md
Understand a specific command's behavior	src/main/java/.../commands/*.java
Understand the plugin's core logic	src/main/java/.../ScoreKeeperPlugin.java
Understand what the build does	build.gradle, settings.gradle, gradle.properties
Understand the command declarations	src/main/resources/plugin.yml
See the license	LICENSE, config/license-header.txt

---

This document is a living reference. When you learn something new about the project, update it — keep it honest (what's done vs. planned), and cite the source file when something is non-obvious.