From f9ad2d9461c7b1375e1a3a8ecefe78393c68e8d2 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Sat, 8 Aug 2026 13:44:14 -0400 Subject: [PATCH] docs(design): define creeper aura plugin --- design/index.md | 15 +++++++ design/log.md | 13 ++++++ design/user-stories/index.md | 15 +++++++ .../us-001-track-creeper-defeats.md | 25 +++++++++++ .../us-002-unlock-creeper-aura-ranks.md | 41 +++++++++++++++++++ ...3-show-progression-and-rank-advancement.md | 29 +++++++++++++ .../us-004-check-personal-progress.md | 25 +++++++++++ .../us-005-administer-player-progression.md | 30 ++++++++++++++ .../us-006-configure-aura-progression.md | 31 ++++++++++++++ .../us-007-build-and-release-plugin.md | 26 ++++++++++++ 10 files changed, 250 insertions(+) create mode 100644 design/index.md create mode 100644 design/log.md create mode 100644 design/user-stories/index.md create mode 100644 design/user-stories/us-001-track-creeper-defeats.md create mode 100644 design/user-stories/us-002-unlock-creeper-aura-ranks.md create mode 100644 design/user-stories/us-003-show-progression-and-rank-advancement.md create mode 100644 design/user-stories/us-004-check-personal-progress.md create mode 100644 design/user-stories/us-005-administer-player-progression.md create mode 100644 design/user-stories/us-006-configure-aura-progression.md create mode 100644 design/user-stories/us-007-build-and-release-plugin.md diff --git a/design/index.md b/design/index.md new file mode 100644 index 0000000..b144377 --- /dev/null +++ b/design/index.md @@ -0,0 +1,15 @@ +--- +type: Index +title: Spigot Creeper Fear Design +description: Entry point for the Spigot Creeper Fear OKF knowledge bundle. +okf_version: "0.1" +--- + +# Spigot Creeper Fear Design + +This bundle documents a Spigot plugin in which players earn Creeper Aura ranks by defeating creepers. Unlocked ranks prevent eligible creeper explosions from breaking blocks while changing the damage dealt to protected players. + +## Explore + +- [User stories](user-stories/index.md) +- [Design log](log.md) diff --git a/design/log.md b/design/log.md new file mode 100644 index 0000000..4146595 --- /dev/null +++ b/design/log.md @@ -0,0 +1,13 @@ +--- +type: Log +title: Design Log +description: Chronological record of material changes to the Spigot Creeper Fear design bundle. +--- + +# Design Log + +## 2026-08-08 + +- 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. diff --git a/design/user-stories/index.md b/design/user-stories/index.md new file mode 100644 index 0000000..bf1870f --- /dev/null +++ b/design/user-stories/index.md @@ -0,0 +1,15 @@ +--- +type: Index +title: Creeper Fear User Stories +description: Catalog of user stories for the Spigot Creeper Fear plugin. +--- + +# User Stories + +- [US-001: Track creeper defeats](us-001-track-creeper-defeats.md) +- [US-002: Unlock Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) +- [US-003: Show progression and rank advancement](us-003-show-progression-and-rank-advancement.md) +- [US-004: Check personal progress](us-004-check-personal-progress.md) +- [US-005: Administer player progression](us-005-administer-player-progression.md) +- [US-006: Configure aura progression](us-006-configure-aura-progression.md) +- [US-007: Build and release the plugin](us-007-build-and-release-plugin.md) diff --git a/design/user-stories/us-001-track-creeper-defeats.md b/design/user-stories/us-001-track-creeper-defeats.md new file mode 100644 index 0000000..1145277 --- /dev/null +++ b/design/user-stories/us-001-track-creeper-defeats.md @@ -0,0 +1,25 @@ +--- +type: User Story +title: "US-001: Track creeper defeats" +description: Record persistent player progress from creeper kills attributable to the player. +status: backlog +--- + +# US-001: Track creeper defeats + +As a **player**, I want my qualifying creeper kills recorded so that my Creeper Aura progression persists. + +## 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. + +## Related + +- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-002-unlock-creeper-aura-ranks.md b/design/user-stories/us-002-unlock-creeper-aura-ranks.md new file mode 100644 index 0000000..0e25633 --- /dev/null +++ b/design/user-stories/us-002-unlock-creeper-aura-ranks.md @@ -0,0 +1,41 @@ +--- +type: User Story +title: "US-002: Unlock Creeper Aura ranks" +description: Protect blocks and modify creeper damage according to a player's earned aura rank. +status: backlog +--- + +# US-002: Unlock Creeper Aura ranks + +As a **player**, I want Creeper Aura to become stronger as I defeat creepers so that I progressively master their explosions. + +## Default progression + +| State | Required lifetime kills | 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 | + +## Acceptance criteria + +- [ ] A player unlocks ranks according to the configured cumulative kill thresholds. +- [ ] 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. +- [ ] Other nearby players and entities continue to receive their normal creeper explosion effects unless they have their own aura damage modifier. +- [ ] The protected player's rank multiplier is applied to vanilla creeper explosion damage before armor, enchantments, resistance, and difficulty mitigation. +- [ ] At rank VI, the protected player's creeper explosion damage event is cancelled so that damage and knockback are nullified. +- [ ] Charged creepers obey the same aura rules while retaining their vanilla base explosion strength. +- [ ] Explosions from TNT, beds, respawn anchors, and non-creeper entities are unchanged. +- [ ] Simultaneous exposure of players with different aura ranks is deterministic and tested. + +## Related + +- [Track creeper defeats](us-001-track-creeper-defeats.md) +- [Configure aura progression](us-006-configure-aura-progression.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-003-show-progression-and-rank-advancement.md b/design/user-stories/us-003-show-progression-and-rank-advancement.md new file mode 100644 index 0000000..ffbce9a --- /dev/null +++ b/design/user-stories/us-003-show-progression-and-rank-advancement.md @@ -0,0 +1,29 @@ +--- +type: User Story +title: "US-003: Show progression and rank advancement" +description: Give players brief kill progress displays and prominent rank-up notifications. +status: backlog +--- + +# US-003: Show progression and rank advancement + +As a **player**, I want visible progress and rank-up notifications so that I understand my advancement without persistent screen clutter. + +## 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. +- [ ] 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. + +## Related + +- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) +- [Check personal progress](us-004-check-personal-progress.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-004-check-personal-progress.md b/design/user-stories/us-004-check-personal-progress.md new file mode 100644 index 0000000..1aaf193 --- /dev/null +++ b/design/user-stories/us-004-check-personal-progress.md @@ -0,0 +1,25 @@ +--- +type: User Story +title: "US-004: Check personal progress" +description: Let players request their current Creeper Aura status through a command. +status: backlog +--- + +# US-004: Check personal progress + +As a **player**, I want a command that reports my Creeper Aura progress so that I can check it at any time. + +## 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. +- [ ] 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. +- [ ] Command usage is included in plugin help and command metadata. + +## Related + +- [Show progression and rank advancement](us-003-show-progression-and-rank-advancement.md) +- [Administer player progression](us-005-administer-player-progression.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-005-administer-player-progression.md b/design/user-stories/us-005-administer-player-progression.md new file mode 100644 index 0000000..944a57e --- /dev/null +++ b/design/user-stories/us-005-administer-player-progression.md @@ -0,0 +1,30 @@ +--- +type: User Story +title: "US-005: Administer player progression" +description: Let authorized administrators inspect and modify online or offline player progression. +status: backlog +--- + +# US-005: Administer player progression + +As a **server administrator**, I want to inspect and modify player progress so that I can support players and correct mistakes. + +## Acceptance criteria + +- [ ] `/creeperaura progress ` reports another player's kills, rank, next threshold, and remaining kills. +- [ ] `/creeperaura set ` sets a non-negative lifetime kill total and reconciles the player's rank to that explicit administrative value. +- [ ] `/creeperaura add ` adjusts a player's kill total without allowing a negative result. +- [ ] 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. +- [ ] 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. +- [ ] Successful administrative changes are written to the server log with the actor, target, old value, and new value. + +## Related + +- [Check personal progress](us-004-check-personal-progress.md) +- [Configure aura progression](us-006-configure-aura-progression.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-006-configure-aura-progression.md b/design/user-stories/us-006-configure-aura-progression.md new file mode 100644 index 0000000..9441398 --- /dev/null +++ b/design/user-stories/us-006-configure-aura-progression.md @@ -0,0 +1,31 @@ +--- +type: User Story +title: "US-006: Configure aura progression" +description: Let administrators safely configure and persist aura thresholds, multipliers, and feedback. +status: backlog +--- + +# US-006: Configure aura progression + +As a **server administrator**, I want to configure progression and aura behavior so that it fits my server's balance. + +## Acceptance criteria + +- [ ] Configuration provides documented defaults for all six cumulative kill thresholds and damage multipliers. +- [ ] Rank thresholds are non-negative and strictly increasing. +- [ ] Damage multipliers are finite and non-negative. +- [ ] Progress boss-bar duration and player-facing rank messages are configurable. +- [ ] `/creeperaura threshold ` validates, applies, and persists a threshold change. +- [ ] `/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. +- [ ] Configuration-command changes survive plugin and server restarts. + +## Related + +- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) +- [Administer player progression](us-005-administer-player-progression.md) +- [User-story catalog](index.md) diff --git a/design/user-stories/us-007-build-and-release-plugin.md b/design/user-stories/us-007-build-and-release-plugin.md new file mode 100644 index 0000000..3e3eec2 --- /dev/null +++ b/design/user-stories/us-007-build-and-release-plugin.md @@ -0,0 +1,26 @@ +--- +type: User Story +title: "US-007: Build and release the plugin" +description: Give maintainers repeatable Java builds, automated verification, and versioned Gitea releases. +status: backlog +--- + +# US-007: Build and release the plugin + +As a **plugin maintainer**, I want automated builds and releases so that tested, correctly versioned plugin artifacts can be distributed consistently. + +## Acceptance criteria + +- [ ] The Gradle project compiles with Java 17 against Spigot API 26.2. +- [ ] Automated tests run as part of the Gradle `check` lifecycle. +- [ ] Pushes and pull requests build and test the plugin in Gitea Actions. +- [ ] Pull requests validate conventional commit messages. +- [ ] CI stores a development JAR as a workflow artifact. +- [ ] Main-branch conventional commits drive semantic versioning. +- [ ] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release. +- [ ] Build, installation, command, permission, configuration, and release procedures are documented. + +## Related + +- [User-story catalog](index.md) +- [Design index](../index.md)