chore(knowledge): move canonical docs to shared SoMC wiki
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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 <blocks>` 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)
|
||||
@@ -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 <player> <duration>` 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 <player>` 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)
|
||||
@@ -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 <player>` 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 <player>` 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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user