docs(design): define creeper aura plugin
This commit is contained in:
@@ -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)
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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 <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.
|
||||
- [ ] 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)
|
||||
@@ -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 <rank> <kills>` 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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user