feat(progress): track persistent creeper kills
This commit is contained in:
@@ -0,0 +1,46 @@
|
||||
---
|
||||
type: Architecture
|
||||
title: Creeper Fear Plugin Architecture
|
||||
description: Runtime boundaries, persistence model, and event flow for Creeper Aura progression.
|
||||
---
|
||||
|
||||
# Creeper Fear Plugin Architecture
|
||||
|
||||
## Runtime
|
||||
|
||||
Creeper Fear targets Java 17 and Spigot API 26.2. The plugin entry point owns listeners, commands, player feedback, configuration, and a progression service.
|
||||
|
||||
## Progression model
|
||||
|
||||
Each known player is identified by UUID and has:
|
||||
|
||||
- a last-known player name for administrative lookup;
|
||||
- a current rank (`LOCKED`, `I`, `II`, `III`, `IV`, `V`, or `VI`);
|
||||
- a non-negative number of creeper kills earned within the current tier.
|
||||
|
||||
A qualifying kill increments current-tier progress. Unlocking the next rank resets that progress to zero. Rank VI accumulates no further progress. Lifetime kill totals are deliberately not retained.
|
||||
|
||||
## Persistence and threading
|
||||
|
||||
SQLite stores player progression in the plugin data directory. Gameplay listeners submit persistence work to a dedicated single-thread executor so database latency does not block the Minecraft server thread. Bukkit API state is captured before work leaves the server thread and is not accessed by persistence workers.
|
||||
|
||||
Player progress is loaded into an online cache before synchronous aura decisions. Offline administrative operations use the same serialized persistence boundary.
|
||||
|
||||
## Event flow
|
||||
|
||||
A creeper death is attributed to a player when the player directly dealt the final damage or is attributable through a projectile or owned tameable. The progression service deduplicates a creeper death and records one point.
|
||||
|
||||
For explosions, player damage events establish whether an unlocked player would have been hit before armor mitigation. Each protected player receives their own rank multiplier. If any aura activates, the corresponding creeper explosion's affected block list is cleared for everyone. Rank VI cancels the player's damage event entirely.
|
||||
|
||||
## Commands and configuration
|
||||
|
||||
`/creeperaura` exposes player progress and permission-protected offline administration. Rank requirements, multipliers, feedback duration, and messages are loaded from YAML. Valid command-based changes are written back to YAML and survive restart.
|
||||
|
||||
## Verification
|
||||
|
||||
Domain and persistence behavior is exercised through public interfaces with JUnit. Bukkit-facing adapters remain thin, while build verification ensures their compatibility with Spigot API 26.2.
|
||||
|
||||
## Related
|
||||
|
||||
- [Design index](index.md)
|
||||
- [User stories](user-stories/index.md)
|
||||
@@ -12,4 +12,5 @@ This bundle documents a Spigot plugin in which players earn Creeper Aura ranks b
|
||||
## Explore
|
||||
|
||||
- [User stories](user-stories/index.md)
|
||||
- [Plugin architecture](architecture.md)
|
||||
- [Design log](log.md)
|
||||
|
||||
@@ -11,3 +11,6 @@ description: Chronological record of material changes to the Spigot Creeper Fear
|
||||
- Established the OKF v0.1 design bundle.
|
||||
- Defined creeper-kill progression, six Creeper Aura ranks, explosion protection, player feedback, administration, configuration, and build/release stories.
|
||||
- Selected Spigot API 26.2 and Java 17 to match the neighboring `spigot-event-producer` project.
|
||||
- Replaced lifetime cumulative kill tracking with a persisted rank and current-tier progress model.
|
||||
- Added the initial plugin architecture.
|
||||
- Completed US-001 with asynchronous SQLite current-tier progress, direct and indirect kill attribution, bounded death deduplication, and automated tests.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-001: Track creeper defeats"
|
||||
description: Record persistent player progress from creeper kills attributable to the player.
|
||||
status: backlog
|
||||
description: Record persistent current-tier progress from creeper kills attributable to the player.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-001: Track creeper defeats
|
||||
@@ -11,15 +11,19 @@ As a **player**, I want my qualifying creeper kills recorded so that my Creeper
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] A creeper kill attributable to a player adds one kill to that player's lifetime progress.
|
||||
- [ ] Direct melee kills and indirect kills attributable to the player, including projectiles and the player's tamed wolves, count.
|
||||
- [ ] A single creeper death cannot award progress more than once.
|
||||
- [ ] Progress is stored using the player's UUID rather than their mutable name.
|
||||
- [ ] Progress survives logout, server restarts, and player-name changes.
|
||||
- [ ] Progress updates are persisted without blocking the Minecraft server thread on slow storage work.
|
||||
- [ ] Missing or invalid persisted data is handled safely and reported to server administrators.
|
||||
- [x] A creeper kill attributable to a player adds one point to that player's current-tier progress.
|
||||
- [x] Direct melee kills and indirect kills attributable to the player, including projectiles and the player's tamed wolves, count.
|
||||
- [x] A single creeper death cannot award progress more than once.
|
||||
- [x] Progress is stored using the player's UUID rather than their mutable name.
|
||||
- [x] The player's current rank and current-tier progress are persisted separately.
|
||||
- [x] Lifetime creeper-kill totals are not retained.
|
||||
- [x] Rank VI does not accumulate further progress.
|
||||
- [x] Progress survives logout, server restarts, and player-name changes.
|
||||
- [x] Progress updates are persisted without blocking the Minecraft server thread on slow storage work.
|
||||
- [x] Missing or invalid persisted data is handled safely and reported to server administrators.
|
||||
|
||||
## Related
|
||||
|
||||
- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md)
|
||||
- [Plugin architecture](../architecture.md)
|
||||
- [User-story catalog](index.md)
|
||||
|
||||
@@ -11,19 +11,20 @@ As a **player**, I want Creeper Aura to become stronger as I defeat creepers so
|
||||
|
||||
## Default progression
|
||||
|
||||
| State | Required lifetime kills | Damage to protected player | Creeper block damage |
|
||||
| Current state | Kills needed to unlock next rank | Damage to protected player | Creeper block damage |
|
||||
| --- | ---: | ---: | --- |
|
||||
| Locked | 0–99 | 1× | Normal |
|
||||
| Creeper Aura I | 100 | 3× | Prevented |
|
||||
| Creeper Aura II | 200 | 2× | Prevented |
|
||||
| Creeper Aura III | 300 | 1.5× | Prevented |
|
||||
| Creeper Aura IV | 400 | 1× | Prevented |
|
||||
| Creeper Aura V | 500 | 0.5× | Prevented |
|
||||
| Creeper Aura VI | 600 | 0× | Prevented |
|
||||
| Locked | 100 to unlock I | 1× | Normal |
|
||||
| Creeper Aura I | 100 to unlock II | 3× | Prevented |
|
||||
| Creeper Aura II | 100 to unlock III | 2× | Prevented |
|
||||
| Creeper Aura III | 100 to unlock IV | 1.5× | Prevented |
|
||||
| Creeper Aura IV | 100 to unlock V | 1× | Prevented |
|
||||
| Creeper Aura V | 100 to unlock VI | 0.5× | Prevented |
|
||||
| Creeper Aura VI | Maximum rank | 0× | Prevented |
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] A player unlocks ranks according to the configured cumulative kill thresholds.
|
||||
- [ ] A player unlocks the next rank after earning the configured number of kills within their current tier.
|
||||
- [ ] Unlocking a rank resets current-tier progress to zero.
|
||||
- [ ] A player below rank I receives normal creeper explosion behavior.
|
||||
- [ ] An aura activates when an unlocked player would have been hit by the creeper explosion, even when armor or another modifier would reduce the eventual damage to zero.
|
||||
- [ ] An activated aura prevents that creeper explosion from breaking or removing blocks for everyone affected by the explosion.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-003: Show progression and rank advancement"
|
||||
description: Give players brief kill progress displays and prominent rank-up notifications.
|
||||
description: Give players brief current-tier progress displays and prominent rank-up notifications.
|
||||
status: backlog
|
||||
---
|
||||
|
||||
@@ -12,15 +12,14 @@ As a **player**, I want visible progress and rank-up notifications so that I und
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] After each qualifying creeper kill, a temporary boss bar shows the player's current state and progress toward the next rank.
|
||||
- [ ] A locked player sees progress toward Creeper Aura I.
|
||||
- [ ] A ranked player sees their current Roman-numeral rank, current kill total, and the next threshold.
|
||||
- [ ] A locked player sees current-tier progress toward Creeper Aura I.
|
||||
- [ ] A ranked player sees their current Roman-numeral rank, current-tier progress, and the next rank requirement.
|
||||
- [ ] The display duration is configurable and defaults to a short period measured in seconds.
|
||||
- [ ] The boss bar is hidden automatically when its display period expires.
|
||||
- [ ] A rank VI player no longer sees a progress boss bar.
|
||||
- [ ] Each newly attained rank displays a full-screen title naming the rank.
|
||||
- [ ] Joining the server does not replay a previously acknowledged rank-up title.
|
||||
- [ ] Administrative progress changes update the display state of an online affected player.
|
||||
- [ ] When one progress event satisfies multiple ranks, the resulting rank and notification behavior is deterministic and tested.
|
||||
- [ ] Administrative changes update an online player's boss bar if it is currently visible.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-004: Check personal progress"
|
||||
description: Let players request their current Creeper Aura status through a command.
|
||||
description: Let players request their current Creeper Aura rank and tier progress through a command.
|
||||
status: backlog
|
||||
---
|
||||
|
||||
@@ -11,8 +11,8 @@ As a **player**, I want a command that reports my Creeper Aura progress so that
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `/creeperaura progress` reports the player's lifetime creeper kills and current locked or ranked state.
|
||||
- [ ] Before rank VI, the response reports the next rank threshold and the number of additional kills needed.
|
||||
- [ ] `/creeperaura progress` reports the player's current locked or ranked state and current-tier progress.
|
||||
- [ ] Before rank VI, the response reports the next rank requirement and the number of additional kills needed.
|
||||
- [ ] At rank VI, the response clearly reports that progression is complete.
|
||||
- [ ] The self-service command is available to ordinary players without administrative permission.
|
||||
- [ ] Console use, invalid arguments, and unavailable player data produce clear responses.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-005: Administer player progression"
|
||||
description: Let authorized administrators inspect and modify online or offline player progression.
|
||||
description: Let authorized administrators inspect and modify online or offline player rank and tier progress.
|
||||
status: backlog
|
||||
---
|
||||
|
||||
@@ -11,13 +11,15 @@ As a **server administrator**, I want to inspect and modify player progress so t
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `/creeperaura progress <player>` reports another player's kills, rank, next threshold, and remaining kills.
|
||||
- [ ] `/creeperaura set <player> <kills>` sets a non-negative lifetime kill total and reconciles the player's rank to that explicit administrative value.
|
||||
- [ ] `/creeperaura add <player> <kills>` adjusts a player's kill total without allowing a negative result.
|
||||
- [ ] `/creeperaura progress <player>` reports another player's rank, current-tier progress, next requirement, and remaining kills.
|
||||
- [ ] `/creeperaura set <player> <progress>` sets a non-negative current-tier progress value without implicitly changing rank.
|
||||
- [ ] `/creeperaura add <player> <progress>` adjusts current-tier progress without allowing a negative result.
|
||||
- [ ] `/creeperaura rank <player> <locked|I|II|III|IV|V|VI>` explicitly changes rank and resets current-tier progress to zero.
|
||||
- [ ] Rank VI never retains current-tier progress.
|
||||
- [ ] Inspection and modification work for known offline players as well as online players.
|
||||
- [ ] Players are resolved to stored UUIDs so name changes do not create duplicate progression records.
|
||||
- [ ] Administrative changes are persisted immediately.
|
||||
- [ ] An online affected player's boss bar and rank state are updated after a change.
|
||||
- [ ] An online affected player's feedback and aura state are updated after a change.
|
||||
- [ ] Administrative commands require distinct, documented permissions suitable for inspection and modification.
|
||||
- [ ] Unauthorized use does not disclose another player's progression.
|
||||
- [ ] Invalid player names, ambiguous identities, invalid numbers, and storage failures produce clear responses without partial changes.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-006: Configure aura progression"
|
||||
description: Let administrators safely configure and persist aura thresholds, multipliers, and feedback.
|
||||
description: Let administrators safely configure and persist per-rank requirements, multipliers, and feedback.
|
||||
status: backlog
|
||||
---
|
||||
|
||||
@@ -11,17 +11,17 @@ As a **server administrator**, I want to configure progression and aura behavior
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Configuration provides documented defaults for all six cumulative kill thresholds and damage multipliers.
|
||||
- [ ] Rank thresholds are non-negative and strictly increasing.
|
||||
- [ ] Configuration provides documented defaults for the six per-rank kill requirements and six unlocked-rank damage multipliers.
|
||||
- [ ] Rank requirements are positive integers.
|
||||
- [ ] Damage multipliers are finite and non-negative.
|
||||
- [ ] Progress boss-bar duration and player-facing rank messages are configurable.
|
||||
- [ ] `/creeperaura threshold <rank> <kills>` validates, applies, and persists a threshold change.
|
||||
- [ ] `/creeperaura threshold <rank> <points>` validates, applies, and persists the points required to unlock that rank.
|
||||
- [ ] `/creeperaura reload` safely loads externally edited configuration without requiring a server restart.
|
||||
- [ ] Threshold-management and reload commands require documented administrative permissions.
|
||||
- [ ] Invalid configuration is rejected with actionable diagnostics while the last valid configuration remains active.
|
||||
- [ ] Changing thresholds never automatically removes an already unlocked rank or grants a new rank immediately.
|
||||
- [ ] After a threshold change, the player's next qualifying kill evaluates newly satisfied progression and can grant the next eligible rank immediately.
|
||||
- [ ] Existing progress within the player's retained rank is displayed against the updated next threshold.
|
||||
- [ ] Changing requirements never automatically removes an unlocked rank, grants a new rank, or discards current-tier progress.
|
||||
- [ ] After a requirement change, the player's next qualifying kill can grant at most the next rank when its requirement is satisfied.
|
||||
- [ ] Rank advancement resets current-tier progress to zero rather than carrying excess progress forward.
|
||||
- [ ] Configuration-command changes survive plugin and server restarts.
|
||||
|
||||
## Related
|
||||
|
||||
Reference in New Issue
Block a user