diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5591000 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +# spigot-base 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-base/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-base/` 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-base/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 41bfa86..3af5a2e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ A Purpur 26.2 plugin providing progression-gated player bases and quality-of-lif Players begin by breaking Survival-mode grass blocks or dirt. The progression paths provide a persistent base, navigation particles, expanding base bounds, controlled flight, personal teleportation, and visitor teleportation. -The approved behavior is specified in the [OKF design bundle](design/index.md). +The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-base/index.md). ## Requirements diff --git a/design/index.md b/design/index.md deleted file mode 100644 index 759fbec..0000000 --- a/design/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -type: Index -title: Spigot Base Design -description: Entry point for the Spigot Base OKF knowledge bundle. -okf_version: "0.1" ---- - -# Spigot Base Design - -This bundle documents the progression-gated quality-of-life features, player bases, flight, teleportation, administration, persistence, and delivery requirements for the Spigot Base plugin. - -## Explore - -- [User stories](user-stories/index.md) -- [Design log](log.md) diff --git a/design/log.md b/design/log.md deleted file mode 100644 index ee394c5..0000000 --- a/design/log.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -type: Log -title: Spigot Base Design Log -description: Chronological record of material decisions affecting the Spigot Base design. ---- - -# Spigot Base Design Log - -## 2026-08-09 — Initial progression design - -- Base progression is sequential: Base I establishes a base, Base II provides navigation, Base III provides personal teleportation, and Base IV permits visitor teleportation. -- Every secondary progression path requires Base I. -- A base is cylindrical and begins with a 10-block radius and a vertical extent 25 blocks above and below its set Y coordinate. -- Only Survival-mode activity contributes progress; repeatedly placing and breaking blocks is permitted. -- Flight is limited to the base, includes a five-block horizontal warning buffer, and can be toggled by the player. -- Player-facing administration will initially use commands rather than an inventory UI. -- The build and release pipeline will follow the neighboring Trigger Spawn project pattern. - -## 2026-08-09 — Implementation started - -- Approved implementation begins with the tested Gradle/Spigot foundation, validated configuration, and durable player state. -- Feature work will proceed incrementally using tests before implementation where practical. - -## 2026-08-09 — Core implementation checkpoint - -- Implemented UUID-keyed YAML state, validated configuration, Base I–IV progression, base sizing, particle navigation, controlled base flight, personal and visitor teleportation, progress feedback, and initial administrative commands. -- Added Gradle, Spigot metadata, Gitea CI/release workflows, and project documentation based on Trigger Spawn. -- Verified the implementation with `./gradlew clean check jar`: 34 tests passed and the plugin JAR was produced successfully. -- User stories remain in progress pending live-server integration verification and completion of runtime administrative configuration editing. - -## 2026-08-09 — Navigation preference fix - -- Added explicit, idempotent `/basenavigation on` and `/basenavigation off` modes with autocomplete while retaining no-argument toggling. -- Preserved a disabled navigation preference during later grass-or-dirt progression instead of forcing navigation back on. - -## 2026-08-09 — Initial release scope completed - -- Added live, validated, persisted numeric configuration updates through `/baseadmin config`. -- Added administrative progress-counter updates, prerequisite-aware level changes, cooldown clearing, and cascading path resets. -- Made progression materials, visitor currency, boss-bar duration, particle count, and title timing configurable. -- Preserved unknown forward-compatible YAML fields for retained player records while continuing to reject invalid progression state. -- Completed and verified all approved user stories with the automated Gradle check lifecycle. - -## 2026-08-10 — Player command aliases - -- Added `/sethome` for `/setbase`, `/home` for `/base`, and `/visit` for `/gotobase`. -- Visitor autocomplete remains available for eligible offline bases through the `/visit` alias. -- Verified the aliases and plugin build with `./gradlew clean check jar`. - -## 2026-08-10 — Toggle command autocomplete - -- Added explicit, idempotent `on` and `off` modes and autocomplete to base flight and visitor access while retaining no-argument toggling. -- Added `/homenavigation`, `/homeflight`, and `/homevisitors` aliases with the same autocomplete as their canonical commands. -- Generalized toggle preference resolution for navigation, flight, and visitor access. -- Verified the implementation with `./gradlew clean check jar`. - -## 2026-08-10 — Unified base settings command - -- Replaced the separate progress, navigation, flight, and visitor commands with `/basesettings` and its `/homesettings` alias. -- Added nested autocomplete for status, Base IV upgrades, visitor access, navigation, flight, and progress boss-bar settings. -- Moved the Base IV purchase from `/base upgrade` to `/basesettings upgrade`, leaving `/base` and `/home` dedicated to personal teleportation. -- Preserved the full progression report as the default `/basesettings` response and as `/basesettings status`. -- Verified the breaking command restructure with `./gradlew clean check jar`. - -## 2026-08-10 — Administrative command autocomplete and reset safety - -- Added `/homeadmin` as an alias for `/baseadmin` and replaced the administrative `progress` subcommand with `status`. -- Added permission-aware, context-sensitive autocomplete for subcommands, online and known offline players, paths, levels, counters, cooldown types, reset confirmation, and numeric configuration keys. -- Removed the unsafe unconfirmed base reset path; complete resets now require `reset all confirm`. -- Tightened argument validation and replaced implementation-specific enum errors with player-facing usage guidance. -- Verified the administrative revision with `./gradlew clean check jar`. - -## 2026-08-10 — Base border visualization - -- Added persisted, owner-only base border particles controlled by `/basesettings border enable|disable` with contextual autocomplete. -- Rendered a bounded nearby arc at the player's current height using the current base radius while respecting world and vertical bounds. -- Added border preference reporting to player and administrative status output and safe defaults for existing state files. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-10 — Spawnable block overlay - -- Added persistent progression for Survival-mode block placements anywhere, with existing in-base placement counts used as a safe migration minimum. -- Added `/basesettings spawnable enable|disable` after a configurable 250-placement unlock and reported its progress and preference in player and admin status output. -- Added admin controls for total placement progress, the unlock threshold, and each unlocked player's overlay preference. -- Added owner-only red particles for nearby dark spawning surfaces inside base bounds, using bounded incremental scanning and rendering budgets. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-10 — Navigation visibility buffer - -- Limited enabled base navigation particles to the base's world and positions more than 25 horizontal blocks beyond the current base border. -- Used the live size-tier radius so expansion and relocation immediately update the visibility threshold. -- Added exact-boundary and controller integration coverage. -- Verified the change with `./gradlew clean check jar`. - -## 2026-08-24 — Pocket Base mob-spawning control - -- Disabled natural hostile and passive mob spawning by default in new and existing Pocket Bases without a saved preference. -- Added independent persisted owner settings through `/basesettings pocket mobs `, contextual autocomplete, and status reporting. -- Migrated each legacy combined mob-spawning preference to both categories to preserve existing behavior. -- Reapplied both saved spawn flags when Pocket Base worlds load and restored both prior world settings when persistence fails. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-24 — Relocatable Pocket Base return portals - -- Allowed Pocket Base owners to activate a complete return portal frame with flint and steel anywhere inside their unlocked pocket boundary. -- Persisted one active return portal location while retaining the generated portal as the default for existing Pocket Bases. -- Made only the selected intact frame functional without removing old frame blocks, preserving the void-return safety fallback. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-24 — Purchasable Pocket Base biomes - -- Added `/basesettings pocket type ` with type-aware autocomplete and validation. -- Defaulted new and unconfigured Pocket Bases to `void/the_void` and persisted each owner's selected biome. -- Applied biome metadata across unlocked columns and new expansion rings without changing blocks, entities, inventories, portals, progression, or mob-spawning preferences. -- Added an atomic, configurable biome-change payment that defaults to 16 netherite blocks and restores the prior biome and payment on failure. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-24 — Native base settings dialog - -- Changed `/basesettings` and `/homesettings` with no arguments to open a native Minecraft dialog dashboard, with explicit `ui` subcommands providing the same behavior. -- Added progression summaries, current and locked setting states, toggles, Pocket Base controls, biome selection, and confirmations for Base IV, Pocket Base, and biome purchases. -- Retained the detailed chat report under `/basesettings status` and kept dialog actions routed through the existing validated command behavior. -- Added dialog routing, autocomplete, alias, non-player, generated-control, locked-state, and purchase-confirmation coverage. -- Verified the feature with `./gradlew clean check jar`. - -## 2026-08-24 — Purpur dialog runtime compatibility - -- Replaced the Spigot-only Bungee dialog types that were absent from production with Purpur's supported Paper dialog API. -- Compiled and tested against the exact Purpur 26.2 build 2618 API with Java 25, and updated both CI workflows to use Java 25. -- Preserved unit-test coverage through server-independent dialog specifications and adapted Bukkit test fixtures to Purpur's registry-aware API behavior. -- Verified 128 tests and the Java 25 plugin artifact with `./gradlew clean check jar`. - -## 2026-08-25 — Static dialog command actions - -- Replaced macro command templates with static run-command actions for fixed dialog buttons. -- Added regression coverage for the generated run-command action and its unchanged command payload. -- Verified `/basesettings` opens without command exceptions on a local Purpur 26.2 build 2618 server. -- Verified the plugin artifact with `./gradlew clean check jar`. - -## 2026-08-24 — Pocket Base mob portal travel - -- Added five-tick collision scanning that transports non-player living mobs through active Pocket Base entrance and return portals. -- Reused safe player destinations and server-spawn fallback behavior while excluding items, projectiles, vehicles, and other non-living entities. -- Applied the existing two-second portal cooldown to mobs to prevent immediate repeated transport. -- Verified the feature and Java 25 plugin artifact with `./gradlew clean check jar`. - -## 2026-08-28 — Safe Pocket Base fall returns - -- Cleared accumulated fall distance whenever portal or void-return travel teleports an entity, preventing carried-over fall damage at the destination. -- Added regression coverage for players falling out of a Pocket Base and returning to the server spawn. -- Verified the fix and plugin artifact with `./gradlew clean check jar`. - -## 2026-08-28 — Raid-earned Pocket Base flight - -- Made a successful raid victory by the owner inside their own Pocket Base permanently unlock owner-only Survival flight. -- Limited Pocket Base flight to its expanding horizontal boundary plus a 16-block warning buffer while allowing the world's full build height. -- Persisted unlocks with safe locked defaults for existing records and exposed progress through chat status and the native settings dialog. -- Verified 140 tests and the Java 25 plugin artifact with `./gradlew clean check jar`. - -## 2026-08-28 — Shared Pocket Base flight portals - -- Added one persistent owner-activated gold-block flight portal per Pocket Base after the raid unlock. -- Granted owners and guests temporary controlled flight after portal collision, independently of the owner's persisted automatic-flight preference. -- Applied the expanding Pocket Base boundary plus a 16-block warning buffer to both automatic and portal-granted flight. -- Restored Back buttons from nested native dialog screens to the main Base Settings dashboard. -- Verified 149 tests and the Java 25 plugin artifact with `./gradlew clean check jar`. - -## 2026-08-29 — Recovery Compass metadata compatibility - -- Accepted Purpur's valid generic item metadata when creating the Pocket Base Keystone instead of requiring the legacy Compass-specific metadata subtype. -- Added regression coverage and verified 158 tests and the Java 25 plugin artifact with `./gradlew clean check jar`. - -## 2026-08-29 — Pocket Base Keystone travel - -- Added a reusable Recovery Compass keystone recipe with an Ender Pearl center, cardinal Netherite Ingots, and Obsidian corners. -- Limited crafting and use to Pocket Base owners while allowing transferred keystones to work for each eligible holder's own Pocket Base. -- Added instant entry and safe return travel with exact, durable return destinations and fall-distance clearing. -- Rejected unavailable and unsafe returns without discarding the saved destination. -- Verified 157 tests and the Java 25 plugin artifact with `./gradlew clean check jar`. diff --git a/design/user-stories/index.md b/design/user-stories/index.md deleted file mode 100644 index edf26fb..0000000 --- a/design/user-stories/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -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) -13. [US-013: Visualize the base border](us-013-visualize-base-border.md) -14. [US-014: Highlight spawnable blocks](us-014-highlight-spawnable-blocks.md) -15. [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -16. [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) -17. [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -18. [US-018: Control Pocket Base mob spawning](us-018-control-pocket-base-mob-spawning.md) -19. [US-019: Change a Pocket Base biome](us-019-change-a-pocket-base-biome.md) -20. [US-020: Control a base through a dialog UI](us-020-control-base-through-dialog-ui.md) -21. [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md) -22. [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md) -23. [US-023: Craft and use a Pocket Base Keystone](us-023-craft-pocket-base-keystone.md) diff --git a/design/user-stories/us-001-unlock-and-establish-base.md b/design/user-stories/us-001-unlock-and-establish-base.md deleted file mode 100644 index de30f80..0000000 --- a/design/user-stories/us-001-unlock-and-establish-base.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Only blocks broken while the player is in Survival mode contribute progression. -- [x] Breaking `GRASS_BLOCK` or `DIRT` contributes one unit of Base I progress. -- [x] Other dirt-like materials, including coarse dirt, rooted dirt, podzol, mycelium, and dirt paths, do not contribute by default. -- [x] Player-placed blocks may contribute when broken; natural-generation detection is not required. -- [x] Base I unlocks when the player reaches the configured threshold, which defaults to 250 qualifying blocks. -- [x] `/setbase` is unavailable before Base I and explains the unmet requirement. -- [x] `/sethome` is an alias for `/setbase` with identical behavior. -- [x] After Base I unlocks, `/setbase` records the player's current world and block location as the center of a cylindrical base. -- [x] 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. -- [x] The first successful `/setbase` is immediately available. -- [x] A successful relocation starts a configurable elapsed-time cooldown that defaults to 24 hours. -- [x] Failed attempts do not start or extend the relocation cooldown. -- [x] 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) diff --git a/design/user-stories/us-002-unlock-base-navigation.md b/design/user-stories/us-002-unlock-base-navigation.md deleted file mode 100644 index 99cb1fe..0000000 --- a/design/user-stories/us-002-unlock-base-navigation.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -type: User Story -title: "US-002: Unlock Base II navigation" -description: Let players earn toggleable particle guidance toward their established base. -status: done ---- - -# 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 - -- [x] Base II requires Base I and an established base. -- [x] Base II unlocks at a configurable cumulative grass-or-dirt threshold that defaults to 500 blocks, 250 more than Base I. -- [x] Base II provides particle-based navigation and does not grant or require a physical compass item. -- [x] While enabled and in the base's world, particles are drawn along the ground only when the player is horizontally more than 25 blocks beyond the current base border. -- [x] No navigation particles appear inside the base, exactly 25 blocks beyond its border, or anywhere within that buffer. -- [x] Expansion and relocation update the navigation visibility threshold immediately. -- [x] Particle generation is bounded to avoid excessive server or client load. -- [x] A player in another world receives a clear message instead of a misleading particle direction. -- [x] `/basesettings navigation enable` enables guidance idempotently after Base II is unlocked, and `/basesettings navigation disable` disables it idempotently. -- [x] Invalid navigation arguments show command usage, and `enable` and `disable` are offered through autocomplete. -- [x] Grass-or-dirt progress after Base II preserves the player's selected navigation preference. -- [x] 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) diff --git a/design/user-stories/us-003-expand-the-base.md b/design/user-stories/us-003-expand-the-base.md deleted file mode 100644 index 5c6a310..0000000 --- a/design/user-stories/us-003-expand-the-base.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Base-size progression is unavailable until Base I is unlocked. -- [x] Only qualifying blocks broken in Survival mode count. -- [x] The first expansion requires a configurable 500 `STONE` and changes the radius from 10 to 25 blocks by default. -- [x] 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. -- [x] 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. -- [x] Stone, deepslate, and obsidian variants do not count by default. -- [x] Materials mined before their sequential tier becomes active do not count toward that later tier. -- [x] Player-placed qualifying blocks may be mined repeatedly for progress. -- [x] Expansions affect the cylinder's horizontal radius without independently changing its vertical bounds. -- [x] 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) diff --git a/design/user-stories/us-004-unlock-and-control-base-flight.md b/design/user-stories/us-004-unlock-and-control-base-flight.md deleted file mode 100644 index 6be795a..0000000 --- a/design/user-stories/us-004-unlock-and-control-base-flight.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Flight progression is unavailable until Base I is unlocked and a base is established. -- [x] The plugin observes elytra held directly in the player's inventory and armor equipment while the player is in Survival mode. -- [x] Elytra inside shulker boxes, bundles, or other nested containers do not count. -- [x] Observing one elytra permanently unlocks Flight I, two simultaneous elytra unlock Flight II, and three simultaneous elytra unlock Flight III. -- [x] A player observed with enough elytra for a later tier receives all unmet preceding flight tiers. -- [x] Elytra are not consumed, and losing them later does not revoke an earned tier. -- [x] 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. -- [x] Flight II expands the vertical range to 100 blocks below and above base Y by default. -- [x] Flight III expands the vertical range to the world's minimum and maximum build heights. -- [x] A configurable five-block horizontal warning buffer extends beyond the current base radius. -- [x] Plugin-granted flight remains active in the warning buffer, and a prominent on-screen notice that the player is leaving the base appears only while the player is actively flying. -- [x] Passing beyond the warning buffer removes only flight granted by this plugin. -- [x] Flight is not granted outside the unlocked vertical range. -- [x] `/basesettings flight enable` enables unlocked flight idempotently, and `/basesettings flight disable` disables it idempotently. -- [x] Invalid flight arguments show command usage, and `enable` and `disable` are offered through autocomplete. -- [x] The flight toggle persists across reconnects and restarts. -- [x] 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) diff --git a/design/user-stories/us-005-unlock-base-teleportation.md b/design/user-stories/us-005-unlock-base-teleportation.md deleted file mode 100644 index 74963c7..0000000 --- a/design/user-stories/us-005-unlock-base-teleportation.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Warm-up particles float around the player, are visible nearby, and grow denser with warm-up progress. -- [x] Successful warmed-up teleports leave a departure cloud that thins out over two seconds. -- [x] Cancellation stops particle emission and failed teleports create no departure cloud. -- [x] Particle effects are bounded, cleaned up on shutdown, and regression-tested without changing teleport timing, safety, or cooldowns. - -- [x] Base III requires Base II, an established base, and a configurable 200 qualifying block placements inside the base. -- [x] Only placements made in Survival mode and within the base's current horizontal and vertical bounds count. -- [x] Player-placed blocks and replacement of previously broken blocks may contribute repeatedly. -- [x] Base III unlocks `/base` with a configurable 30-second warm-up and three-hour cooldown by default. -- [x] `/home` aliases the teleport-only `/base` command. -- [x] Looking around without changing block coordinates does not cancel the warm-up. -- [x] Changing block X, Y, or Z, taking damage, teleporting, changing worlds, dying, disconnecting, or starting a conflicting teleport cancels the warm-up. -- [x] Cancellation clearly informs the player and does not consume the cooldown. -- [x] The destination is a safe standing location at or near the recorded base center. -- [x] An unavailable or unsafe destination is reported clearly and does not consume the cooldown. -- [x] Only a completed teleport starts the cooldown. -- [x] 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) diff --git a/design/user-stories/us-006-reduce-teleport-warmup.md b/design/user-stories/us-006-reduce-teleport-warmup.md deleted file mode 100644 index 6be7b7a..0000000 --- a/design/user-stories/us-006-reduce-teleport-warmup.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Warm-up progression requires Base III. -- [x] The qualifying placement counter from the Base III unlock is retained and used cumulatively. -- [x] Only Survival-mode placements inside the base's current horizontal and vertical bounds count. -- [x] A configurable 200 total placements grants the initial 30-second warm-up by default. -- [x] A configurable 1,000 total placements reduces the warm-up from 30 to 15 seconds by default. -- [x] A configurable 2,000 total placements reduces the warm-up from 15 to 5 seconds by default. -- [x] A configurable 12,000 total placements removes the warm-up by default. -- [x] Each tier must be earned sequentially, and progress is preserved when the base is relocated. -- [x] 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) diff --git a/design/user-stories/us-007-reduce-teleport-cooldown.md b/design/user-stories/us-007-reduce-teleport-cooldown.md deleted file mode 100644 index 5ce9016..0000000 --- a/design/user-stories/us-007-reduce-teleport-cooldown.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Cooldown-reduction progress requires Base III. -- [x] Any block broken in Survival mode inside the base's current horizontal and vertical bounds contributes unless excluded by configuration. -- [x] Player-placed blocks may be broken repeatedly for progress. -- [x] The default cooldown is three hours before any cooldown-reduction milestone. -- [x] A configurable 1,000 cumulative blocks reduces the cooldown from three to two hours by default. -- [x] A configurable 2,000 cumulative blocks reduces the cooldown from two hours to one hour by default. -- [x] A configurable 3,000 cumulative blocks reduces the cooldown from one hour to 30 minutes by default. -- [x] A configurable 5,000 cumulative blocks removes the cooldown by default. -- [x] Each tier is sequential and relocating the base preserves earned tiers and progress. -- [x] 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) diff --git a/design/user-stories/us-008-unlock-visitor-access.md b/design/user-stories/us-008-unlock-visitor-access.md deleted file mode 100644 index 9cd2dbc..0000000 --- a/design/user-stories/us-008-unlock-visitor-access.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Visitor warm-ups share the nearby-visible, progressively denser floating particles used by home teleports. -- [x] Successful visitor teleports leave a two-second fading departure cloud; cancellation or failure stops emission without a departure cloud. -- [x] Effects are bounded and cleaned up on shutdown, with regression coverage preserving visitor timing, safety, and cooldowns. - -- [x] Base IV requires Base III and an established base. -- [x] `/basesettings upgrade` offers the Base IV purchase for a configurable price that defaults to 128 diamonds, replacing `/base upgrade` and `/home upgrade`. -- [x] A successful purchase removes the complete price atomically from the player's direct inventory. -- [x] Insufficient funds, an invalid state, or a failed persistence operation does not consume any diamonds or grant Base IV. -- [x] `/basesettings visitors allowed` permits visitor access idempotently for a Base IV owner, and `/basesettings visitors blocked` blocks it idempotently. -- [x] Invalid visitor arguments show command usage, and `allowed` and `blocked` are offered through autocomplete. -- [x] The visitor-access preference persists across reconnects and restarts. -- [x] `/gotobase ` autocompletes bases that the requesting player is currently eligible to visit. -- [x] `/visit ` aliases `/gotobase ` with identical autocomplete, including eligible bases whose owners are offline. -- [x] Enabled bases remain visitable while their owners are offline. -- [x] `/visit` and `/gotobase` require the visitor to be in the destination base's recorded world; cross-dimension requests are rejected before warm-up with a clear message and without consuming cooldown. -- [x] A visitor teleport uses the destination owner's current warm-up tier, but always requires at least a one-second stationary warm-up; `/visit` and `/gotobase` never teleport instantly. -- [x] Looking around is permitted, while movement between block coordinates, damage, teleportation, world change, death, logout, or a conflicting teleport cancels the visitor warm-up. -- [x] Cancellation or destination failure does not consume a visitor cooldown. -- [x] A safe destination is resolved at or near the owner's recorded base center. -- [x] Each visitor has an independent cooldown for each destination owner. -- [x] On successful teleport, the visitor cooldown duration is captured from the destination owner's current cooldown tier. -- [x] A later owner cooldown upgrade applies to future visits without rewriting a cooldown already in progress. -- [x] Visiting another base does not consume or modify the owner's personal `/base` cooldown or the visitor's personal `/base` cooldown. -- [x] 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) -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) diff --git a/design/user-stories/us-009-view-progression-and-notifications.md b/design/user-stories/us-009-view-progression-and-notifications.md deleted file mode 100644 index 602c207..0000000 --- a/design/user-stories/us-009-view-progression-and-notifications.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] `/basesettings status` shows the player's Base, Base Size, Base Flight, Teleport Warm-up, and Teleport Cooldown paths plus current visitor, navigation, flight, and boss-bar settings. -- [x] `/basesettings status` shows whether Pocket Base flight still requires a successful owner raid or has been unlocked. -- [x] Each path identifies earned levels, unmet prerequisites, current progress, the next threshold, and the next reward. -- [x] Locked secondary paths clearly identify Base I or another sequential level as their prerequisite. -- [x] Relevant qualifying activity briefly displays a configurable progress boss bar for the active milestone. -- [x] Boss-bar text and fill accurately represent the current count and threshold and never exceed 100 percent. -- [x] The automatic boss bar disappears after a configurable number of seconds. -- [x] `/basesettings bossbar enable` enables automatic progress boss bars idempotently, and `/basesettings bossbar disable` disables them idempotently. -- [x] Invalid boss-bar arguments show command usage, and `enable` and `disable` are offered through autocomplete. -- [x] Disabling automatic boss bars does not prevent `/basesettings status` from displaying progress. -- [x] The boss-bar preference persists across reconnects and restarts. -- [x] Each newly unlocked level displays prominent full-screen title and subtitle text describing the reward. -- [x] Unlock notifications occur once per earned level and do not repeat after reconnecting or restarting. -- [x] `/homesettings` aliases `/basesettings` with identical behavior and autocomplete. -- [x] Superseded `/baseprogress`, `/basenavigation`, `/baseflight`, and `/basevisitors` commands and their aliases are no longer registered. - -## 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) -- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md) diff --git a/design/user-stories/us-010-administer-player-progression.md b/design/user-stories/us-010-administer-player-progression.md deleted file mode 100644 index 91545c8..0000000 --- a/design/user-stories/us-010-administer-player-progression.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Administrative commands require `spigotbase.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] `/baseadmin status ` displays the player's base, counters, earned path levels, active cooldowns, toggles, and visitor settings. -- [x] `/baseadmin setlevel ` sets an earned path level while enforcing or explicitly granting required preceding levels. -- [x] `/baseadmin setprogress ` updates the selected counter and consistently evaluates reached tiers. -- [x] `/baseadmin reset ` resets a selected path without silently leaving benefits that require it. -- [x] `/baseadmin reset base` is rejected and directs the administrator to the confirmed complete-reset command. -- [x] `/baseadmin reset all` removes the player's base, progression, active cooldowns, and plugin preferences after confirmation. -- [x] Administrators can clear personal and visitor cooldowns independently. -- [x] Administrative commands can update configured block requirements, warm-ups, and cooldowns for each level using validated values. -- [x] Runtime configuration changes are persisted for subsequent restarts. -- [x] Lowered progression requirements are evaluated for a player on their next relevant action rather than immediately updating every stored player. -- [x] Every successful mutation reports exactly what changed, and invalid requests make no partial changes. -- [x] `/homeadmin` aliases `/baseadmin` with identical permission requirements and autocomplete. -- [x] Permission-aware autocomplete offers subcommands, online and known offline players, progression paths, valid levels, progress counters, cooldown types, reset paths and confirmation, and numeric configuration keys. -- [x] Invalid and extra arguments show friendly usage without exposing implementation-specific enum errors or modifying state. - -## 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) diff --git a/design/user-stories/us-011-configure-and-persist-progression.md b/design/user-stories/us-011-configure-and-persist-progression.md deleted file mode 100644 index 51584a8..0000000 --- a/design/user-stories/us-011-configure-and-persist-progression.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -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: done ---- - -# 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 - -- [x] Configuration supports all qualifying materials, progression thresholds, radii, vertical flight limits, warning-buffer distance, warm-ups, cooldowns, prices, particle settings, and notification durations. -- [x] Default values match the progression requirements documented by the related user stories. -- [x] Thresholds and levels are validated as nonnegative, representable, and sequentially coherent where required. -- [x] Radii, vertical ranges, durations, and prices 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 names, base locations, counters, levels, relocation times, teleport times, visitor cooldowns, navigation preferences, flight preferences, boss-bar preferences, and visitor settings. -- [x] UUID-keyed Pocket Base state persists raid-earned flight unlocks, with missing legacy values defaulting safely to locked. -- [x] Pocket Base state persists the owner automatic-flight preference and active flight portal, with safe defaults for legacy records. -- [x] Cooldowns and relocation limits use real elapsed timestamps and continue while players are offline. -- [x] State is saved safely so a failed write does not replace valid persisted state with a partial document. -- [x] Corrupt, unknown, or invalid records are handled defensively and cannot silently grant progression or privileges. -- [x] 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) -- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md) -- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md) diff --git a/design/user-stories/us-012-build-and-release-plugin.md b/design/user-stories/us-012-build-and-release-plugin.md deleted file mode 100644 index 33a8644..0000000 --- a/design/user-stories/us-012-build-and-release-plugin.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -type: User Story -title: "US-012: Build and release the plugin" -description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases. -status: done ---- - -# 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 - -- [x] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain. -- [x] Compiler lint warnings fail the build. -- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle. -- [x] Pushes and pull requests build and test the plugin in Gitea Actions. -- [x] Pull requests validate conventional commit messages. -- [x] CI stores a development JAR as a workflow artifact. -- [x] Main-branch conventional commits drive semantic versioning. -- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release. -- [x] 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) diff --git a/design/user-stories/us-013-visualize-base-border.md b/design/user-stories/us-013-visualize-base-border.md deleted file mode 100644 index 91fbb63..0000000 --- a/design/user-stories/us-013-visualize-base-border.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-013: Visualize the base border" -description: Let players display a bounded, owner-only particle arc along the current edge of their established base. -status: done ---- - -# US-013: Visualize the base border - -As a **player with Base I**, I want to display a particle effect at my base border so that I can understand where base benefits begin and end while building. - -## Acceptance criteria - -- [x] Border visualization requires Base I and an established base. -- [x] `/basesettings border enable` enables visualization idempotently, and `/basesettings border disable` disables it idempotently. -- [x] `border`, `enable`, and `disable` are offered through contextual autocomplete. -- [x] Border visualization is disabled by default and the preference persists across reconnects and restarts. -- [x] Older state files without the preference load it as disabled. -- [x] `/basesettings status` and `/baseadmin status` display the border preference. -- [x] Particles are visible only to the base owner. -- [x] Particles trace the current circular horizontal boundary at the player's current Y-level and follow base expansion or relocation immediately. -- [x] Particles render only while the player is in the base world, within the base's vertical range, and reasonably close to the boundary. -- [x] Particle generation is bounded to avoid excessive server and client load. -- [x] A complete administrative reset disables border visualization. - -## 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) -- [US-010: Administer player progression](us-010-administer-player-progression.md) diff --git a/design/user-stories/us-014-highlight-spawnable-blocks.md b/design/user-stories/us-014-highlight-spawnable-blocks.md deleted file mode 100644 index 1ab1670..0000000 --- a/design/user-stories/us-014-highlight-spawnable-blocks.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -type: User Story -title: "US-014: Highlight spawnable blocks" -description: Unlock an owner-only red particle overlay for nearby hostile-mob spawnable blocks after 250 placements anywhere. -status: done ---- - -# US-014: Highlight spawnable blocks - -As a **player with an established base**, I want to highlight nearby blocks where hostile mobs can spawn so that I can find lighting gaps in my base. - -## Acceptance criteria - -- [x] Every block placed in Survival mode anywhere contributes to a persistent total-placement counter. -- [x] The overlay unlocks permanently at a configurable 250 total placements by default. -- [x] Existing players begin with at least their persisted in-base placement count because those placements are known to qualify. -- [x] `/basesettings spawnable enable` enables the unlocked overlay idempotently, and `/basesettings spawnable disable` disables it idempotently. -- [x] `spawnable`, `enable`, and `disable` are offered through contextual autocomplete. -- [x] Enabling requires both the placement unlock and an established base; the persisted preference defaults to disabled. -- [x] `/basesettings status` and `/baseadmin status` display placement progress, unlock state, and preference. -- [x] Administrators can change a player's total-placement counter through `/baseadmin setprogress`. -- [x] Administrators can persistently change the required placement threshold through `/baseadmin config spawnable-overlay-unlock-placements`. -- [x] Administrators can enable or disable an unlocked player's overlay through `/baseadmin setsetting spawnable `. -- [x] Owner-only red particles mark nearby candidate hostile-mob spawning surfaces inside the current base bounds. -- [x] Candidate surfaces have block light zero, a solid spawning surface, and two passable blocks above them. -- [x] Scanning is bounded to 16 horizontal blocks, eight vertical blocks, and a fixed per-update work and particle budget. -- [x] A complete administrative reset clears total-placement progress and disables the overlay. - -## Related - -- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md) -- [US-009: View progression and notifications](us-009-view-progression-and-notifications.md) -- [US-010: Administer player progression](us-010-administer-player-progression.md) -- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md) diff --git a/design/user-stories/us-015-unlock-a-pocket-base.md b/design/user-stories/us-015-unlock-a-pocket-base.md deleted file mode 100644 index f3ad2f4..0000000 --- a/design/user-stories/us-015-unlock-a-pocket-base.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-015: Unlock a Pocket Base" -description: Let Base IV owners purchase a persistent private void world that serves as the foundation for portal access and expansion. -status: done ---- - -# US-015: Unlock a Pocket Base - -As a **player with an established Base IV**, I want to unlock a persistent Pocket Base so that I can build in a personal space beyond the normal world. - -## Acceptance criteria - -- [x] Pocket Base progression requires an established Base IV. -- [x] `/basesettings pocket upgrade` unlocks Pocket Base I and is offered through contextual autocomplete. -- [x] Unlocking atomically charges a configurable currency and amount that default to 64 diamond blocks. -- [x] Insufficient funds or failed persistence or world creation does not consume currency or grant Pocket Base I. -- [x] Pocket Base I creates a persistent owner-specific void world keyed by the owner's UUID. -- [x] The initial platform is 64 by 64 blocks with one grass layer over three dirt layers. -- [x] The pocket world provides a safe arrival location and a generated return portal. -- [x] Pocket Base worlds, contents, ownership, and progression persist through reconnects, restarts, and normal-base relocation. -- [x] `/basesettings status` displays the current Pocket Base level and the next upgrade requirement. - -## Related - -- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md) -- [US-009: View progression and notifications](us-009-view-progression-and-notifications.md) -- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-023: Craft and use a Pocket Base Keystone](us-023-craft-pocket-base-keystone.md) diff --git a/design/user-stories/us-016-build-and-use-pocket-base-portals.md b/design/user-stories/us-016-build-and-use-pocket-base-portals.md deleted file mode 100644 index 7949500..0000000 --- a/design/user-stories/us-016-build-and-use-pocket-base-portals.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -type: User Story -title: "US-016: Build and use Pocket Base portals" -description: Let an owner create one public portal between their normal base and persistent Pocket Base. -status: done ---- - -# US-016: Build and use Pocket Base portals - -As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base with a public portal so that I and other players can move between them naturally. - -## Acceptance criteria - -- [x] The entrance uses a standard 4-by-5 outer frame with a 2-by-3 interior and a configurable frame material that defaults to diamond blocks. -- [x] Only the Pocket Base owner can activate a complete entrance frame with flint and steel. -- [x] Every required frame block must be within the owner's current normal-base bounds when the entrance is activated. -- [x] Custom particles and collision provide portal-like visuals and travel without relying on vanilla Nether portal blocks. -- [x] Each owner has at most one active entrance portal. -- [x] Activating another valid entrance deactivates the previous entrance without removing its frame blocks. -- [x] Breaking any required frame block immediately deactivates the entrance. -- [x] Any player can use an active entrance without a separate visitor setting, warm-up, or cooldown. -- [x] Non-player living mobs entering an active entrance portal are teleported into that Pocket Base. -- [x] Portal cooldown handling prevents transported mobs from immediately bouncing back. -- [x] Items, projectiles, vehicles, and other non-living entities are not transported. -- [x] Visitors can build, break blocks, open containers, and otherwise interact normally inside the Pocket Base. -- [x] The generated return portal sends players safely to the owner's active entrance. -- [x] Non-player living mobs entering the active, intact return portal are teleported safely outside the normal-world entrance. -- [x] Mob return travel falls back safely to the server spawn when the owner has no valid normal-world entrance. -- [x] Only the owner can activate a complete portal frame inside their own Pocket Base with flint and steel. -- [x] Every required return-frame block must be within the owner's unlocked Pocket Base boundary. -- [x] Each Pocket Base has at most one active return portal, and activating another valid frame moves the active return location without removing the old frame. -- [x] Relocated return portals persist through restarts, while existing Pocket Bases use the generated portal as their default. -- [x] Breaking the active return frame disables return travel through it. -- [x] Return travel falls back to the server spawn when the owner has no valid normal-world entrance. -- [x] Falling below Y -64 performs the same safe return without void damage. -- [x] Portal and void-return travel clears accumulated fall distance so players do not take carried-over fall damage after landing at the destination. -- [x] Players who disconnect inside a Pocket Base remain there when they reconnect. -- [x] Moving the normal base deactivates its entrance while preserving the Pocket Base world and its contents. -- [x] Portal ownership and the active entrance location persist through restarts. -- [x] A separate active gold-block portal inside an owner's Pocket Base can grant temporary controlled flight after raid-earned flight is unlocked. - -## Related - -- [US-003: Expand the base](us-003-expand-the-base.md) -- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md) -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md) -- [US-023: Craft and use a Pocket Base Keystone](us-023-craft-pocket-base-keystone.md) diff --git a/design/user-stories/us-017-expand-a-pocket-base.md b/design/user-stories/us-017-expand-a-pocket-base.md deleted file mode 100644 index 34beb23..0000000 --- a/design/user-stories/us-017-expand-a-pocket-base.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-017: Expand a Pocket Base" -description: Let Pocket Base owners purchase unlimited levels that add permanent buildable terrain around their pocket world. -status: done ---- - -# US-017: Expand a Pocket Base - -As a **Pocket Base owner**, I want to purchase additional buildable space so that my pocket world can grow with my projects. - -## Acceptance criteria - -- [x] Using `/basesettings pocket upgrade` after Pocket Base I purchases the next Pocket Base level. -- [x] Each additional level atomically charges a configurable currency and amount that default to 16 diamond blocks. -- [x] Insufficient funds or failed persistence or terrain generation does not consume currency or grant a level. -- [x] Each level adds 16 blocks on every side, producing Level I at 64 by 64, Level II at 96 by 96, Level III at 128 by 128, and size `64 + 32 × (level - 1)` thereafter. -- [x] Newly unlocked terrain has one grass layer over three dirt layers. -- [x] Expansion preserves all existing blocks, inventories, and entities in previously unlocked terrain. -- [x] Owners and visitors cannot place blocks outside the currently unlocked horizontal boundary. -- [x] Pocket Base progression has no plugin-configured level cap, subject only to Minecraft coordinate and integer limits. -- [x] Pocket Base levels, dimensions, contents, and build boundaries persist through restarts. - -## Related - -- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md) -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) diff --git a/design/user-stories/us-018-control-pocket-base-mob-spawning.md b/design/user-stories/us-018-control-pocket-base-mob-spawning.md deleted file mode 100644 index b60afda..0000000 --- a/design/user-stories/us-018-control-pocket-base-mob-spawning.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-018: Control Pocket Base mob spawning" -description: Let Pocket Base owners control hostile and passive natural mob spawning independently in their private world, with both disabled by default. -status: done ---- - -# US-018: Control Pocket Base mob spawning - -As a **Pocket Base owner**, I want to enable or disable hostile and passive natural mob spawning independently in my Pocket Base so that I can choose which kinds of normal mob activity its private world supports. - -## Acceptance criteria - -- [x] Hostile and passive natural mob spawning are both disabled by default in every new Pocket Base and in existing Pocket Bases that have no saved preference. -- [x] A Pocket Base owner can use `/basesettings pocket mobs hostile enable|disable` to control hostile natural mob spawning in their own Pocket Base. -- [x] A Pocket Base owner can use `/basesettings pocket mobs passive enable|disable` to control passive natural mob spawning in their own Pocket Base. -- [x] Changing one mob category does not change the other category. -- [x] The commands are unavailable until Pocket Base I is unlocked. -- [x] The commands, categories, and modes are offered through contextual autocomplete. -- [x] `/basesettings status` displays the current hostile and passive Pocket Base mob-spawning settings. -- [x] Both preferences persist across restarts and are reapplied when the Pocket Base world loads. -- [x] Existing saved `mob-spawning-enabled` values migrate to both category preferences, preserving prior behavior. -- [x] Disabling either natural-spawning category does not remove existing mobs or prevent explicitly spawned or summoned mobs. -- [x] Persistence or world-application failures produce a clear failure message, restore both prior world flags, and do not report a successful change. - -## Related - -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-019: Change a Pocket Base biome](us-019-change-a-pocket-base-biome.md) diff --git a/design/user-stories/us-019-change-a-pocket-base-biome.md b/design/user-stories/us-019-change-a-pocket-base-biome.md deleted file mode 100644 index 2ffc33a..0000000 --- a/design/user-stories/us-019-change-a-pocket-base-biome.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -type: User Story -title: "US-019: Change a Pocket Base biome" -description: Let Pocket Base owners purchase biome changes that alter natural mob selection without changing their builds. -status: done ---- - -# US-019: Change a Pocket Base biome - -As a **Pocket Base owner**, I want to change my Pocket Base biome so that I can control its biome-specific atmosphere and natural mob selection without rebuilding it. - -## Acceptance criteria - -- [x] A Pocket Base owner can use `/basesettings pocket type ` to select a compatible biome. -- [x] Void supports `the_void`; Nether supports its vanilla biome subtypes; and Overworld supports its vanilla biome subtypes. -- [x] New and previously unconfigured Pocket Bases default to the void type and `the_void` subtype. -- [x] Each change atomically charges a configurable currency and amount that default to 16 netherite blocks. -- [x] Selecting the active subtype or providing an invalid type/subtype combination is rejected without charging. -- [x] Changing subtypes within the same type incurs the configured cost. -- [x] The selected biome is applied across every unlocked Pocket Base column without changing blocks, entities, inventories, portals, level, or the mob-spawning preference. -- [x] Newly unlocked terrain receives the selected biome. -- [x] When natural mob spawning is enabled, Minecraft can use the selected biome for applicable natural mob selection. -- [x] The selected type and subtype persist through restarts and appear in `/basesettings status`. -- [x] The command, types, and compatible subtypes are offered through contextual autocomplete. -- [x] Failed biome application or persistence restores the prior biome and does not consume payment. - -## Related - -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-018: Control Pocket Base mob spawning](us-018-control-pocket-base-mob-spawning.md) diff --git a/design/user-stories/us-020-control-base-through-dialog-ui.md b/design/user-stories/us-020-control-base-through-dialog-ui.md deleted file mode 100644 index 314ec6d..0000000 --- a/design/user-stories/us-020-control-base-through-dialog-ui.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -type: User Story -title: "US-020: Control a base through a dialog UI" -description: Let players inspect and control their base through Minecraft's native dialog interface. -status: done ---- - -# US-020: Control a base through a dialog UI - -As a **player**, I want a dialog-based base dashboard so that I can inspect progression and manage my base without remembering command arguments. - -## Acceptance criteria - -- [x] `/basesettings` and `/basesettings ui` open the base-control dialog. -- [x] `/homesettings` and `/homesettings ui` behave identically. -- [x] `/basesettings status` retains the chat-based progression report. -- [x] The dialog summarizes current Base and Pocket Base progression. -- [x] Dialog controls cover visitors, navigation, flight, border, spawnable overlay, boss bar, Pocket Base mob spawning, upgrades, and biome selection when applicable. -- [x] The Pocket Base dialog shows whether owner flight still requires a successful raid and lets an unlocked owner enable or disable automatic Pocket Base flight. -- [x] Nested dialog screens provide Back buttons that return to the main Base Settings dashboard. -- [x] Controls indicate their current or locked state. -- [x] Purchases require confirmation and continue using existing validation, payment, and persistence logic. -- [x] `ui` is offered through command autocomplete. -- [x] Non-player execution remains safely rejected. -- [x] Automated tests verify dialog routing and generated controls. -- [x] Fixed dialog commands use Purpur static run-command actions rather than macro templates. -- [x] A rendering regression test verifies fixed command buttons do not throw `No variables in macro`. -- [x] The dialog uses Purpur's supported Paper dialog API and opens on the production Purpur 26.2 runtime without missing-class or command exceptions. - -## Related - -- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md) -- [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md) -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-018: Control Pocket Base mob spawning](us-018-control-pocket-base-mob-spawning.md) -- [US-019: Change a Pocket Base biome](us-019-change-a-pocket-base-biome.md) -- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md) -- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md) diff --git a/design/user-stories/us-021-unlock-pocket-base-flight.md b/design/user-stories/us-021-unlock-pocket-base-flight.md deleted file mode 100644 index 855f4ce..0000000 --- a/design/user-stories/us-021-unlock-pocket-base-flight.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -type: User Story -title: "US-021: Unlock Pocket Base flight" -description: Let a Pocket Base owner permanently earn controlled flight by winning a raid in their own pocket world. -status: done ---- - -# US-021: Unlock Pocket Base flight - -As a **Pocket Base owner**, I want to earn flight by completing a raid in my Pocket Base so that I can build and travel safely throughout my expanding pocket world. - -## Acceptance criteria - -- [x] Pocket Base flight begins locked for new owners and existing saved Pocket Bases. -- [x] A successful raid completed in a Pocket Base permanently unlocks flight only when that Pocket Base's owner is listed among the raid winners. -- [x] Raids completed outside the owner's Pocket Base and raids the owner does not win do not unlock flight. -- [x] Defeated, stopped, expired, and abandoned raids do not unlock flight. -- [x] Unlocking Pocket Base flight is free and does not consume blocks or other currency. -- [x] The owner receives a prominent one-time unlock notification after the qualifying raid. -- [x] In Survival mode, an owner with the unlock can enable or disable automatic plugin-granted flight inside their own Pocket Base without affecting portal-granted temporary flight. -- [x] Pocket Base flight spans the world's full build height and the current unlocked horizontal boundary plus 16 blocks on every side. -- [x] An actively flying owner receives a warning after leaving the unlocked Pocket Base boundary while remaining inside the 16-block buffer. -- [x] Moving beyond the 16-block buffer removes only flight granted by this plugin. -- [x] Pocket Base expansion automatically expands the corresponding flight area. -- [x] Visitors do not receive the owner's Pocket Base flight privilege. -- [x] Teleportation, world changes, game-mode changes, death, logout, and plugin shutdown do not leave unintended flight enabled. -- [x] The unlock persists across reconnects and restarts. -- [x] Chat status and the native settings dialog show whether Pocket Base flight is locked behind a successful raid or unlocked. - -## Related - -- [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md) -- [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) -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-020: Control a base through a dialog UI](us-020-control-base-through-dialog-ui.md) -- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md) diff --git a/design/user-stories/us-022-share-pocket-base-flight-through-a-portal.md b/design/user-stories/us-022-share-pocket-base-flight-through-a-portal.md deleted file mode 100644 index 21fa2fd..0000000 --- a/design/user-stories/us-022-share-pocket-base-flight-through-a-portal.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: User Story -title: "US-022: Share Pocket Base flight through a portal" -description: Let an owner build a gold-block portal that temporarily grants controlled Pocket Base flight to players who pass through it. -status: done ---- - -# US-022: Share Pocket Base flight through a portal - -As a **Pocket Base owner**, I want an activated flight portal inside my Pocket Base so that I can temporarily share controlled flight with guests without changing my own default-flight preference. - -## Acceptance criteria - -- [x] Entering the active flight portal immediately starts eligible Survival players flying without double-jumping. -- [x] Each portal entry sends “Pocket dimension flight enabled!” without repeated messages while standing in the portal. -- [x] Immediate takeoff preserves existing flight boundaries and expiry rules, with regression tests. - -- [x] The owner must first unlock Pocket Base flight by winning a raid in their own Pocket Base. -- [x] Only the owner can activate a complete 4-by-5 gold-block frame with flint and steel as the active flight portal. -- [x] Every required frame block must be inside the owner's currently unlocked Pocket Base boundary at activation. -- [x] Each Pocket Base has at most one active flight portal, and activating another valid frame moves the active location without removing the old frame. -- [x] The active flight portal uses custom particles and collision without vanilla Nether portal blocks. -- [x] Breaking any required block in the active frame deactivates the flight portal. -- [x] Any player, including the owner or a guest, who passes through the active intact flight portal receives temporary Pocket Base flight. -- [x] Portal-granted flight remains independent of the owner's default Pocket Base flight preference. -- [x] Portal-granted flight spans the world's full build height and the current Pocket Base boundary plus 16 blocks on every side. -- [x] An actively flying player receives a warning inside the 16-block buffer, and flight ends beyond it. -- [x] Expanding the Pocket Base automatically expands the portal-granted flight area. -- [x] Portal-granted flight ends when the player leaves the Pocket Base, dies, disconnects, or changes out of Survival mode. -- [x] The active flight portal location and owner default-flight preference persist across restarts. -- [x] Existing saved Pocket Bases default to no flight portal while preserving raid-earned owner flight as enabled. - -## Related - -- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md) -- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md) -- [US-020: Control a base through a dialog UI](us-020-control-base-through-dialog-ui.md) -- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md) diff --git a/design/user-stories/us-023-craft-pocket-base-keystone.md b/design/user-stories/us-023-craft-pocket-base-keystone.md deleted file mode 100644 index bf6e9af..0000000 --- a/design/user-stories/us-023-craft-pocket-base-keystone.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: User Story -title: "US-023: Craft and use a Pocket Base Keystone" -description: Let Pocket Base owners craft a reusable item for instant round-trip travel between their current location and their private dimension. -status: done ---- - -# US-023: Craft and use a Pocket Base Keystone - -As a **Pocket Base owner**, I want to craft a reusable keystone that instantly takes me into my Pocket Base and back so that I can access my private dimension without finding a portal. - -## Acceptance criteria - -- [x] The Pocket Base Keystone is a distinct Recovery Compass identified by persistent item metadata rather than its display name alone. -- [x] Keystone creation accepts the valid generic item metadata supplied for Recovery Compasses by the supported Purpur runtime. -- [x] Its shaped recipe places an Ender Pearl in the center, Netherite Ingots on the four cardinal slots, and Obsidian in the four corners. -- [x] Only a player who has unlocked Pocket Base I can complete the recipe or use a keystone. -- [x] Right-clicking a keystone outside a Pocket Base instantly teleports the player to their own Pocket Base arrival point. -- [x] Entering records the player's exact prior world, position, yaw, and pitch as the return destination. -- [x] Right-clicking a keystone inside the player's own Pocket Base returns them safely to the recorded destination. -- [x] Return destinations persist across logout and server restart. -- [x] Missing worlds and unsafe destinations fail safely without replacing or discarding the recorded return destination. -- [x] A keystone is reusable, has no warm-up or cooldown, and always accesses the user's own unlocked Pocket Base even when transferred between players. -- [x] Keystone travel clears accumulated fall distance and does not change existing portal travel behavior. -- [x] Automated tests cover recipe shape, crafting and use eligibility, metadata authentication, entry, return, persistence, and unavailable or unsafe destinations. - -- [x] Keystone entry and return work when right-clicking air or blocks, regardless of facing direction. -- [x] Vanilla no-action events are handled without bypassing explicit item-use restrictions. -- [x] Regression tests cover air and block interactions for entry and return, and denied item use. - -## Verification - -- `./gradlew clean check jar` passes, including event-dispatch regression coverage for air/block entry and return and explicit item-use denial. -- Live-server verification remains pending deployment. - -## Related - -- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md) -- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md)