From 1d5f5e334e7dbff599a5d2df20d76bf3c08fdd51 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Wed, 9 Sep 2026 23:18:31 -0400 Subject: [PATCH] chore(knowledge): move canonical docs to shared SoMC wiki --- AGENTS.md | 9 +++ README.md | 2 +- design/index.md | 15 ---- design/log.md | 72 ------------------- 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 -------- 13 files changed, 10 insertions(+), 342 deletions(-) create mode 100644 AGENTS.md delete mode 100644 design/index.md delete mode 100644 design/log.md delete mode 100644 design/user-stories/index.md delete mode 100644 design/user-stories/us-001-earn-progressive-spawn-access.md delete mode 100644 design/user-stories/us-002-teleport-safely-to-spawn.md delete mode 100644 design/user-stories/us-003-configure-world-spawn-area.md delete mode 100644 design/user-stories/us-004-manage-spawn-access.md delete mode 100644 design/user-stories/us-005-manage-spawn-bans.md delete mode 100644 design/user-stories/us-006-configure-plugin-behavior.md delete mode 100644 design/user-stories/us-007-build-and-release-plugin.md delete mode 100644 design/user-stories/us-008-reward-spawn-progression.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..eccbfcc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +# spigot-trigger-spawn agent entrypoint + +The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md). + +Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-trigger-spawn/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-trigger-spawn/` stories. Also follow the parent workspace `AGENTS.md` when present. + +For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-trigger-spawn/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access. + +Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push. diff --git a/README.md b/README.md index 4b8290a..65a21cb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Players unlock `/spawn` by killing a Warden, Ender Dragon, or Wither after the p `/spawn` uses real elapsed cooldown time, including time offline. An accepted request displays a three-second countdown. Walking to another block, jumping, falling, teleporting, changing worlds, or disconnecting cancels it; looking around does not. The plugin samples a safe destination in the current world's circular spawn area, and failures do not consume the cooldown. -The behavior under development is specified in the [OKF design bundle](design/index.md). +The behavior under development is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-trigger-spawn/index.md). ## Requirements diff --git a/design/index.md b/design/index.md deleted file mode 100644 index bf68121..0000000 --- a/design/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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 deleted file mode 100644 index 093ae09..0000000 --- a/design/log.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -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. - -## 2026-08-08 — Build and release foundation - -- Added the Java 17 Gradle project targeting Spigot API 26.2, with JUnit 5 verification and versioned resource processing. -- Added Gitea CI and semantic-release workflows modeled on `spigot-event-producer`. -- Documented local builds, public releases, and the required `RELEASE_TOKEN` repository secret. - -## 2026-08-08 — Configuration and persistence - -- Added validated, independently configurable real-time cooldown tiers with documented defaults. -- Added atomic YAML persistence for UUID-based player access state and per-world spawn settings. -- Invalid persisted access values fail closed, while invalid required configuration disables the plugin rather than allowing partial startup. -- Added friendly duration formatting and the administrative permission declaration. - -## 2026-08-08 — Per-world spawn areas - -- Added `/spawnadmin set`, `distance`, and `info` for player-operated configuration of the current world. -- Worlds default to their native spawn and an independently persisted 20-block radius. -- Circular target sampling is uniform by area, preserves configured facing, and supports a zero-block radius. - -## 2026-08-08 — Administrative access grants - -- Added custom `/spawn` cooldown grants with safe, friendly duration parsing. -- Added complete access resets and a paginated view of naturally and administratively eligible players. -- Administrative targets resolve online players, persisted names, server-known offline players, and known UUIDs while state remains keyed by UUID. - -## 2026-08-08 — Spawn bans - -- Added persistent `/spawn` bans, unbans, and paginated ban listing for online and resolvable offline players. -- Banning immediately clears grants, boss progress, and cooldown state; unbanning restores none of them. -- Banned player state cannot retain natural or granted access. - -## 2026-08-08 — Boss progression - -- Added player-attributed Warden, Ender Dragon, and Wither kill observation without importing historical accomplishments. -- Unique kills unlock and improve the configured cooldown tier in any order; duplicate kills do not count. -- Each credited kill persists UUID-based progress, clears the current cooldown, and displays an on-screen reward plus colored checklist. - -## 2026-08-08 — Safe spawn teleportation - -- Added `/spawn` eligibility and real-time cooldown enforcement with explicit friendly remaining-time messages. -- Added a three-second on-screen warm-up cancelled by block movement, jumping, falling, teleportation, world changes, or disconnects. -- Safe destinations are sampled within the current world's circle using bounded attempts and a closest-elevation search that rejects environmental hazards. -- Only completed teleports consume cooldown, and incomplete progression receives a post-teleport reminder. - -## 2026-08-08 — Progression rewards and reminders - -- Successful `/spawn` teleports now identify each remaining boss and show the next permanent boss-based cooldown tier. -- Fully progressed players receive no unnecessary reminder. -- Verified that newly credited unique kills make `/spawn` immediately available while duplicate kills preserve the existing cooldown. diff --git a/design/user-stories/index.md b/design/user-stories/index.md deleted file mode 100644 index 9abd66d..0000000 --- a/design/user-stories/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 deleted file mode 100644 index fe374e2..0000000 --- a/design/user-stories/us-001-earn-progressive-spawn-access.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] The plugin observes player-attributed kills of the Warden, Ender Dragon, and Wither. -- [x] Only kills observed while the plugin is operating count; historical statistics and advancements are not imported. -- [x] The three enemies may be killed in any order. -- [x] The first unique qualifying kill unlocks `/spawn` with the configured one-kill cooldown, which defaults to 8 hours. -- [x] The second unique qualifying kill applies the configured two-kill cooldown, which defaults to 4 hours. -- [x] The third unique qualifying kill applies the configured three-kill cooldown, which defaults to 1 hour. -- [x] Repeated kills of an already credited enemy do not improve the player's tier. -- [x] 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. -- [x] Progress is presented as a checklist in which credited enemies have a green check and uncredited enemies have a red cross. -- [x] Each newly credited unique kill immediately clears any active `/spawn` cooldown as a progression reward. -- [x] 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 deleted file mode 100644 index f56c047..0000000 --- a/design/user-stories/us-002-teleport-safely-to-spawn.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] `/spawn` is available after at least one qualifying unique enemy kill or an administrative grant. -- [x] A player without access receives a message instructing them to defeat a Warden, Ender Dragon, or Wither and sees the colored progress checklist. -- [x] A banned player cannot begin a spawn teleport. -- [x] 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. -- [x] Cooldowns use real elapsed time and therefore continue while the player is offline. -- [x] An accepted teleport request starts a three-second on-screen countdown. -- [x] The player may look around during the countdown without cancelling it. -- [x] A change to the player's block X, Y, or Z coordinate cancels the countdown, including walking to another block, jumping, or falling. -- [x] Teleportation or a world change during the countdown cancels it. -- [x] The destination is sampled randomly within the circular spawn area configured for the player's current world. -- [x] The destination provides non-hazardous solid ground, two blocks of clear headroom, and no immediate lava, fire, water, void, or other configured environmental hazard. -- [x] Unsafe underwater, leaf-top, inaccessible Nether-roof, and void-exposed destinations are rejected. -- [x] 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. -- [x] The safe-location search uses a bounded number of attempts and reports failure clearly when no destination is found. -- [x] Only a completed teleport starts the applicable cooldown. -- [x] After a completed teleport, a player with unfinished boss progression is reminded that defeating each remaining unique boss permanently reduces the cooldown. -- [x] 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 deleted file mode 100644 index d488017..0000000 --- a/design/user-stories/us-003-configure-world-spawn-area.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Every world has an independent spawn center and maximum spawn distance. -- [x] Until an administrator sets a custom center, a world uses its native world spawn point. -- [x] `/spawnadmin set` stores the executing administrator's current world, coordinates, yaw, and pitch as that world's center and facing direction. -- [x] `/spawnadmin distance ` sets the current world's maximum spawn distance in blocks. -- [x] `/spawnadmin info` displays the current world's effective center, whether it is native or custom, and maximum distance. -- [x] The default maximum spawn distance is 20 blocks. -- [x] The spawn area is circular, and random horizontal points are sampled uniformly by area within its radius. -- [x] A maximum distance of `0` targets the configured center and adjusts it to the nearest safe block. -- [x] Negative, non-numeric, or otherwise invalid distances are rejected with an explanatory message. -- [x] Random destinations use the center's saved yaw and pitch. -- [x] 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 deleted file mode 100644 index c3236e8..0000000 --- a/design/user-stories/us-004-manage-spawn-access.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] `/spawnadmin grant ` grants immediate `/spawn` access with the supplied cooldown. -- [x] Friendly, case-insensitive duration units are accepted, including values such as `30m`, `2h`, and `1d`. -- [x] Zero, negative, malformed, or overflowing grant durations are rejected with an explanatory message. -- [x] A custom administrative grant overrides the player's boss-based cooldown tier while the grant exists. -- [x] Killing qualifying enemies does not replace an active administrative grant's custom cooldown. -- [x] `/spawnadmin remove ` removes any administrative grant, recorded enemy progress, and active cooldown from the player. -- [x] After removal, the player begins with no access and can earn it again by defeating a qualifying enemy. -- [x] `/spawnadmin access [page]` lists all players who currently have natural or granted access, including offline players. -- [x] Each access-list entry identifies the player, access source, applicable cooldown, progression tier when relevant, and current remaining cooldown. -- [x] Administrative player arguments support online players and previously known offline players when they can be resolved safely. -- [x] 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 deleted file mode 100644 index 717b9e2..0000000 --- a/design/user-stories/us-005-manage-spawn-bans.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] `/spawnadmin ban ` immediately prevents the player from using `/spawn`. -- [x] Banning a player clears their administrative grant, enemy progress, and active cooldown. -- [x] Qualifying kills made while banned are not recorded. -- [x] A banned player cannot receive an administrative grant until unbanned. -- [x] `/spawnadmin bans [page]` displays a paginated list of banned players, including offline players. -- [x] `/spawnadmin unban ` removes the ban without restoring any prior grant, enemy progress, or cooldown. -- [x] An unbanned player begins with no access and can earn access again by defeating a qualifying enemy or receiving a new grant. -- [x] Ban and unban commands support online players and previously known offline players when they can be resolved safely. -- [x] 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 deleted file mode 100644 index ba1b389..0000000 --- a/design/user-stories/us-006-configure-plugin-behavior.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] The one-kill cooldown is independently configurable and defaults to 28,800 seconds. -- [x] The two-kill cooldown is independently configurable and defaults to 14,400 seconds. -- [x] The three-kill cooldown is independently configurable and defaults to 3,600 seconds. -- [x] Configured cooldowns must be positive and representable safely by the plugin. -- [x] Invalid required configuration prevents partial initialization and produces a clear server log message. -- [x] Player-facing messages use clear built-in wording, readable colors, and friendly duration formatting. -- [x] Ordinary players do not require a plugin permission node to execute `/spawn`; eligibility is controlled by progression, grants, cooldowns, and bans. -- [x] Administrative commands require `triggerspawn.admin`. -- [x] Server operators receive `triggerspawn.admin` by default. -- [x] Boss progress, grants, bans, cooldown timestamps, latest known names, and per-world spawn settings persist across clean restarts. -- [x] 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 deleted file mode 100644 index 03ac35d..0000000 --- a/design/user-stories/us-007-build-and-release-plugin.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] The Gradle project compiles against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain. -- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle. -- [x] Pushes and pull requests build and test the plugin in Gitea Actions. -- [x] Pull requests validate conventional commit messages. -- [x] CI stores a development JAR as a workflow artifact. -- [x] Main-branch conventional commits drive semantic versioning. -- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release. -- [x] 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 deleted file mode 100644 index 744a2ed..0000000 --- a/design/user-stories/us-008-reward-spawn-progression.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] 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. -- [x] The reminder identifies the remaining eligible bosses and shows the next cooldown tier. -- [x] A player who has completed all three unique qualifying kills does not receive the progression reminder. -- [x] Each newly credited unique Warden, Ender Dragon, or Wither kill immediately clears the player's active `/spawn` cooldown. -- [x] Clearing the cooldown makes `/spawn` immediately available as a progression reward. -- [x] The newly credited kill also permanently applies the improved boss-based cooldown tier. -- [x] Repeated kills of an already credited enemy do not clear the cooldown. -- [x] The on-screen kill message states that `/spawn` is immediately available and displays the new cooldown tier. -- [x] 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)