From d35c0197f58025bb1c19361f0d4666412e27bd00 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Fri, 14 Aug 2026 18:27:09 -0400 Subject: [PATCH] docs(design): complete initial harvest stories --- README.md | 19 ++++++++-- design/log.md | 7 ++++ ...s-001-track-crop-harvesting-progression.md | 18 +++++----- .../us-002-unlock-crop-auto-harvest-levels.md | 36 +++++++++---------- .../us-003-harvest-connected-mature-crops.md | 34 +++++++++--------- ...-004-replant-crops-and-distribute-drops.md | 22 ++++++------ ...05-view-crop-progress-and-notifications.md | 30 ++++++++-------- ...6-administer-player-harvest-progression.md | 26 +++++++------- ...nfigure-and-persist-harvesting-behavior.md | 28 +++++++-------- 9 files changed, 121 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index f4449af..7fbdb01 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,26 @@ The plugin JAR is written to `build/libs/`. ```text /harvest -/harvest status [crop] +/harvest status [wheat|carrot|potato|beetroot] /harvest bossbar -/harvestadmin ``` +The progress boss bar is enabled by default and remains visible for five seconds after its latest update. Sneaking while breaking a mature crop bypasses auto-harvest while still earning progress. + +## Administration + +The `spigotharvest.admin` permission is granted to server operators by default. + +```text +/harvestadmin status [crop] +/harvestadmin setlevel <0|I|II|III|IV|V|VI|VII|VIII|IX|X> +/harvestadmin setprogress +/harvestadmin reset +/harvestadmin reset all confirm +``` + +Validated progression and presentation defaults are documented in `src/main/resources/config.yml`. UUID-keyed player state is stored in `plugins/SpigotHarvest/state.yml` using atomic replacement where supported. + ## Releases Gitea Actions checks pushes and pull requests and stores a development JAR. Pull requests validate conventional commits. Main-branch conventional commits drive semantic releases when the repository defines a `RELEASE_TOKEN` with contents-write permission. diff --git a/design/log.md b/design/log.md index 2db0e77..c494e56 100644 --- a/design/log.md +++ b/design/log.md @@ -23,3 +23,10 @@ description: Chronological record of material decisions affecting the Spigot Har - Added the Java 17 Gradle/Spigot foundation, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial documentation. - Added Gitea CI and semantic-release workflows with development and versioned JAR artifacts. - Verified the foundation with `./gradlew clean check jar`. + +## 2026-08-14 — Initial plugin scope completed + +- Implemented independent Level 0–X progression for wheat, carrots, potatoes, and beetroot with validated configuration and atomic UUID-keyed YAML state. +- Implemented deterministic connected-crop traversal, one-operation-per-player scheduling, one-crop-per-tick harvesting, protection-event checks, automatic replanting, inventory delivery, and overflow drops. +- Added player status and boss-bar controls, five-second idle progress presentation, unlock titles, administrative inspection and mutations, offline-player lookup, and safe confirmed resets. +- Developed the progression, traversal, drops, persistence, settings, status, and administration behavior through failing-first automated tests. diff --git a/design/user-stories/us-001-track-crop-harvesting-progression.md b/design/user-stories/us-001-track-crop-harvesting-progression.md index 2a778ee..6c03deb 100644 --- a/design/user-stories/us-001-track-crop-harvesting-progression.md +++ b/design/user-stories/us-001-track-crop-harvesting-progression.md @@ -2,7 +2,7 @@ type: User Story title: "US-001: Track crop harvesting progression" description: Track qualifying harvest activity independently for each player and supported crop. -status: in-progress +status: done --- # US-001: Track crop harvesting progression @@ -11,14 +11,14 @@ As a **player**, I want my mature crop harvests tracked separately by crop so th ## Acceptance criteria -- [ ] Initial progression paths exist independently for wheat, carrots, potatoes, and beetroot. -- [ ] A crop contributes progress only when it is fully grown at the time a player harvests it. -- [ ] Only crops harvested by a player in Survival mode contribute progress by default. -- [ ] A manually broken mature crop contributes one unit to its matching crop path. -- [ ] Each mature crop collected by an auto-harvest operation contributes one unit to the player who started that operation. -- [ ] Sneaking prevents a manual break from starting auto-harvest but does not prevent the mature triggering crop from contributing progress. -- [ ] Immature crops, unsupported crops, and non-harvest block changes do not contribute progress. -- [ ] Progress is associated with the player's UUID and survives reconnects and server restarts. +- [x] Initial progression paths exist independently for wheat, carrots, potatoes, and beetroot. +- [x] A crop contributes progress only when it is fully grown at the time a player harvests it. +- [x] Only crops harvested by a player in Survival mode contribute progress by default. +- [x] A manually broken mature crop contributes one unit to its matching crop path. +- [x] Each mature crop collected by an auto-harvest operation contributes one unit to the player who started that operation. +- [x] Sneaking prevents a manual break from starting auto-harvest but does not prevent the mature triggering crop from contributing progress. +- [x] Immature crops, unsupported crops, and non-harvest block changes do not contribute progress. +- [x] Progress is associated with the player's UUID and survives reconnects and server restarts. ## Related diff --git a/design/user-stories/us-002-unlock-crop-auto-harvest-levels.md b/design/user-stories/us-002-unlock-crop-auto-harvest-levels.md index be63768..2034649 100644 --- a/design/user-stories/us-002-unlock-crop-auto-harvest-levels.md +++ b/design/user-stories/us-002-unlock-crop-auto-harvest-levels.md @@ -2,7 +2,7 @@ type: User Story title: "US-002: Unlock crop auto-harvest levels" description: Let players earn ten independently configured auto-harvest levels for every supported crop. -status: in-progress +status: done --- # US-002: Unlock crop auto-harvest levels @@ -11,23 +11,23 @@ As a **player**, I want increasingly large auto-harvest limits as I gain experie ## Acceptance criteria -- [ ] Every supported crop has independent levels from Level 0 through Level X. -- [ ] Level 0 provides normal harvesting without connected auto-harvest. -- [ ] Progress toward a level is incremental and resets to zero when that level is earned. -- [ ] Excess progress from a single progression update carries into the next level rather than being discarded. -- [ ] The default Level 0 to I requirement is 100 mature crops and Level I permits an operation containing at most 4 crops. -- [ ] The default Level I to II requirement is 400 mature crops and Level II permits at most 8 crops. -- [ ] The default Level II to III requirement is 800 mature crops and Level III permits at most 16 crops. -- [ ] The default Level III to IV requirement is 1,600 mature crops and Level IV permits at most 32 crops. -- [ ] The default Level IV to V requirement is 3,200 mature crops and Level V permits at most 64 crops. -- [ ] The default Level V to VI requirement is 12,800 mature crops and Level VI permits at most 128 crops. -- [ ] The default Level VI to VII requirement is 25,600 mature crops and Level VII permits at most 256 crops. -- [ ] The default Level VII to VIII requirement is 51,200 mature crops and Level VIII permits at most 512 crops. -- [ ] The default Level VIII to IX requirement is 153,600 mature crops and Level IX permits at most 1,024 crops. -- [ ] The default Level IX to X requirement is 409,600 mature crops and Level X permits at most 2,048 crops. -- [ ] Each requirement and operation cap can be configured independently without changing another crop's earned player state. -- [ ] An auto-harvest operation uses the cap held when the operation starts; unlocking a level during that operation does not enlarge the operation already in progress. -- [ ] Reaching Level X stops further level progression without preventing harvesting or status display. +- [x] Every supported crop has independent levels from Level 0 through Level X. +- [x] Level 0 provides normal harvesting without connected auto-harvest. +- [x] Progress toward a level is incremental and resets to zero when that level is earned. +- [x] Excess progress from a single progression update carries into the next level rather than being discarded. +- [x] The default Level 0 to I requirement is 100 mature crops and Level I permits an operation containing at most 4 crops. +- [x] The default Level I to II requirement is 400 mature crops and Level II permits at most 8 crops. +- [x] The default Level II to III requirement is 800 mature crops and Level III permits at most 16 crops. +- [x] The default Level III to IV requirement is 1,600 mature crops and Level IV permits at most 32 crops. +- [x] The default Level IV to V requirement is 3,200 mature crops and Level V permits at most 64 crops. +- [x] The default Level V to VI requirement is 12,800 mature crops and Level VI permits at most 128 crops. +- [x] The default Level VI to VII requirement is 25,600 mature crops and Level VII permits at most 256 crops. +- [x] The default Level VII to VIII requirement is 51,200 mature crops and Level VIII permits at most 512 crops. +- [x] The default Level VIII to IX requirement is 153,600 mature crops and Level IX permits at most 1,024 crops. +- [x] The default Level IX to X requirement is 409,600 mature crops and Level X permits at most 2,048 crops. +- [x] Each requirement and operation cap can be configured independently without changing another crop's earned player state. +- [x] An auto-harvest operation uses the cap held when the operation starts; unlocking a level during that operation does not enlarge the operation already in progress. +- [x] Reaching Level X stops further level progression without preventing harvesting or status display. ## Related diff --git a/design/user-stories/us-003-harvest-connected-mature-crops.md b/design/user-stories/us-003-harvest-connected-mature-crops.md index 0494cf3..1368055 100644 --- a/design/user-stories/us-003-harvest-connected-mature-crops.md +++ b/design/user-stories/us-003-harvest-connected-mature-crops.md @@ -2,7 +2,7 @@ type: User Story title: "US-003: Harvest connected mature crops" description: Animate bounded harvesting across connected mature crops when a player performs a normal crop break. -status: in-progress +status: done --- # US-003: Harvest connected mature crops @@ -11,22 +11,22 @@ As a **player**, I want one normal crop break to harvest a connected area at a v ## Acceptance criteria -- [ ] Normally breaking a fully grown supported crop starts auto-harvest when the player has at least Level I for that crop. -- [ ] Breaking while sneaking performs normal single-crop harvesting and never starts auto-harvest. -- [ ] The manually broken triggering crop is included in the operation's maximum crop count. -- [ ] Auto-harvest traverses only fully grown crops of the same type as the triggering crop. -- [ ] A crop is connected when its horizontal position touches the current crop in any of the eight directions and its Y coordinate differs from the current crop by no more than one block. -- [ ] Connectivity is evaluated per link, allowing a connected operation to follow gradual rises and drops. -- [ ] Traversal is deterministic and never processes the same block more than once in an operation. -- [ ] The operation stops when it reaches the player's crop-level cap or no eligible connected crop remains. -- [ ] Auto-harvest processes a configurable number of crops per server tick, defaulting to one. -- [ ] A player can have no more than one active auto-harvest operation at a time. -- [ ] A normal crop broken while that player already has an active operation is harvested normally and may contribute progress, but it does not start or join another operation. -- [ ] Auto-harvest does not force-load chunks or continue into unloaded chunks. -- [ ] A crop that is no longer mature or matching when its turn arrives is skipped safely. -- [ ] Crop breaks denied by the server or another protection plugin are left unchanged, yield no drops, and contribute no progress. -- [ ] An operation ends safely when exhausted, cancelled, the player disconnects, or the plugin disables. -- [ ] Separate players may run independent auto-harvest operations concurrently. +- [x] Normally breaking a fully grown supported crop starts auto-harvest when the player has at least Level I for that crop. +- [x] Breaking while sneaking performs normal single-crop harvesting and never starts auto-harvest. +- [x] The manually broken triggering crop is included in the operation's maximum crop count. +- [x] Auto-harvest traverses only fully grown crops of the same type as the triggering crop. +- [x] A crop is connected when its horizontal position touches the current crop in any of the eight directions and its Y coordinate differs from the current crop by no more than one block. +- [x] Connectivity is evaluated per link, allowing a connected operation to follow gradual rises and drops. +- [x] Traversal is deterministic and never processes the same block more than once in an operation. +- [x] The operation stops when it reaches the player's crop-level cap or no eligible connected crop remains. +- [x] Auto-harvest processes a configurable number of crops per server tick, defaulting to one. +- [x] A player can have no more than one active auto-harvest operation at a time. +- [x] A normal crop broken while that player already has an active operation is harvested normally and may contribute progress, but it does not start or join another operation. +- [x] Auto-harvest does not force-load chunks or continue into unloaded chunks. +- [x] A crop that is no longer mature or matching when its turn arrives is skipped safely. +- [x] Crop breaks denied by the server or another protection plugin are left unchanged, yield no drops, and contribute no progress. +- [x] An operation ends safely when exhausted, cancelled, the player disconnects, or the plugin disables. +- [x] Separate players may run independent auto-harvest operations concurrently. ## Related diff --git a/design/user-stories/us-004-replant-crops-and-distribute-drops.md b/design/user-stories/us-004-replant-crops-and-distribute-drops.md index 17405ba..6185555 100644 --- a/design/user-stories/us-004-replant-crops-and-distribute-drops.md +++ b/design/user-stories/us-004-replant-crops-and-distribute-drops.md @@ -2,7 +2,7 @@ type: User Story title: "US-004: Replant crops and distribute drops" description: Automatically replant harvested crops and deliver their remaining drops safely to the player. -status: in-progress +status: done --- # US-004: Replant crops and distribute drops @@ -11,16 +11,16 @@ As a **player**, I want harvested crops replanted and their useful drops deliver ## Acceptance criteria -- [ ] Every crop successfully harvested by an auto-harvest operation is immediately replanted as the same crop at its minimum growth stage. -- [ ] Replanting consumes one appropriate planting item from that crop's generated drops before remaining drops are delivered. -- [ ] Wheat consumes one wheat seed, carrots consume one carrot, potatoes consume one potato, and beetroot consumes one beetroot seed when replanted. -- [ ] A crop is not auto-harvested when its generated drops cannot supply the item required to replant it. -- [ ] Drop quantities follow normal server crop-drop behavior and applicable tool enchantments where supported by the Spigot API. -- [ ] Replanting does not consume an additional item from the player's existing inventory. -- [ ] Remaining planting items, produce, and other generated drops are inserted into the initiating player's inventory. -- [ ] Items that do not fit in the inventory are dropped safely near the initiating player rather than at every harvested crop. -- [ ] No crop harvest duplicates or silently discards generated items. -- [ ] If the initiating player becomes unavailable, the operation ends without harvesting further crops. +- [x] Every crop successfully harvested by an auto-harvest operation is immediately replanted as the same crop at its minimum growth stage. +- [x] Replanting consumes one appropriate planting item from that crop's generated drops before remaining drops are delivered. +- [x] Wheat consumes one wheat seed, carrots consume one carrot, potatoes consume one potato, and beetroot consumes one beetroot seed when replanted. +- [x] A crop is not auto-harvested when its generated drops cannot supply the item required to replant it. +- [x] Drop quantities follow normal server crop-drop behavior and applicable tool enchantments where supported by the Spigot API. +- [x] Replanting does not consume an additional item from the player's existing inventory. +- [x] Remaining planting items, produce, and other generated drops are inserted into the initiating player's inventory. +- [x] Items that do not fit in the inventory are dropped safely near the initiating player rather than at every harvested crop. +- [x] No crop harvest duplicates or silently discards generated items. +- [x] If the initiating player becomes unavailable, the operation ends without harvesting further crops. ## Related diff --git a/design/user-stories/us-005-view-crop-progress-and-notifications.md b/design/user-stories/us-005-view-crop-progress-and-notifications.md index 8ecba3a..960e513 100644 --- a/design/user-stories/us-005-view-crop-progress-and-notifications.md +++ b/design/user-stories/us-005-view-crop-progress-and-notifications.md @@ -2,7 +2,7 @@ type: User Story title: "US-005: View crop progress and notifications" description: Give players command and boss-bar feedback about each crop's current progression. -status: in-progress +status: done --- # US-005: View crop progress and notifications @@ -11,20 +11,20 @@ As a **player**, I want to inspect crop progression and see recent progress upda ## Acceptance criteria -- [ ] `/harvest` and `/harvest status` display a concise summary of all supported crop paths and the player's current boss-bar preference. -- [ ] `/harvest status ` displays that crop's earned level, current level-local progress, next requirement, and current and next operation caps. -- [ ] Level X status clearly reports that the crop path is complete. -- [ ] `/harvest bossbar enable` enables progress boss bars idempotently, and `/harvest bossbar disable` disables them idempotently. -- [ ] Boss bars are enabled by default. -- [ ] Disabling boss bars does not affect progression, unlock notifications, or command-based status display. -- [ ] Crop names and boss-bar modes are offered through autocomplete, and invalid or extra arguments show friendly usage guidance. -- [ ] Every qualifying manual or automated harvest updates a crop-specific progress boss bar for the initiating player when boss bars are enabled. -- [ ] Boss-bar text identifies the crop and accurately displays current level-local progress and its requirement. -- [ ] Boss-bar fill never falls below zero or exceeds 100 percent. -- [ ] The boss bar remains visible for a configurable duration after the latest progress update, defaulting to five seconds. -- [ ] A new qualifying update resets the boss bar's disappearance timer. -- [ ] Unlocking a crop level displays a prominent one-time notification identifying the crop, new level, and new operation cap. -- [ ] Unlock notifications do not repeat after reconnecting or restarting. +- [x] `/harvest` and `/harvest status` display a concise summary of all supported crop paths and the player's current boss-bar preference. +- [x] `/harvest status ` displays that crop's earned level, current level-local progress, next requirement, and current and next operation caps. +- [x] Level X status clearly reports that the crop path is complete. +- [x] `/harvest bossbar enable` enables progress boss bars idempotently, and `/harvest bossbar disable` disables them idempotently. +- [x] Boss bars are enabled by default. +- [x] Disabling boss bars does not affect progression, unlock notifications, or command-based status display. +- [x] Crop names and boss-bar modes are offered through autocomplete, and invalid or extra arguments show friendly usage guidance. +- [x] Every qualifying manual or automated harvest updates a crop-specific progress boss bar for the initiating player when boss bars are enabled. +- [x] Boss-bar text identifies the crop and accurately displays current level-local progress and its requirement. +- [x] Boss-bar fill never falls below zero or exceeds 100 percent. +- [x] The boss bar remains visible for a configurable duration after the latest progress update, defaulting to five seconds. +- [x] A new qualifying update resets the boss bar's disappearance timer. +- [x] Unlocking a crop level displays a prominent one-time notification identifying the crop, new level, and new operation cap. +- [x] Unlock notifications do not repeat after reconnecting or restarting. ## Related diff --git a/design/user-stories/us-006-administer-player-harvest-progression.md b/design/user-stories/us-006-administer-player-harvest-progression.md index 46e5369..c672a34 100644 --- a/design/user-stories/us-006-administer-player-harvest-progression.md +++ b/design/user-stories/us-006-administer-player-harvest-progression.md @@ -2,7 +2,7 @@ type: User Story title: "US-006: Administer player harvest progression" description: Let administrators inspect, correct, and reset player crop progression safely through commands. -status: in-progress +status: done --- # US-006: Administer player harvest progression @@ -11,18 +11,18 @@ As a **server administrator**, I want command-based controls for crop progressio ## Acceptance criteria -- [ ] Administrative commands require `spigotharvest.admin`, which server operators receive by default. -- [ ] Administrative player arguments safely resolve online players and previously known offline players. -- [ ] Player state remains keyed by UUID while retaining the latest known name for lookup and display. -- [ ] `/harvestadmin status [crop]` displays the selected player's crop levels, level-local progress, and any active operation. -- [ ] `/harvestadmin setlevel <0|I|II|III|IV|V|VI|VII|VIII|IX|X>` sets that crop's level and resets its level-local progress. -- [ ] `/harvestadmin setprogress ` sets level-local progress and consistently evaluates any reached levels, carrying excess progress forward. -- [ ] `/harvestadmin reset ` resets only the selected crop to Level 0 with zero progress. -- [ ] `/harvestadmin reset all confirm` resets all crop progression only after explicit confirmation. -- [ ] A reset or level reduction cancels the player's active operation when that operation would exceed the resulting entitlement. -- [ ] Every successful mutation reports exactly what changed. -- [ ] Invalid requests make no partial changes and provide friendly usage guidance. -- [ ] Permission-aware autocomplete offers subcommands, online and known offline players, supported crops, valid levels, and reset confirmation. +- [x] Administrative commands require `spigotharvest.admin`, which server operators receive by default. +- [x] Administrative player arguments safely resolve online players and previously known offline players. +- [x] Player state remains keyed by UUID while retaining the latest known name for lookup and display. +- [x] `/harvestadmin status [crop]` displays the selected player's crop levels, level-local progress, and any active operation. +- [x] `/harvestadmin setlevel <0|I|II|III|IV|V|VI|VII|VIII|IX|X>` sets that crop's level and resets its level-local progress. +- [x] `/harvestadmin setprogress ` sets level-local progress and consistently evaluates any reached levels, carrying excess progress forward. +- [x] `/harvestadmin reset ` resets only the selected crop to Level 0 with zero progress. +- [x] `/harvestadmin reset all confirm` resets all crop progression only after explicit confirmation. +- [x] A reset or level reduction cancels the player's active operation when that operation would exceed the resulting entitlement. +- [x] Every successful mutation reports exactly what changed. +- [x] Invalid requests make no partial changes and provide friendly usage guidance. +- [x] Permission-aware autocomplete offers subcommands, online and known offline players, supported crops, valid levels, and reset confirmation. ## Related diff --git a/design/user-stories/us-007-configure-and-persist-harvesting-behavior.md b/design/user-stories/us-007-configure-and-persist-harvesting-behavior.md index 2bd5d51..a5277bc 100644 --- a/design/user-stories/us-007-configure-and-persist-harvesting-behavior.md +++ b/design/user-stories/us-007-configure-and-persist-harvesting-behavior.md @@ -2,7 +2,7 @@ type: User Story title: "US-007: Configure and persist harvesting behavior" description: Give operators validated configuration and durable storage for crop progression and harvesting behavior. -status: in-progress +status: done --- # US-007: Configure and persist harvesting behavior @@ -11,19 +11,19 @@ As a **server operator**, I want harvesting behavior to be configurable and play ## Acceptance criteria -- [ ] Configuration defines supported crops and the block material, maturity rule, and planting item for each crop. -- [ ] Configuration defines every level-local requirement and operation cap independently for each supported crop. -- [ ] Configuration defines eligible game modes, crops processed per tick, boss-bar idle duration, and unlock-notification timing. -- [ ] Defaults match the crops, requirements, caps, one-crop-per-tick pace, Survival-only progression, and five-second boss-bar duration documented by related stories. -- [ ] Requirements and caps are positive, representable, and sequentially coherent. -- [ ] Processing rates and notification durations reject unsafe or nonsensical values. -- [ ] Invalid required configuration prevents partial plugin initialization and produces a clear server log message. -- [ ] UUID-keyed state persists latest known player names, each crop's earned level and level-local progress, and the player's boss-bar preference. -- [ ] Existing player records without a boss-bar preference safely default to enabled. -- [ ] Active auto-harvest operations are transient and do not resume after a restart or reconnect. -- [ ] State is saved safely so a failed write does not replace valid persisted state with a partial document. -- [ ] Corrupt or invalid records are handled defensively and cannot silently grant progression or larger operation caps. -- [ ] Unknown forward-compatible configuration and state fields are preserved where practical. +- [x] Configuration defines supported crops and the block material, maturity rule, and planting item for each crop. +- [x] Configuration defines every level-local requirement and operation cap independently for each supported crop. +- [x] Configuration defines eligible game modes, crops processed per tick, boss-bar idle duration, and unlock-notification timing. +- [x] Defaults match the crops, requirements, caps, one-crop-per-tick pace, Survival-only progression, and five-second boss-bar duration documented by related stories. +- [x] Requirements and caps are positive, representable, and sequentially coherent. +- [x] Processing rates and notification durations reject unsafe or nonsensical values. +- [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message. +- [x] UUID-keyed state persists latest known player names, each crop's earned level and level-local progress, and the player's boss-bar preference. +- [x] Existing player records without a boss-bar preference safely default to enabled. +- [x] Active auto-harvest operations are transient and do not resume after a restart or reconnect. +- [x] State is saved safely so a failed write does not replace valid persisted state with a partial document. +- [x] Corrupt or invalid records are handled defensively and cannot silently grant progression or larger operation caps. +- [x] Unknown forward-compatible configuration and state fields are preserved where practical. ## Related