From a01f36db86a402963b41e8b12bf5bbf47a74ba7f Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Sat, 8 Aug 2026 13:03:11 -0400 Subject: [PATCH] docs(design): define spawn plugin user stories --- design/index.md | 15 ++++++++ design/log.md | 22 +++++++++++ design/user-stories/index.md | 16 ++++++++ .../us-001-earn-progressive-spawn-access.md | 31 ++++++++++++++++ .../us-002-teleport-safely-to-spawn.md | 37 +++++++++++++++++++ .../us-003-configure-world-spawn-area.md | 29 +++++++++++++++ .../us-004-manage-spawn-access.md | 30 +++++++++++++++ .../user-stories/us-005-manage-spawn-bans.md | 27 ++++++++++++++ .../us-006-configure-plugin-behavior.md | 31 ++++++++++++++++ .../us-007-build-and-release-plugin.md | 25 +++++++++++++ .../us-008-reward-spawn-progression.md | 28 ++++++++++++++ 11 files changed, 291 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-earn-progressive-spawn-access.md create mode 100644 design/user-stories/us-002-teleport-safely-to-spawn.md create mode 100644 design/user-stories/us-003-configure-world-spawn-area.md create mode 100644 design/user-stories/us-004-manage-spawn-access.md create mode 100644 design/user-stories/us-005-manage-spawn-bans.md create mode 100644 design/user-stories/us-006-configure-plugin-behavior.md create mode 100644 design/user-stories/us-007-build-and-release-plugin.md create mode 100644 design/user-stories/us-008-reward-spawn-progression.md diff --git a/design/index.md b/design/index.md new file mode 100644 index 0000000..bf68121 --- /dev/null +++ b/design/index.md @@ -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) diff --git a/design/log.md b/design/log.md new file mode 100644 index 0000000..5e3c397 --- /dev/null +++ b/design/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. diff --git a/design/user-stories/index.md b/design/user-stories/index.md new file mode 100644 index 0000000..9abd66d --- /dev/null +++ b/design/user-stories/index.md @@ -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) diff --git a/design/user-stories/us-001-earn-progressive-spawn-access.md b/design/user-stories/us-001-earn-progressive-spawn-access.md new file mode 100644 index 0000000..dadf7f9 --- /dev/null +++ b/design/user-stories/us-001-earn-progressive-spawn-access.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) diff --git a/design/user-stories/us-002-teleport-safely-to-spawn.md b/design/user-stories/us-002-teleport-safely-to-spawn.md new file mode 100644 index 0000000..37d45e5 --- /dev/null +++ b/design/user-stories/us-002-teleport-safely-to-spawn.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) diff --git a/design/user-stories/us-003-configure-world-spawn-area.md b/design/user-stories/us-003-configure-world-spawn-area.md new file mode 100644 index 0000000..2bf5066 --- /dev/null +++ b/design/user-stories/us-003-configure-world-spawn-area.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 ` 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) diff --git a/design/user-stories/us-004-manage-spawn-access.md b/design/user-stories/us-004-manage-spawn-access.md new file mode 100644 index 0000000..d5d8131 --- /dev/null +++ b/design/user-stories/us-004-manage-spawn-access.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 ` 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 ` 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) diff --git a/design/user-stories/us-005-manage-spawn-bans.md b/design/user-stories/us-005-manage-spawn-bans.md new file mode 100644 index 0000000..26e28ce --- /dev/null +++ b/design/user-stories/us-005-manage-spawn-bans.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 ` 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 ` 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) diff --git a/design/user-stories/us-006-configure-plugin-behavior.md b/design/user-stories/us-006-configure-plugin-behavior.md new file mode 100644 index 0000000..0a87f2b --- /dev/null +++ b/design/user-stories/us-006-configure-plugin-behavior.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) 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..872071c --- /dev/null +++ b/design/user-stories/us-007-build-and-release-plugin.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) diff --git a/design/user-stories/us-008-reward-spawn-progression.md b/design/user-stories/us-008-reward-spawn-progression.md new file mode 100644 index 0000000..77e57ec --- /dev/null +++ b/design/user-stories/us-008-reward-spawn-progression.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)