167 lines
8.4 KiB
Markdown
167 lines
8.4 KiB
Markdown
# ScoreKeeper — Plugin Integration & Event/Command Reference
|
|
|
|
> Analysis for the ScoreKeeper codebase. Scope: how the plugin hooks into the
|
|
> Minecraft (Paper) server runtime — event listeners, command registrations,
|
|
> scheduled/tick logic, and inter-plugin/API surface — with a table mapping each
|
|
> trigger → handler class → effect on score data.
|
|
>
|
|
> Platform: **Paper** (`io.papermc.paper:paper-api:1.21.7-R0.1-SNAPSHOT`), Java 21,
|
|
> Gradle. Main class: `com.majinnaibu.minecraft.plugins.scorekeeper.ScoreKeeperPlugin`.
|
|
|
|
---
|
|
|
|
## 1. TL;DR for a new developer
|
|
|
|
ScoreKeeper is almost entirely **command-driven**. It registers **no Bukkit event
|
|
listeners**, declares **no `@EventHandler` methods, no `Listener` implementations,
|
|
and calls `getPluginManager().registerEvents(...)` nowhere**. It also schedules
|
|
**no timed tasks** (no `BukkitScheduler`/`BukkitRunnable`/tick logic).
|
|
|
|
The only things that touch score state are **five console/chat commands**
|
|
(`score-get`, `score-add`, `score-subtract`, `score-reset`, `score-archive`).
|
|
Score state lives in an **in-memory `HashMap<UUID, Integer>`** and is **not
|
|
persisted** — `onEnable`/`onDisable` have `TODO` stubs, so data is lost on restart.
|
|
|
|
There is a **`highscore` / high-score table in the project name and the task
|
|
prompt, but no such command or logic exists yet** — it is unimplemented.
|
|
|
|
---
|
|
|
|
## 2. Event listeners (Bukkit/Adventure)
|
|
|
|
**None.** The plugin listens to no server events. Confirmed by absence of any of:
|
|
`@EventHandler`, `implements Listener`, `registerEvents(`, `PlayerJoinEvent`,
|
|
`PlayerQuitEvent`, `PlayerDeathEvent`, or any other event import/registration.
|
|
|
|
| Server event | Handler | Effect on score data |
|
|
|---|---|---|
|
|
| PlayerJoin | *none* | none |
|
|
| PlayerQuit | *none* | none |
|
|
| PlayerDeath | *none* | none |
|
|
| (all other Bukkit events) | *none* | none |
|
|
| Custom/plugin-injected events | *none* | none |
|
|
|
|
**Implication:** nothing about a player's score changes as a result of gameplay
|
|
events (joining, quitting, dying, scoring points in-game, etc.). The only way
|
|
score data changes is through the commands in §3.
|
|
|
|
---
|
|
|
|
## 3. Command registrations & permissions
|
|
|
|
Commands are declared in `src/main/resources/plugin.yml` (no `aliases`, no
|
|
`permissions:` block, and no per-command `permission:` — so **every command is
|
|
available to every sender with no permission gating**). Each is wired to an
|
|
executor in `ScoreKeeperPlugin.onEnable()`.
|
|
|
|
Argument-resolution idiom shared by every handler:
|
|
`boolean rcon = !(sender instanceof Player);` — an RCON caller has no self
|
|
context, so the "target = self" shortcut is unavailable and a `<playerName>`
|
|
must be supplied.
|
|
|
|
`<playerName>` is resolved with `server.getPlayerExact(name)` — an **exact,
|
|
case-sensitive lookup of currently-online players only**. Score operations
|
|
therefore apply to **online players**, and an unknown/offline name yields a
|
|
"Can't find a player with that name" error (except where noted).
|
|
|
|
### Reference table — command → handler class → effect on score data
|
|
|
|
| Trigger (command) | Usage | Handler class | Delegates to | Effect on score data |
|
|
|---|---|---|---|---|
|
|
| `score-get` | `/score-get [player]` | `ScoreGetCommand` | `ScoreKeeperPlugin.getScore(Player)` → `getPlayerScore` | **Read only.** Returns the player's current score. Side effect: lazily registers the player at `0` if unseen. No persistent change. |
|
|
| `score-add` | `/score-add [player] <amount>` | `ScoreAddCommand` | `ScoreKeeperPlugin.addScore(Player,int)` | `score = old + amount` (integer `amount` in `[1..]`). |
|
|
| `score-subtract` | `/score-subtract [player] <amount>` | `ScoreSubtractCommand` | `ScoreKeeperPlugin.subtractScore(Player,int)` | `score = old - amount` (can go negative). |
|
|
| `score-reset` | `/score-reset [player]` | `ScoreResetCommand` | `ScoreKeeperPlugin.resetScore(Player)` | `score = 0` (writes 0; key created if absent). |
|
|
| `score-archive` | `/score-archive [player]` | `ScoreArchiveCommand` | *nothing* | **No state change.** Handler prints `"archive command unimplemented"`. It does **not** call `ScoreKeeperPlugin.archiveScore(...)` — see §5. |
|
|
|
|
### Command behaviour details
|
|
|
|
- **Sender vs. target.** Single-arg form means "operate on the invoking player"
|
|
(`split.length == 1` → `targetPlayer = sender`). Two-arg form means
|
|
`<playerName> <amount>` (add/subtract) or `<playerName>` (get/reset). For an
|
|
RCON sender, the single-arg form is treated as missing a target and prints
|
|
usage instead.
|
|
- **Amount parsing.** `score-add`/`score-subtract` require an integer
|
|
`amount`; a non-integer prints `"amount must be an integer"`.
|
|
- **Error/usage messaging.** `echoError` (red) and `echoUsage` (colour-coded)
|
|
differ between player and RCON call sites (`/score-add` vs `score-add`).
|
|
All handlers `return true` (command handled).
|
|
- **Permissions.** None declared → no operator/permission requirement; any
|
|
player or RCON can run them.
|
|
|
|
---
|
|
|
|
## 4. Scheduled tasks / tick-based logic
|
|
|
|
**None.** Confirmed by absence of `getScheduler()`, `runTask`,
|
|
`BukkitRunnable`, `BukkitTask`, `scheduleSync*`, or any periodic/repeating
|
|
logic. ScoreKeeper runs no background or tick-driven work.
|
|
|
|
---
|
|
|
|
## 5. Inter-plugin dependencies & API exposure
|
|
|
|
- **Declared dependencies:** plugin.yml has no `depend`, `softdepend`, `load`,
|
|
or `load-before` → **no declared inter-plugin coupling**.
|
|
- **Build dependency:** the only third-party dependency is
|
|
`io.papermc.paper:paper-api` (marked `compileOnly`, and explicitly ignored as a
|
|
snapshot by the release plugin). No other plugin/API is referenced.
|
|
- **Public API surface.** `ScoreKeeperPlugin` is a plain `JavaPlugin` exposing
|
|
`public` methods that other plugins *could* call if they hold a reference:
|
|
- `void addScore(Player, int)`
|
|
- `void subtractScore(Player, int)`
|
|
- `int getScore(Player)`
|
|
- `void setScore(Player, int)` — **public but used by no command** (internal
|
|
write path; the only writer not reachable via a command).
|
|
- `void resetScore(Player)`
|
|
- `void archiveScore(Player)` — **public but called by nothing**; it only logs
|
|
a warning. The `/score-archive` command does **not** invoke it.
|
|
- `void sendMessage(CommandSender, Component)`, `logInfo/logWarning/logError`
|
|
- **No formal service registration.** There is no `registerService`/`asService`
|
|
(ServiceLoader), no dedicated API artifact, and no `api:` block in plugin.yml.
|
|
Exposure is by **public method surface only** — informal and not discoverable
|
|
by other plugins.
|
|
- **Persistence (unimplemented).** `onEnable` logs a warning that load-from-file
|
|
is unimplemented; `onDisable` logs that save-to-file is unimplemented. The
|
|
`HashMap<UUID,Integer>` is the sole state store and is **forgotten on restart**.
|
|
|
|
---
|
|
|
|
## 6. Lifecycle
|
|
|
|
| Hook | What it does |
|
|
|---|---|
|
|
| `onEnable()` | Wires the five `score-*` command executors; logs the "load not implemented" warning and an enable log line. |
|
|
| `onDisable()` | Logs the "save not implemented" warning. **All in-memory scores are lost on shutdown.** |
|
|
|
|
---
|
|
|
|
## 7. State model (quick reference)
|
|
|
|
- **Store:** `private HashMap<UUID,Integer> _playerScores` on `ScoreKeeperPlugin`
|
|
(one map field for the whole plugin).
|
|
- **Keying:** by `Player.getUniqueId()` (UUID), so scores are per-player and
|
|
survive name changes *within a single server run*; lost on restart.
|
|
- **Lazy init:** any read (including `get`/`score-get`) auto-creates the key at `0`.
|
|
- **Writers:** `addScore`, `subtractScore`, `resetScore`, `setScore`, all funneled
|
|
through `setPlayerScore(player, value)`.
|
|
- **Concurrency:** plain `HashMap`; safe today only because command dispatch
|
|
runs on the server's main thread. Not thread-safe for off-thread use.
|
|
|
|
---
|
|
|
|
## 8. "Which server trigger causes which state change" — summary
|
|
|
|
| Trigger | State change |
|
|
|---|---|
|
|
| `/score-add [player] <amount>` | `_playerScores[uuid] += amount` |
|
|
| `/score-subtract [player] <amount>` | `_playerScores[uuid] -= amount` |
|
|
| `/score-reset [player]` | `_playerScores[uuid] = 0` |
|
|
| `/score-get [player]` | none (reads; lazily registers at 0) |
|
|
| `/score-archive [player]` | none (not implemented) |
|
|
| Any Minecraft/Bukkit event (join/quit/death/etc.) | **none — no listeners exist** |
|
|
| Server tick / scheduled task | **none — no scheduler exists** |
|
|
| Server enable | no data change (registration + log only) |
|
|
| Server disable | in-memory scores discarded (no persistence) |
|
|
| `addScore`/`subtractScore`/`setScore`/`archiveScore` via the public API | same table where called; only reachable by code holding a plugin reference, not by in-game events or commands (except add/subtract/reset which do have commands) |
|