docs(design): define harvest progression stories

2026-08-14 18:13:47 -04:00
commit b8583901f5
11 changed files with 299 additions and 0 deletions
@@ -0,0 +1,15 @@
 ---
 type: Index
 title: Spigot Harvest Design
 description: Entry point for the Spigot Harvest OKF knowledge bundle.
 okf_version: "0.1"
 ---
 # Spigot Harvest Design
 This bundle documents per-crop progression, animated connected harvesting, automatic replanting, player feedback, administration, persistence, configuration, and delivery requirements for the Spigot Harvest plugin.
 ## Explore
 - [User stories](user-stories/index.md)
 - [Design log](log.md)
@@ -0,0 +1,19 @@
 ---
 type: Log
 title: Spigot Harvest Design Log
 description: Chronological record of material decisions affecting the Spigot Harvest design.
 ---
 # Spigot Harvest Design Log
 ## 2026-08-14 — Initial harvesting progression design
 - Initial crop support includes wheat, carrots, potatoes, and beetroot, with an independent Level 0–X progression path for each crop.
 - Normal crop breaking triggers auto-harvest, while sneaking bypasses auto-harvest without preventing the manually broken mature crop from contributing progress.
 - Connected crops may be adjacent in any of the eight horizontal directions and differ by no more than one Y level for each connection.
 - The total operation cap includes the triggering crop and doubles from 4 at Level I through 2,048 at Level X.
 - Level requirements are incremental rather than cumulative and are based on the preceding level's harvest cap: a multiplier of 100 through Level V, 200 for Levels VI–VIII, 300 for Level IX, and 400 for Level X.
 - Automated harvests contribute progression, execute at one crop per server tick by default, and permit only one active auto-harvest operation per player.
 - Qualifying progress displays a player-toggleable boss bar that is enabled by default, persists its preference, and remains visible for five seconds after its latest update by default.
 - Harvested crops are automatically replanted, remaining drops go to the player's inventory, and inventory overflow drops near the player.
 - The project and delivery pipeline will follow the neighboring Spigot Base project where applicable.
@@ -0,0 +1,16 @@
 ---
 type: Index
 title: Spigot Harvest User Stories
 description: Catalog of user stories for the Spigot Harvest plugin.
 ---
 # Spigot Harvest User Stories
 1. [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
 2. [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
 3. [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
 4. [US-004: Replant crops and distribute drops](us-004-replant-crops-and-distribute-drops.md)
 5. [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)
 6. [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)
 7. [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
 8. [US-008: Build and release the plugin](us-008-build-and-release-plugin.md)
@@ -0,0 +1,27 @@
 ---
 type: User Story
 title: "US-001: Track crop harvesting progression"
 description: Track qualifying harvest activity independently for each player and supported crop.
 status: backlog
 ---
 # US-001: Track crop harvesting progression
 As a **player**, I want my mature crop harvests tracked separately by crop so that my experience with each crop unlocks its own harvesting benefits.
 ## 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.
 ## Related
 - [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
 - [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
 - [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
@@ -0,0 +1,36 @@
 ---
 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: backlog
 ---
 # US-002: Unlock crop auto-harvest levels
 As a **player**, I want increasingly large auto-harvest limits as I gain experience with a crop so that repeated farming becomes progressively more efficient.
 ## 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.
 ## Related
 - [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
 - [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
 - [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)
@@ -0,0 +1,35 @@
 ---
 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: backlog
 ---
 # US-003: Harvest connected mature crops
 As a **player**, I want one normal crop break to harvest a connected area at a visible pace so that unlocked farming feels powerful and satisfying without harming server performance.
 ## 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.
 ## Related
 - [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
 - [US-004: Replant crops and distribute drops](us-004-replant-crops-and-distribute-drops.md)
 - [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
@@ -0,0 +1,28 @@
 ---
 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: backlog
 ---
 # US-004: Replant crops and distribute drops
 As a **player**, I want harvested crops replanted and their useful drops delivered to me so that auto-harvest saves repetitive work without duplicating or losing items.
 ## 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.
 ## Related
 - [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
 - [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
@@ -0,0 +1,33 @@
 ---
 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: backlog
 ---
 # US-005: View crop progress and notifications
 As a **player**, I want to inspect crop progression and see recent progress updates so that I understand my current benefits and next unlock.
 ## 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 <crop>` 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.
 ## Related
 - [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
 - [US-002: Unlock crop auto-harvest levels](us-002-unlock-crop-auto-harvest-levels.md)
 - [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)
@@ -0,0 +1,30 @@
 ---
 type: User Story
 title: "US-006: Administer player harvest progression"
 description: Let administrators inspect, correct, and reset player crop progression safely through commands.
 status: backlog
 ---
 # US-006: Administer player harvest progression
 As a **server administrator**, I want command-based controls for crop progression so that I can inspect players and correct their state safely.
 ## 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 <player> [crop]` displays the selected player's crop levels, level-local progress, and any active operation.
 - [ ] `/harvestadmin setlevel <player> <crop> <0|I|II|III|IV|V|VI|VII|VIII|IX|X>` sets that crop's level and resets its level-local progress.
 - [ ] `/harvestadmin setprogress <player> <crop> <amount>` sets level-local progress and consistently evaluates any reached levels, carrying excess progress forward.
 - [ ] `/harvestadmin reset <player> <crop>` resets only the selected crop to Level 0 with zero progress.
 - [ ] `/harvestadmin reset <player> 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.
 ## Related
 - [US-005: View crop progress and notifications](us-005-view-crop-progress-and-notifications.md)
 - [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
@@ -0,0 +1,33 @@
 ---
 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: backlog
 ---
 # US-007: Configure and persist harvesting behavior
 As a **server operator**, I want harvesting behavior to be configurable and player progression to be durable so that the plugin remains predictable across restarts and server changes.
 ## 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.
 ## Related
 - [US-001: Track crop harvesting progression](us-001-track-crop-harvesting-progression.md)
 - [US-003: Harvest connected mature crops](us-003-harvest-connected-mature-crops.md)
 - [US-006: Administer player harvest progression](us-006-administer-player-harvest-progression.md)
 - [US-008: Build and release the plugin](us-008-build-and-release-plugin.md)
@@ -0,0 +1,27 @@
 ---
 type: User Story
 title: "US-008: Build and release the plugin"
 description: Give maintainers repeatable Spigot builds, automated verification, and versioned Gitea releases.
 status: backlog
 ---
 # US-008: Build and release the plugin
 As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested, correctly versioned artifacts can be distributed consistently.
 ## Acceptance criteria
 - [ ] The Gradle project compiles against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain.
 - [ ] Compiler lint warnings fail the build.
 - [ ] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
 - [ ] Pushes and pull requests build and test the plugin in Gitea Actions.
 - [ ] Pull requests validate conventional commit messages.
 - [ ] CI stores a development JAR as a workflow artifact.
 - [ ] Main-branch conventional commits drive semantic versioning.
 - [ ] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
 - [ ] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Harvest names and identifiers.
 ## Related
 - [US-007: Configure and persist harvesting behavior](us-007-configure-and-persist-harvesting-behavior.md)
 - [User-story catalog](index.md)