diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..90fd865 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +# spigot-creeper-fear 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-creeper-fear/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-creeper-fear/` 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-creeper-fear/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 2dde605..2238b41 100644 --- a/README.md +++ b/README.md @@ -99,4 +99,4 @@ For a local versioned artifact: ## Design -The [OKF design bundle](design/index.md) contains the architecture and completed user stories. +The [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-creeper-fear/index.md) contains the architecture and completed user stories. diff --git a/design/architecture.md b/design/architecture.md deleted file mode 100644 index 40b18a2..0000000 --- a/design/architecture.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -type: Architecture -title: Creeper Fear Plugin Architecture -description: Runtime boundaries, persistence model, and event flow for Creeper Aura progression. ---- - -# Creeper Fear Plugin Architecture - -## Runtime - -Creeper Fear targets Java 17 and Spigot API 26.2. The plugin entry point owns listeners, commands, player feedback, configuration, and a progression service. - -## Progression model - -Each known player is identified by UUID and has: - -- a last-known player name for administrative lookup; -- a current rank (`LOCKED`, `I`, `II`, `III`, `IV`, `V`, or `VI`); -- a non-negative number of creeper kills earned within the current tier. - -A qualifying kill increments current-tier progress. Unlocking the next rank resets that progress to zero. Rank VI accumulates no further progress. Lifetime kill totals are deliberately not retained. - -## Persistence and threading - -SQLite stores player progression in the plugin data directory. Gameplay listeners submit persistence work to a dedicated single-thread executor so database latency does not block the Minecraft server thread. Bukkit API state is captured before work leaves the server thread and is not accessed by persistence workers. - -Player progress is loaded into an online cache before synchronous aura decisions. Offline administrative operations use the same serialized persistence boundary. - -## Event flow - -A creeper death is attributed to a player when the player directly dealt the final damage or is attributable through a projectile or owned tameable. The progression service deduplicates a creeper death and records one point. - -A self-destructing creeper also awards one point to every player its explosion would have hit. Explosion awards are deduplicated independently for each creeper and player, count before armor or aura mitigation, and use the same feedback as credited kills. - -For explosions, player damage events establish whether an unlocked player would have been hit before armor mitigation. Each protected player receives their own rank multiplier. If any aura activates, the corresponding creeper explosion's affected block list is cleared for everyone. Rank VI cancels the player's damage event entirely. - -## Commands and configuration - -`/creeperaura` exposes player progress and permission-protected offline administration. Permission-aware tab completion suggests available subcommands, online players, and valid ranks without querying SQLite on the server thread. Rank requirements, multipliers, feedback duration, and messages are loaded from YAML. Valid command-based changes are written back to YAML and survive restart. - -## Verification - -Domain and persistence behavior is exercised through public interfaces with JUnit. Bukkit-facing adapters remain thin, while build verification ensures their compatibility with Spigot API 26.2. - -## Related - -- [Design index](index.md) -- [User stories](user-stories/index.md) diff --git a/design/index.md b/design/index.md deleted file mode 100644 index 51a1567..0000000 --- a/design/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -type: Index -title: Spigot Creeper Fear Design -description: Entry point for the Spigot Creeper Fear OKF knowledge bundle. -okf_version: "0.1" ---- - -# Spigot Creeper Fear Design - -This bundle documents a Spigot plugin in which players earn Creeper Aura ranks by defeating creepers. Unlocked ranks prevent eligible creeper explosions from breaking blocks while changing the damage dealt to protected players. - -## Explore - -- [User stories](user-stories/index.md) -- [Plugin architecture](architecture.md) -- [Design log](log.md) -- [Project README](../README.md) diff --git a/design/log.md b/design/log.md deleted file mode 100644 index a7e0701..0000000 --- a/design/log.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: Log -title: Design Log -description: Chronological record of material changes to the Spigot Creeper Fear design bundle. ---- - -# Design Log - -## 2026-08-11 - -- Updated US-002 so an unlocked player's aura protects blocks from any creeper explosion within 25 blocks, without requiring the explosion to hit the player. -- Updated US-002 and US-006 so rank I requires 25 creeper kills by default while later ranks continue to require 100. - -## 2026-08-10 - -- Completed US-008 with permission-aware command, online-player, and rank tab completion. - -## 2026-08-08 - -- Established the OKF v0.1 design bundle. -- Defined creeper-kill progression, six Creeper Aura ranks, explosion protection, player feedback, administration, configuration, and build/release stories. -- Selected Spigot API 26.2 and Java 17 to match the neighboring `spigot-event-producer` project. -- Replaced lifetime cumulative kill tracking with a persisted rank and current-tier progress model. -- Added the initial plugin architecture. -- Completed US-001 with asynchronous SQLite current-tier progress, direct and indirect kill attribution, bounded death deduplication, and automated tests. -- Completed US-002 with per-tier rank advancement, online aura state, creeper block protection, rank damage multipliers, and rank VI cancellation. -- Completed US-003 with temporary configurable boss bars, current-tier progress presentation, full-screen rank-up titles, and maximum-rank hiding. -- Extended US-001 so a self-destructing creeper awards deduplicated progress and normal feedback to every player its explosion hits. -- Completed US-004 with an asynchronous self-service progress command, ordinary-player permission, completion output, and command metadata. -- Completed US-005 with UUID-backed offline inspection, atomic progress and rank administration, separate permissions, online-state refresh, and audit logging. -- Completed US-006 with validated per-rank requirements and multipliers, configurable feedback, persistent threshold administration, and safe reload behavior. -- Completed US-007 with Java 17/Spigot 26.2 Gradle builds, project documentation, Gitea CI, conventional-commit checks, semantic versioning, and release artifact publication. diff --git a/design/user-stories/index.md b/design/user-stories/index.md deleted file mode 100644 index a1f4ebe..0000000 --- a/design/user-stories/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -type: Index -title: Creeper Fear User Stories -description: Catalog of user stories for the Spigot Creeper Fear plugin. ---- - -# User Stories - -- [US-001: Track creeper defeats](us-001-track-creeper-defeats.md) -- [US-002: Unlock Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) -- [US-003: Show progression and rank advancement](us-003-show-progression-and-rank-advancement.md) -- [US-004: Check personal progress](us-004-check-personal-progress.md) -- [US-005: Administer player progression](us-005-administer-player-progression.md) -- [US-006: Configure aura progression](us-006-configure-aura-progression.md) -- [US-007: Build and release the plugin](us-007-build-and-release-plugin.md) -- [US-008: Autocomplete commands](us-008-autocomplete-commands.md) diff --git a/design/user-stories/us-001-track-creeper-defeats.md b/design/user-stories/us-001-track-creeper-defeats.md deleted file mode 100644 index 54bca21..0000000 --- a/design/user-stories/us-001-track-creeper-defeats.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: User Story -title: "US-001: Track creeper defeats" -description: Record persistent current-tier progress from creeper kills attributable to the player. -status: done ---- - -# US-001: Track creeper defeats - -As a **player**, I want my qualifying creeper kills recorded so that my Creeper Aura progression persists. - -## Acceptance criteria - -- [x] A creeper kill attributable to a player adds one point to that player's current-tier progress. -- [x] Direct melee kills and indirect kills attributable to the player, including projectiles and the player's tamed wolves, count. -- [x] A single creeper death cannot award progress more than once. -- [x] A creeper explosion awards one point to every player the explosion would have hit, including when armor or aura immunity reduces final damage to zero. -- [x] Each affected player receives at most one point from a given creeper explosion, while multiple affected players can each receive a point. -- [x] Explosion-earned progress produces the same progress and rank-up feedback as a credited kill. -- [x] Progress is stored using the player's UUID rather than their mutable name. -- [x] The player's current rank and current-tier progress are persisted separately. -- [x] Lifetime creeper-kill totals are not retained. -- [x] Rank VI does not accumulate further progress. -- [x] Progress survives logout, server restarts, and player-name changes. -- [x] Progress updates are persisted without blocking the Minecraft server thread on slow storage work. -- [x] Missing or invalid persisted data is handled safely and reported to server administrators. - -## Related - -- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) -- [Plugin architecture](../architecture.md) -- [User-story catalog](index.md) diff --git a/design/user-stories/us-002-unlock-creeper-aura-ranks.md b/design/user-stories/us-002-unlock-creeper-aura-ranks.md deleted file mode 100644 index da97ff7..0000000 --- a/design/user-stories/us-002-unlock-creeper-aura-ranks.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -type: User Story -title: "US-002: Unlock Creeper Aura ranks" -description: Protect blocks and modify creeper damage according to a player's earned aura rank. -status: done ---- - -# US-002: Unlock Creeper Aura ranks - -As a **player**, I want Creeper Aura to become stronger as I defeat creepers so that I progressively master their explosions. - -## Default progression - -| Current state | Kills needed to unlock next rank | Damage to protected player | Creeper block damage | -| --- | ---: | ---: | --- | -| Locked | 25 to unlock I | 1× | Normal | -| Creeper Aura I | 100 to unlock II | 3× | Prevented | -| Creeper Aura II | 100 to unlock III | 2× | Prevented | -| Creeper Aura III | 100 to unlock IV | 1.5× | Prevented | -| Creeper Aura IV | 100 to unlock V | 1× | Prevented | -| Creeper Aura V | 100 to unlock VI | 0.5× | Prevented | -| Creeper Aura VI | Maximum rank | 0× | Prevented | - -## Acceptance criteria - -- [x] A player unlocks rank I after 25 kills by default; subsequent ranks require 100 kills each by default. -- [x] Unlocking a rank resets current-tier progress to zero. -- [x] A player below rank I receives normal creeper explosion behavior. -- [x] An aura protects blocks when a player with rank I or higher is within 25 blocks of a creeper at explosion time, including at exactly 25 blocks. -- [x] Block protection does not require the aura player to be hit by or have line of sight to the explosion. -- [x] An activated aura prevents that creeper explosion from breaking or removing blocks for everyone affected by the explosion. -- [x] Players beyond 25 blocks and players whose aura is locked do not activate block protection. -- [x] Other nearby players and entities continue to receive their normal creeper explosion effects unless they have their own aura damage modifier. -- [x] The protected player's rank multiplier is applied to vanilla creeper explosion damage before armor, enchantments, resistance, and difficulty mitigation. -- [x] At rank VI, the protected player's creeper explosion damage event is cancelled so that damage and knockback are nullified. -- [x] Charged creepers obey the same aura rules while retaining their vanilla base explosion strength. -- [x] Explosions from TNT, beds, respawn anchors, and non-creeper entities are unchanged. -- [x] Simultaneous exposure of players with different aura ranks is deterministic and tested. - -## Related - -- [Track creeper defeats](us-001-track-creeper-defeats.md) -- [Configure aura progression](us-006-configure-aura-progression.md) -- [User-story catalog](index.md) diff --git a/design/user-stories/us-003-show-progression-and-rank-advancement.md b/design/user-stories/us-003-show-progression-and-rank-advancement.md deleted file mode 100644 index eae99e9..0000000 --- a/design/user-stories/us-003-show-progression-and-rank-advancement.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-003: Show progression and rank advancement" -description: Give players brief current-tier progress displays and prominent rank-up notifications. -status: done ---- - -# US-003: Show progression and rank advancement - -As a **player**, I want visible progress and rank-up notifications so that I understand my advancement without persistent screen clutter. - -## Acceptance criteria - -- [x] After each qualifying creeper kill, a temporary boss bar shows the player's current state and progress toward the next rank. -- [x] A locked player sees current-tier progress toward Creeper Aura I. -- [x] A ranked player sees their current Roman-numeral rank, current-tier progress, and the next rank requirement. -- [x] The display duration is configurable and defaults to a short period measured in seconds. -- [x] The boss bar is hidden automatically when its display period expires. -- [x] A rank VI player no longer sees a progress boss bar. -- [x] Each newly attained rank displays a full-screen title naming the rank. -- [x] Joining the server does not replay a previously acknowledged rank-up title. -- [x] Administrative changes update an online player's boss bar if it is currently visible. - -## Related - -- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) -- [Check personal progress](us-004-check-personal-progress.md) -- [User-story catalog](index.md) diff --git a/design/user-stories/us-004-check-personal-progress.md b/design/user-stories/us-004-check-personal-progress.md deleted file mode 100644 index 53c852d..0000000 --- a/design/user-stories/us-004-check-personal-progress.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -type: User Story -title: "US-004: Check personal progress" -description: Let players request their current Creeper Aura rank and tier progress through a command. -status: done ---- - -# US-004: Check personal progress - -As a **player**, I want a command that reports my Creeper Aura progress so that I can check it at any time. - -## Acceptance criteria - -- [x] `/creeperaura progress` reports the player's current locked or ranked state and current-tier progress. -- [x] Before rank VI, the response reports the next rank requirement and the number of additional kills needed. -- [x] At rank VI, the response clearly reports that progression is complete. -- [x] The self-service command is available to ordinary players without administrative permission. -- [x] Console use, invalid arguments, and unavailable player data produce clear responses. -- [x] Command usage is included in plugin help and command metadata. - -## Related - -- [Show progression and rank advancement](us-003-show-progression-and-rank-advancement.md) -- [Administer player progression](us-005-administer-player-progression.md) -- [User-story catalog](index.md) diff --git a/design/user-stories/us-005-administer-player-progression.md b/design/user-stories/us-005-administer-player-progression.md deleted file mode 100644 index 2761ef8..0000000 --- a/design/user-stories/us-005-administer-player-progression.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: User Story -title: "US-005: Administer player progression" -description: Let authorized administrators inspect and modify online or offline player rank and tier progress. -status: done ---- - -# US-005: Administer player progression - -As a **server administrator**, I want to inspect and modify player progress so that I can support players and correct mistakes. - -## Acceptance criteria - -- [x] `/creeperaura progress ` reports another player's rank, current-tier progress, next requirement, and remaining kills. -- [x] `/creeperaura set ` sets a non-negative current-tier progress value without implicitly changing rank. -- [x] `/creeperaura add ` adjusts current-tier progress without allowing a negative result. -- [x] `/creeperaura rank ` explicitly changes rank and resets current-tier progress to zero. -- [x] Rank VI never retains current-tier progress. -- [x] Inspection and modification work for known offline players as well as online players. -- [x] Players are resolved to stored UUIDs so name changes do not create duplicate progression records. -- [x] Administrative changes are persisted immediately. -- [x] An online affected player's feedback and aura state are updated after a change. -- [x] Administrative commands require distinct, documented permissions suitable for inspection and modification. -- [x] Unauthorized use does not disclose another player's progression. -- [x] Invalid player names, ambiguous identities, invalid numbers, and storage failures produce clear responses without partial changes. -- [x] Successful administrative changes are written to the server log with the actor, target, old value, and new value. - -## Related - -- [Check personal progress](us-004-check-personal-progress.md) -- [Configure aura progression](us-006-configure-aura-progression.md) -- [User-story catalog](index.md) diff --git a/design/user-stories/us-006-configure-aura-progression.md b/design/user-stories/us-006-configure-aura-progression.md deleted file mode 100644 index 12e6392..0000000 --- a/design/user-stories/us-006-configure-aura-progression.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-006: Configure aura progression" -description: Let administrators safely configure and persist per-rank requirements, multipliers, and feedback. -status: done ---- - -# US-006: Configure aura progression - -As a **server administrator**, I want to configure progression and aura behavior so that it fits my server's balance. - -## Acceptance criteria - -- [x] Configuration defaults to 25 kills for rank I, 100 kills for each subsequent rank, and the documented six unlocked-rank damage multipliers. -- [x] Rank requirements are positive integers. -- [x] Damage multipliers are finite and non-negative. -- [x] Progress boss-bar duration and player-facing rank messages are configurable. -- [x] `/creeperaura threshold ` validates, applies, and persists the points required to unlock that rank. -- [x] `/creeperaura reload` safely loads externally edited configuration without requiring a server restart. -- [x] Threshold-management and reload commands require documented administrative permissions. -- [x] Invalid configuration is rejected with actionable diagnostics while the last valid configuration remains active. -- [x] Changing requirements never automatically removes an unlocked rank, grants a new rank, or discards current-tier progress. -- [x] After a requirement change, the player's next qualifying kill can grant at most the next rank when its requirement is satisfied. -- [x] Rank advancement resets current-tier progress to zero rather than carrying excess progress forward. -- [x] Configuration-command changes survive plugin and server restarts. - -## Related - -- [Creeper Aura ranks](us-002-unlock-creeper-aura-ranks.md) -- [Administer player progression](us-005-administer-player-progression.md) -- [User-story catalog](index.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 14654dc..0000000 --- a/design/user-stories/us-007-build-and-release-plugin.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -type: User Story -title: "US-007: Build and release the plugin" -description: Give maintainers repeatable Java 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 with Java 17 against Spigot API 26.2. -- [x] Automated 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] Build, installation, command, permission, configuration, and release procedures are documented. - -## Related - -- [User-story catalog](index.md) -- [Design index](../index.md) diff --git a/design/user-stories/us-008-autocomplete-commands.md b/design/user-stories/us-008-autocomplete-commands.md deleted file mode 100644 index bf75575..0000000 --- a/design/user-stories/us-008-autocomplete-commands.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-008: Autocomplete commands" -description: Help players and administrators discover valid Creeper Aura command arguments with permission-aware tab completion. -status: done ---- - -# US-008: Autocomplete commands - -As a **command sender**, I want Creeper Aura commands to offer relevant tab completions so that I can enter valid commands quickly and accurately. - -## Acceptance criteria - -- [x] `/creeperaura` suggests only subcommands allowed by the sender's permissions. -- [x] `progress`, `set`, `add`, and `rank` suggest matching online player names where appropriate. -- [x] `rank` suggests `locked`, `I`, `II`, `III`, `IV`, `V`, and `VI`. -- [x] `threshold` suggests configurable ranks `I` through `VI`. -- [x] Suggestions are filtered case-insensitively by the current input. -- [x] Unauthorized administrative subcommands and arguments are not suggested. -- [x] Completion works for both players and the server console. -- [x] Automated tests cover completion behavior. -- [x] Command metadata and project documentation describe autocomplete support. - -Offline stored players remain valid command targets but are not suggested, avoiding synchronous database access during completion. - -## Related - -- [Check personal progress](us-004-check-personal-progress.md) -- [Administer player progression](us-005-administer-player-progression.md) -- [Configure aura progression](us-006-configure-aura-progression.md) -- [User-story catalog](index.md)