docs(design): define spawn plugin user stories

2026-08-08 13:03:11 -04:00
commit a01f36db86
11 changed files with 291 additions and 0 deletions
@@ -0,0 +1,15 @@
 ---
 type: Index
 title: Trigger Spawn Design
 description: Entry point for the Trigger Spawn OKF knowledge bundle.
 okf_version: "0.1"
 ---
 # Trigger Spawn Design
 This bundle documents the player progression, teleportation, administration, persistence, configuration, and delivery requirements for the Trigger Spawn Spigot plugin.
 ## Explore
 - [User stories](user-stories/index.md)
 - [Design log](log.md)
@@ -0,0 +1,22 @@
 ---
 type: Log
 title: Trigger Spawn Design Log
 description: Chronological record of significant Trigger Spawn design decisions.
 ---
 # Trigger Spawn Design Log
 ## 2026-08-08 — Initial user stories
 - Target Spigot 26.2 and Java 17 with a Gradle and Gitea Actions pipeline modeled on `spigot-event-producer`.
 - Unlock `/spawn` after the first observed Warden, Ender Dragon, or Wither kill.
 - Use real elapsed time for cooldowns, with defaults of eight, four, and one hour as unique boss kills accumulate.
 - Support administrator-defined cooldown grants, complete access resets, and bans.
 - Maintain a separate circular spawn area in each world, with a default radius of 20 blocks and safe randomized destinations.
 - Require a stationary three-second warm-up that is cancelled by walking to another block, jumping, falling, teleportation, or world changes.
 ## 2026-08-08 — Progression reminders and rewards
 - Remind players with incomplete progression that remaining unique boss kills permanently reduce the `/spawn` cooldown.
 - Clear the active cooldown immediately after each newly credited unique boss kill.
 - When cooldown prevents `/spawn`, explicitly report that it is unavailable and show the remaining wait in a friendly format.
@@ -0,0 +1,16 @@
 ---
 type: Index
 title: Trigger Spawn User Stories
 description: Catalog of user stories for the Trigger Spawn Spigot plugin.
 ---
 # Trigger Spawn User Stories
 1. [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 2. [US-002: Teleport safely to spawn](us-002-teleport-safely-to-spawn.md)
 3. [US-003: Configure each world's spawn area](us-003-configure-world-spawn-area.md)
 4. [US-004: Grant and remove spawn access](us-004-manage-spawn-access.md)
 5. [US-005: Ban and unban spawn access](us-005-manage-spawn-bans.md)
 6. [US-006: Configure plugin behavior](us-006-configure-plugin-behavior.md)
 7. [US-007: Build and release the plugin](us-007-build-and-release-plugin.md)
 8. [US-008: Reward and encourage spawn progression](us-008-reward-spawn-progression.md)
@@ -0,0 +1,31 @@
 ---
 type: User Story
 title: "US-001: Earn progressive spawn access"
 description: Let players unlock spawn teleportation and improve its cooldown by defeating dangerous enemies.
 status: backlog
 ---
 # US-001: Earn progressive spawn access
 As a **player**, I want to unlock `/spawn` by defeating major enemies so that my progression earns increasingly convenient access to spawn.
 ## Acceptance criteria
 - [ ] The plugin observes player-attributed kills of the Warden, Ender Dragon, and Wither.
 - [ ] Only kills observed while the plugin is operating count; historical statistics and advancements are not imported.
 - [ ] The three enemies may be killed in any order.
 - [ ] The first unique qualifying kill unlocks `/spawn` with the configured one-kill cooldown, which defaults to 8 hours.
 - [ ] The second unique qualifying kill applies the configured two-kill cooldown, which defaults to 4 hours.
 - [ ] The third unique qualifying kill applies the configured three-kill cooldown, which defaults to 1 hour.
 - [ ] Repeated kills of an already credited enemy do not improve the player's tier.
 - [ ] Each newly credited kill displays an on-screen message stating that `/spawn` has been unlocked or updated, is immediately available, and has the shown applicable cooldown.
 - [ ] Progress is presented as a checklist in which credited enemies have a green check and uncredited enemies have a red cross.
 - [ ] Each newly credited unique kill immediately clears any active `/spawn` cooldown as a progression reward.
 - [ ] Progress is associated with the player's UUID and survives server and plugin restarts.
 ## Related
 - [US-002: Teleport safely to spawn](us-002-teleport-safely-to-spawn.md)
 - [US-004: Grant and remove spawn access](us-004-manage-spawn-access.md)
 - [US-005: Ban and unban spawn access](us-005-manage-spawn-bans.md)
 - [US-008: Reward and encourage spawn progression](us-008-reward-spawn-progression.md)
@@ -0,0 +1,37 @@
 ---
 type: User Story
 title: "US-002: Teleport safely to spawn"
 description: Let eligible players teleport to a safe randomized location in their current world's spawn area after a stationary warm-up.
 status: backlog
 ---
 # US-002: Teleport safely to spawn
 As an **eligible player**, I want `/spawn` to take me safely to my current world's spawn area so that I can return without exposing myself to an unsafe destination.
 ## Acceptance criteria
 - [ ] `/spawn` is available after at least one qualifying unique enemy kill or an administrative grant.
 - [ ] A player without access receives a message instructing them to defeat a Warden, Ender Dragon, or Wither and sees the colored progress checklist.
 - [ ] A banned player cannot begin a spawn teleport.
 - [ ] When an active cooldown prevents `/spawn`, the player is explicitly told that the command is unavailable and sees the remaining wait in a friendly duration format.
 - [ ] Cooldowns use real elapsed time and therefore continue while the player is offline.
 - [ ] An accepted teleport request starts a three-second on-screen countdown.
 - [ ] The player may look around during the countdown without cancelling it.
 - [ ] A change to the player's block X, Y, or Z coordinate cancels the countdown, including walking to another block, jumping, or falling.
 - [ ] Teleportation or a world change during the countdown cancels it.
 - [ ] The destination is sampled randomly within the circular spawn area configured for the player's current world.
 - [ ] The destination provides non-hazardous solid ground, two blocks of clear headroom, and no immediate lava, fire, water, void, or other configured environmental hazard.
 - [ ] Unsafe underwater, leaf-top, inaccessible Nether-roof, and void-exposed destinations are rejected.
 - [ ] The safe search prefers a valid vertical position closest to the configured spawn center's elevation rather than automatically preferring the world's highest surface.
 - [ ] The safe-location search uses a bounded number of attempts and reports failure clearly when no destination is found.
 - [ ] Only a completed teleport starts the applicable cooldown.
 - [ ] After a completed teleport, a player with unfinished boss progression is reminded that defeating each remaining unique boss permanently reduces the cooldown.
 - [ ] A cancelled countdown or failed safe-location search does not consume the cooldown.
 ## Related
 - [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 - [US-003: Configure each world's spawn area](us-003-configure-world-spawn-area.md)
 - [US-006: Configure plugin behavior](us-006-configure-plugin-behavior.md)
 - [US-008: Reward and encourage spawn progression](us-008-reward-spawn-progression.md)
@@ -0,0 +1,29 @@
 ---
 type: User Story
 title: "US-003: Configure each world's spawn area"
 description: Let administrators define an independent center and circular safe-spawn radius for every world.
 status: backlog
 ---
 # US-003: Configure each world's spawn area
 As a **server administrator**, I want to configure the spawn area independently in each world so that `/spawn` sends players to an appropriate safe area in their current world.
 ## Acceptance criteria
 - [ ] Every world has an independent spawn center and maximum spawn distance.
 - [ ] Until an administrator sets a custom center, a world uses its native world spawn point.
 - [ ] `/spawnadmin set` stores the executing administrator's current world, coordinates, yaw, and pitch as that world's center and facing direction.
 - [ ] `/spawnadmin distance <blocks>` sets the current world's maximum spawn distance in blocks.
 - [ ] `/spawnadmin info` displays the current world's effective center, whether it is native or custom, and maximum distance.
 - [ ] The default maximum spawn distance is 20 blocks.
 - [ ] The spawn area is circular, and random horizontal points are sampled uniformly by area within its radius.
 - [ ] A maximum distance of `0` targets the configured center and adjusts it to the nearest safe block.
 - [ ] Negative, non-numeric, or otherwise invalid distances are rejected with an explanatory message.
 - [ ] Random destinations use the center's saved yaw and pitch.
 - [ ] Per-world centers and distances survive server and plugin restarts.
 ## Related
 - [US-002: Teleport safely to spawn](us-002-teleport-safely-to-spawn.md)
 - [US-006: Configure plugin behavior](us-006-configure-plugin-behavior.md)
@@ -0,0 +1,30 @@
 ---
 type: User Story
 title: "US-004: Grant and remove spawn access"
 description: Let administrators grant custom spawn cooldowns, inspect access, and completely reset a player's access.
 status: backlog
 ---
 # US-004: Grant and remove spawn access
 As a **server administrator**, I want to grant, inspect, and remove spawn access so that I can manage exceptions independently of boss progression.
 ## Acceptance criteria
 - [ ] `/spawnadmin grant <player> <duration>` grants immediate `/spawn` access with the supplied cooldown.
 - [ ] Friendly, case-insensitive duration units are accepted, including values such as `30m`, `2h`, and `1d`.
 - [ ] Zero, negative, malformed, or overflowing grant durations are rejected with an explanatory message.
 - [ ] A custom administrative grant overrides the player's boss-based cooldown tier while the grant exists.
 - [ ] Killing qualifying enemies does not replace an active administrative grant's custom cooldown.
 - [ ] `/spawnadmin remove <player>` removes any administrative grant, recorded enemy progress, and active cooldown from the player.
 - [ ] After removal, the player begins with no access and can earn it again by defeating a qualifying enemy.
 - [ ] `/spawnadmin access [page]` lists all players who currently have natural or granted access, including offline players.
 - [ ] Each access-list entry identifies the player, access source, applicable cooldown, progression tier when relevant, and current remaining cooldown.
 - [ ] Administrative player arguments support online players and previously known offline players when they can be resolved safely.
 - [ ] Player state is stored by UUID while retaining the latest known player name for display and lookup.
 ## Related
 - [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 - [US-005: Ban and unban spawn access](us-005-manage-spawn-bans.md)
 - [US-006: Configure plugin behavior](us-006-configure-plugin-behavior.md)
@@ -0,0 +1,27 @@
 ---
 type: User Story
 title: "US-005: Ban and unban spawn access"
 description: Let administrators prevent selected players from using or reacquiring spawn teleportation until unbanned.
 status: backlog
 ---
 # US-005: Ban and unban spawn access
 As a **server administrator**, I want to ban and unban players from spawn teleportation so that access can be withheld regardless of progression or grants.
 ## Acceptance criteria
 - [ ] `/spawnadmin ban <player>` immediately prevents the player from using `/spawn`.
 - [ ] Banning a player clears their administrative grant, enemy progress, and active cooldown.
 - [ ] Qualifying kills made while banned are not recorded.
 - [ ] A banned player cannot receive an administrative grant until unbanned.
 - [ ] `/spawnadmin bans [page]` displays a paginated list of banned players, including offline players.
 - [ ] `/spawnadmin unban <player>` removes the ban without restoring any prior grant, enemy progress, or cooldown.
 - [ ] An unbanned player begins with no access and can earn access again by defeating a qualifying enemy or receiving a new grant.
 - [ ] Ban and unban commands support online players and previously known offline players when they can be resolved safely.
 - [ ] Ban state is associated with player UUIDs and survives server and plugin restarts.
 ## Related
 - [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 - [US-004: Grant and remove spawn access](us-004-manage-spawn-access.md)
@@ -0,0 +1,31 @@
 ---
 type: User Story
 title: "US-006: Configure plugin behavior"
 description: Let operators tune cooldown tiers and run the plugin with clear validation, messages, permissions, and durable state.
 status: backlog
 ---
 # US-006: Configure plugin behavior
 As a **server operator**, I want safe configuration and durable state so that Trigger Spawn behaves predictably across worlds and restarts.
 ## Acceptance criteria
 - [ ] The one-kill cooldown is independently configurable and defaults to 28,800 seconds.
 - [ ] The two-kill cooldown is independently configurable and defaults to 14,400 seconds.
 - [ ] The three-kill cooldown is independently configurable and defaults to 3,600 seconds.
 - [ ] Configured cooldowns must be positive and representable safely by the plugin.
 - [ ] Invalid required configuration prevents partial initialization and produces a clear server log message.
 - [ ] Player-facing messages use clear built-in wording, readable colors, and friendly duration formatting.
 - [ ] Ordinary players do not require a plugin permission node to execute `/spawn`; eligibility is controlled by progression, grants, cooldowns, and bans.
 - [ ] Administrative commands require `triggerspawn.admin`.
 - [ ] Server operators receive `triggerspawn.admin` by default.
 - [ ] Boss progress, grants, bans, cooldown timestamps, latest known names, and per-world spawn settings persist across clean restarts.
 - [ ] Persisted data is handled defensively so corrupt or invalid records do not silently grant access.
 ## Related
 - [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 - [US-003: Configure each world's spawn area](us-003-configure-world-spawn-area.md)
 - [US-004: Grant and remove spawn access](us-004-manage-spawn-access.md)
 - [US-005: Ban and unban spawn access](us-005-manage-spawn-bans.md)
@@ -0,0 +1,25 @@
 ---
 type: User Story
 title: "US-007: Build and release the plugin"
 description: Give maintainers repeatable Spigot 26.2 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 against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain.
 - [ ] Automated JUnit 5 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.
 - [ ] The build and release workflow follows the established `spigot-event-producer` project pattern where applicable.
 ## Related
 - [User-story catalog](index.md)
@@ -0,0 +1,28 @@
 ---
 type: User Story
 title: "US-008: Reward and encourage spawn progression"
 description: Remind players how to improve spawn access and reward each newly credited unique boss kill with an immediate cooldown reset.
 status: backlog
 ---
 # US-008: Reward and encourage spawn progression
 As a **player**, I want `/spawn` to explain how I can improve its cooldown and reward new boss progress so that the benefit of defeating each remaining boss is clear and immediately useful.
 ## Acceptance criteria
 - [ ] After every successful `/spawn`, a player who has not defeated all three unique qualifying enemies receives a reminder that defeating the remaining bosses permanently reduces the cooldown.
 - [ ] The reminder identifies the remaining eligible bosses and shows the next cooldown tier.
 - [ ] A player who has completed all three unique qualifying kills does not receive the progression reminder.
 - [ ] Each newly credited unique Warden, Ender Dragon, or Wither kill immediately clears the player's active `/spawn` cooldown.
 - [ ] Clearing the cooldown makes `/spawn` immediately available as a progression reward.
 - [ ] The newly credited kill also permanently applies the improved boss-based cooldown tier.
 - [ ] Repeated kills of an already credited enemy do not clear the cooldown.
 - [ ] The on-screen kill message states that `/spawn` is immediately available and displays the new cooldown tier.
 - [ ] Banned players cannot earn kill credit, a cooldown reset, or an improved tier.
 ## Related
 - [US-001: Earn progressive spawn access](us-001-earn-progressive-spawn-access.md)
 - [US-002: Teleport safely to spawn](us-002-teleport-safely-to-spawn.md)
 - [US-005: Ban and unban spawn access](us-005-manage-spawn-bans.md)