feat(base): implement progression system

2026-08-09 15:01:44 -04:00
commit c87d923cad
76 changed files with 5092 additions and 0 deletions
@@ -0,0 +1,20 @@
+---
+type: Index
+title: Spigot Base User Stories
+description: Catalog of user stories for the Spigot Base plugin.
+---
+
+# Spigot Base User Stories
+
+1. [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+2. [US-002: Unlock Base II navigation](us-002-unlock-base-navigation.md)
+3. [US-003: Expand the base](us-003-expand-the-base.md)
+4. [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
+5. [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
+6. [US-006: Reduce the base teleport warm-up](us-006-reduce-teleport-warmup.md)
+7. [US-007: Reduce the base teleport cooldown](us-007-reduce-teleport-cooldown.md)
+8. [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md)
+9. [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md)
+10. [US-010: Administer player progression](us-010-administer-player-progression.md)
+11. [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
+12. [US-012: Build and release the plugin](us-012-build-and-release-plugin.md)
@@ -0,0 +1,32 @@
+---
+type: User Story
+title: "US-001: Unlock and establish Base I"
+description: Let players earn and establish a persistent personal base by breaking dirt and grass blocks.
+status: in-progress
+---
+
+# US-001: Unlock and establish Base I
+
+As a **player**, I want to earn and set a personal base so that later quality-of-life progression has a location associated with it.
+
+## Acceptance criteria
+
+- [ ] Only blocks broken while the player is in Survival mode contribute progression.
+- [ ] Breaking `GRASS_BLOCK` or `DIRT` contributes one unit of Base I progress.
+- [ ] Other dirt-like materials, including coarse dirt, rooted dirt, podzol, mycelium, and dirt paths, do not contribute by default.
+- [ ] Player-placed blocks may contribute when broken; natural-generation detection is not required.
+- [ ] Base I unlocks when the player reaches the configured threshold, which defaults to 250 qualifying blocks.
+- [ ] `/setbase` is unavailable before Base I and explains the unmet requirement.
+- [ ] After Base I unlocks, `/setbase` records the player's current world and block location as the center of a cylindrical base.
+- [ ] The initial cylinder has a configurable 10-block horizontal radius and extends a configurable 25 blocks above and 25 blocks below the set Y coordinate.
+- [ ] The first successful `/setbase` is immediately available.
+- [ ] A successful relocation starts a configurable elapsed-time cooldown that defaults to 24 hours.
+- [ ] Failed attempts do not start or extend the relocation cooldown.
+- [ ] Progress and base state are associated with the player's UUID and survive restarts.
+
+## Related
+
+- [US-002: Unlock Base II navigation](us-002-unlock-base-navigation.md)
+- [US-003: Expand the base](us-003-expand-the-base.md)
+- [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
+- [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
@@ -0,0 +1,26 @@
+---
+type: User Story
+title: "US-002: Unlock Base II navigation"
+description: Let players earn toggleable particle guidance toward their established base.
+status: in-progress
+---
+
+# US-002: Unlock Base II navigation
+
+As a **player with Base I**, I want visual guidance toward my base so that I can find it without relying on coordinates.
+
+## Acceptance criteria
+
+- [ ] Base II requires Base I and an established base.
+- [ ] Base II unlocks at a configurable cumulative grass-or-dirt threshold that defaults to 500 blocks, 250 more than Base I.
+- [ ] Base II provides particle-based navigation and does not grant or require a physical compass item.
+- [ ] While enabled and in the base's world, particles are drawn along the ground to indicate the direction toward the base.
+- [ ] Particle generation is bounded to avoid excessive server or client load.
+- [ ] A player in another world receives a clear message instead of a misleading particle direction.
+- [ ] `/basenavigation` toggles guidance on and off after Base II is unlocked.
+- [ ] The navigation preference persists across reconnects and restarts.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md)
@@ -0,0 +1,29 @@
+---
+type: User Story
+title: "US-003: Expand the base"
+description: Let players expand their base radius through sequential stone, deepslate, and obsidian mining milestones.
+status: in-progress
+---
+
+# US-003: Expand the base
+
+As a **player with Base I**, I want mining milestones to expand my base so that more of my build receives base benefits.
+
+## Acceptance criteria
+
+- [ ] Base-size progression is unavailable until Base I is unlocked.
+- [ ] Only qualifying blocks broken in Survival mode count.
+- [ ] The first expansion requires a configurable 500 `STONE` and changes the radius from 10 to 25 blocks by default.
+- [ ] After the stone tier, the second expansion requires a separate configurable 1,000 `DEEPSLATE` and changes the radius from 25 to 75 blocks by default.
+- [ ] After the deepslate tier, the third expansion requires a separate configurable 1,000 `OBSIDIAN` and changes the radius from 75 to 150 blocks by default.
+- [ ] Stone, deepslate, and obsidian variants do not count by default.
+- [ ] Materials mined before their sequential tier becomes active do not count toward that later tier.
+- [ ] Player-placed qualifying blocks may be mined repeatedly for progress.
+- [ ] Expansions affect the cylinder's horizontal radius without independently changing its vertical bounds.
+- [ ] Relocating the base preserves earned size tiers and counters.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
@@ -0,0 +1,35 @@
+---
+type: User Story
+title: "US-004: Unlock and control base flight"
+description: Let players permanently unlock and toggle increasingly broad flight within their personal base.
+status: in-progress
+---
+
+# US-004: Unlock and control base flight
+
+As a **player with Base I**, I want to unlock controlled flight around my base so that I can build large structures more conveniently.
+
+## Acceptance criteria
+
+- [ ] Flight progression is unavailable until Base I is unlocked and a base is established.
+- [ ] The plugin observes elytra held directly in the player's inventory and armor equipment while the player is in Survival mode.
+- [ ] Elytra inside shulker boxes, bundles, or other nested containers do not count.
+- [ ] Observing one elytra permanently unlocks Flight I, two simultaneous elytra unlock Flight II, and three simultaneous elytra unlock Flight III.
+- [ ] A player observed with enough elytra for a later tier receives all unmet preceding flight tiers.
+- [ ] Elytra are not consumed, and losing them later does not revoke an earned tier.
+- [ ] Flight I permits plugin-granted flight within the current horizontal base radius and from 25 blocks below through 25 blocks above base Y by default.
+- [ ] Flight II expands the vertical range to 100 blocks below and above base Y by default.
+- [ ] Flight III expands the vertical range to the world's minimum and maximum build heights.
+- [ ] A configurable five-block horizontal warning buffer extends beyond the current base radius.
+- [ ] Plugin-granted flight remains active in the warning buffer and displays prominent on-screen notice that the player is leaving the base.
+- [ ] Passing beyond the warning buffer removes only flight granted by this plugin.
+- [ ] Flight is not granted outside the unlocked vertical range.
+- [ ] `/baseflight` toggles the player's unlocked base flight on and off.
+- [ ] The flight toggle persists across reconnects and restarts.
+- [ ] The plugin handles teleportation, world changes, game-mode changes, death, logout, and plugin shutdown without leaving unintended flight enabled.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-003: Expand the base](us-003-expand-the-base.md)
+- [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md)
@@ -0,0 +1,32 @@
+---
+type: User Story
+title: "US-005: Unlock Base III teleportation"
+description: Let players earn a safe, stationary-warm-up teleport to their personal base.
+status: in-progress
+---
+
+# US-005: Unlock Base III teleportation
+
+As a **player with Base II**, I want to earn `/base` so that I can return safely to my established base.
+
+## Acceptance criteria
+
+- [ ] Base III requires Base II, an established base, and a configurable 200 qualifying block placements inside the base.
+- [ ] Only placements made in Survival mode and within the base's current horizontal and vertical bounds count.
+- [ ] Player-placed blocks and replacement of previously broken blocks may contribute repeatedly.
+- [ ] Base III unlocks `/base` with a configurable 30-second warm-up and three-hour cooldown by default.
+- [ ] Looking around without changing block coordinates does not cancel the warm-up.
+- [ ] Changing block X, Y, or Z, taking damage, teleporting, changing worlds, dying, disconnecting, or starting a conflicting teleport cancels the warm-up.
+- [ ] Cancellation clearly informs the player and does not consume the cooldown.
+- [ ] The destination is a safe standing location at or near the recorded base center.
+- [ ] An unavailable or unsafe destination is reported clearly and does not consume the cooldown.
+- [ ] Only a completed teleport starts the cooldown.
+- [ ] Cooldowns use real elapsed time and continue while the player is offline.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-002: Unlock Base II navigation](us-002-unlock-base-navigation.md)
+- [US-006: Reduce the base teleport warm-up](us-006-reduce-teleport-warmup.md)
+- [US-007: Reduce the base teleport cooldown](us-007-reduce-teleport-cooldown.md)
+- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md)
@@ -0,0 +1,28 @@
+---
+type: User Story
+title: "US-006: Reduce the base teleport warm-up"
+description: Let players reduce and eventually eliminate their base teleport warm-up by building inside their base.
+status: in-progress
+---
+
+# US-006: Reduce the base teleport warm-up
+
+As a **player with Base III**, I want continued building to shorten my `/base` warm-up so that returning home becomes increasingly convenient.
+
+## Acceptance criteria
+
+- [ ] Warm-up progression requires Base III.
+- [ ] The qualifying placement counter from the Base III unlock is retained and used cumulatively.
+- [ ] Only Survival-mode placements inside the base's current horizontal and vertical bounds count.
+- [ ] A configurable 200 total placements grants the initial 30-second warm-up by default.
+- [ ] A configurable 1,000 total placements reduces the warm-up from 30 to 15 seconds by default.
+- [ ] A configurable 2,000 total placements reduces the warm-up from 15 to 5 seconds by default.
+- [ ] A configurable 12,000 total placements removes the warm-up by default.
+- [ ] Each tier must be earned sequentially, and progress is preserved when the base is relocated.
+- [ ] An instant warm-up does not bypass destination safety validation or cooldown enforcement.
+
+## Related
+
+- [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
+- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md)
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
@@ -0,0 +1,29 @@
+---
+type: User Story
+title: "US-007: Reduce the base teleport cooldown"
+description: Let players reduce and eventually eliminate their base teleport cooldown by breaking blocks inside their base.
+status: in-progress
+---
+
+# US-007: Reduce the base teleport cooldown
+
+As a **player with Base III**, I want work performed inside my base to shorten the `/base` cooldown so that I can return more frequently.
+
+## Acceptance criteria
+
+- [ ] Cooldown-reduction progress requires Base III.
+- [ ] Any block broken in Survival mode inside the base's current horizontal and vertical bounds contributes unless excluded by configuration.
+- [ ] Player-placed blocks may be broken repeatedly for progress.
+- [ ] The default cooldown is three hours before any cooldown-reduction milestone.
+- [ ] A configurable 1,000 cumulative blocks reduces the cooldown from three to two hours by default.
+- [ ] A configurable 2,000 cumulative blocks reduces the cooldown from two hours to one hour by default.
+- [ ] A configurable 3,000 cumulative blocks reduces the cooldown from one hour to 30 minutes by default.
+- [ ] A configurable 5,000 cumulative blocks removes the cooldown by default.
+- [ ] Each tier is sequential and relocating the base preserves earned tiers and progress.
+- [ ] An instant cooldown still enforces the applicable teleport warm-up and destination safety checks.
+
+## Related
+
+- [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
+- [US-006: Reduce the base teleport warm-up](us-006-reduce-teleport-warmup.md)
+- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md)
@@ -0,0 +1,36 @@
+---
+type: User Story
+title: "US-008: Unlock Base IV visitor access"
+description: Let players spend diamonds to permit controlled, cooldown-limited visitor teleports to their base.
+status: in-progress
+---
+
+# US-008: Unlock Base IV visitor access
+
+As a **player with Base III**, I want to open my base to visitors so that other players can conveniently join me there under my control.
+
+## Acceptance criteria
+
+- [ ] Base IV requires Base III and an established base.
+- [ ] `/base upgrade` offers the Base IV purchase for a configurable price that defaults to 128 diamonds.
+- [ ] A successful purchase removes the complete price atomically from the player's direct inventory.
+- [ ] Insufficient funds, an invalid state, or a failed persistence operation does not consume any diamonds or grant Base IV.
+- [ ] `/basevisitors` lets a Base IV owner toggle visitor access on and off.
+- [ ] The visitor-access preference persists across reconnects and restarts.
+- [ ] `/gotobase <owner>` autocompletes bases that the requesting player is currently eligible to visit.
+- [ ] Enabled bases remain visitable while their owners are offline.
+- [ ] A visitor teleport uses the destination owner's current warm-up tier.
+- [ ] Looking around is permitted, while movement between block coordinates, damage, teleportation, world change, death, logout, or a conflicting teleport cancels the visitor warm-up.
+- [ ] Cancellation or destination failure does not consume a visitor cooldown.
+- [ ] A safe destination is resolved at or near the owner's recorded base center.
+- [ ] Each visitor has an independent cooldown for each destination owner.
+- [ ] On successful teleport, the visitor cooldown duration is captured from the destination owner's current cooldown tier.
+- [ ] A later owner cooldown upgrade applies to future visits without rewriting a cooldown already in progress.
+- [ ] Visiting another base does not consume or modify the owner's personal `/base` cooldown or the visitor's personal `/base` cooldown.
+- [ ] Disabling visits prevents new requests but does not interrupt a teleport that has already completed.
+
+## Related
+
+- [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
+- [US-006: Reduce the base teleport warm-up](us-006-reduce-teleport-warmup.md)
+- [US-007: Reduce the base teleport cooldown](us-007-reduce-teleport-cooldown.md)
@@ -0,0 +1,30 @@
+---
+type: User Story
+title: "US-009: View progression and unlock notifications"
+description: Give players clear command, boss-bar, and full-screen feedback about their progression.
+status: in-progress
+---
+
+# US-009: View progression and unlock notifications
+
+As a **player**, I want to inspect my progression and receive timely milestone feedback so that I understand what I can unlock next.
+
+## Acceptance criteria
+
+- [ ] `/baseprogress` shows the player's Base, Base Size, Base Flight, Teleport Warm-up, and Teleport Cooldown paths.
+- [ ] Each path identifies earned levels, unmet prerequisites, current progress, the next threshold, and the next reward.
+- [ ] Locked secondary paths clearly identify Base I or another sequential level as their prerequisite.
+- [ ] Relevant qualifying activity briefly displays a configurable progress boss bar for the active milestone.
+- [ ] Boss-bar text and fill accurately represent the current count and threshold and never exceed 100 percent.
+- [ ] The automatic boss bar disappears after a configurable number of seconds.
+- [ ] `/baseprogress bossbar` toggles automatic progress boss bars on and off.
+- [ ] Disabling automatic boss bars does not prevent `/baseprogress` from displaying progress.
+- [ ] The boss-bar preference persists across reconnects and restarts.
+- [ ] Each newly unlocked level displays prominent full-screen title and subtitle text describing the reward.
+- [ ] Unlock notifications occur once per earned level and do not repeat after reconnecting or restarting.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
+- [US-010: Administer player progression](us-010-administer-player-progression.md)
@@ -0,0 +1,31 @@
+---
+type: User Story
+title: "US-010: Administer player progression"
+description: Let administrators inspect and safely modify player progression and live progression settings through commands.
+status: in-progress
+---
+
+# US-010: Administer player progression
+
+As a **server administrator**, I want command-based progression controls so that I can inspect players, correct state, and tune requirements without an inventory UI.
+
+## Acceptance criteria
+
+- [ ] Administrative commands require `spigotbase.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.
+- [ ] `/baseadmin progress <player>` displays the player's base, counters, earned path levels, active cooldowns, toggles, and visitor settings.
+- [ ] `/baseadmin setlevel <player> <path> <level>` sets an earned path level while enforcing or explicitly granting required preceding levels.
+- [ ] `/baseadmin setprogress <player> <path> <amount>` updates the selected counter and consistently evaluates reached tiers.
+- [ ] `/baseadmin reset <player> <path>` resets a selected path without silently leaving benefits that require it.
+- [ ] `/baseadmin reset <player> all` removes the player's base, progression, active cooldowns, and plugin preferences after confirmation.
+- [ ] Administrators can clear personal and visitor cooldowns independently.
+- [ ] Administrative commands can update configured block requirements, warm-ups, and cooldowns for each level using validated values.
+- [ ] Runtime configuration changes are persisted for subsequent restarts.
+- [ ] Lowered progression requirements are evaluated for a player on their next relevant action rather than immediately updating every stored player.
+- [ ] Every successful mutation reports exactly what changed, and invalid requests make no partial changes.
+
+## Related
+
+- [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md)
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
@@ -0,0 +1,30 @@
+---
+type: User Story
+title: "US-011: Configure and persist progression"
+description: Give operators validated configuration and durable, defensive storage for all base progression behavior.
+status: in-progress
+---
+
+# US-011: Configure and persist progression
+
+As a **server operator**, I want progression behavior to be configurable and durable so that the plugin remains predictable across restarts and server changes.
+
+## Acceptance criteria
+
+- [ ] Configuration supports all qualifying materials, progression thresholds, radii, vertical flight limits, warning-buffer distance, warm-ups, cooldowns, prices, particle settings, and notification durations.
+- [ ] Default values match the progression requirements documented by the related user stories.
+- [ ] Thresholds and levels are validated as nonnegative, representable, and sequentially coherent where required.
+- [ ] Radii, vertical ranges, durations, and prices 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 names, base locations, counters, levels, relocation times, teleport times, visitor cooldowns, navigation preferences, flight preferences, boss-bar preferences, and visitor settings.
+- [ ] Cooldowns and relocation limits use real elapsed timestamps and continue while players are offline.
+- [ ] State is saved safely so a failed write does not replace valid persisted state with a partial document.
+- [ ] Corrupt, unknown, or invalid records are handled defensively and cannot silently grant progression or privileges.
+- [ ] Unknown forward-compatible configuration and state fields are preserved where practical.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-003: Expand the base](us-003-expand-the-base.md)
+- [US-010: Administer player progression](us-010-administer-player-progression.md)
+- [US-012: Build and release the plugin](us-012-build-and-release-plugin.md)
@@ -0,0 +1,27 @@
+---
+type: User Story
+title: "US-012: Build and release the plugin"
+description: Give maintainers repeatable Spigot builds, automated verification, and versioned Gitea releases.
+status: in-progress
+---
+
+# US-012: Build and release the plugin
+
+As a **plugin maintainer**, I want automated builds and releases modeled on Trigger Spawn 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-trigger-spawn/` where applicable while using Spigot Base names and identifiers.
+
+## Related
+
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
+- [User-story catalog](index.md)