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)