chore(knowledge): move canonical docs to shared SoMC wiki
This commit is contained in:
@@ -1,40 +1,9 @@
|
||||
# Spigot Quest Board Agent Guide
|
||||
# spigot-quest-board agent entrypoint
|
||||
|
||||
## Project
|
||||
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).
|
||||
|
||||
Spigot Quest Board is a Java 25 plugin for Purpur 26.2. It provides shared physical quest boards where players escrow rewards, deliver requested block items, and claim delivered or returned items.
|
||||
Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-quest-board/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-quest-board/` stories. Also follow the parent workspace `AGENTS.md` when present.
|
||||
|
||||
## Canonical knowledge
|
||||
For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-quest-board/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.
|
||||
|
||||
- `knowledge/` is the canonical OKF v0.1 knowledge bundle.
|
||||
- Read `knowledge/index.md` and the relevant documents in `knowledge/user-stories/` before changing behavior.
|
||||
- Every feature or behavior change requires an approved user story with task-list acceptance criteria.
|
||||
- Preserve unknown YAML frontmatter fields when editing knowledge documents.
|
||||
- Keep `knowledge/index.md`, `knowledge/log.md`, and `knowledge/user-stories/index.md` current.
|
||||
|
||||
## Development
|
||||
|
||||
- Compile against the Purpur API version declared in `build.gradle.kts`.
|
||||
- Use Java 25 and enable strict compiler linting.
|
||||
- Prefer small, server-independent domain objects and services that can be unit tested.
|
||||
- Use test-driven development where practical: add a failing test, implement the minimum behavior, then refactor.
|
||||
- Treat escrow, completion, cancellation, expiry, and claiming as atomic state transitions. Never duplicate or silently discard player items.
|
||||
- Key players by UUID, not display name.
|
||||
- Persist board, quest, escrow, and claim state safely across restarts using atomic file replacement where supported.
|
||||
- Use UTC and RFC 3339 timestamps for persisted or documented date-times.
|
||||
- Keep player-facing command autocomplete permission-aware and context-sensitive.
|
||||
- Use Purpur's supported Paper dialog API for native dialog interfaces.
|
||||
|
||||
## Verification
|
||||
|
||||
Run before completing a story:
|
||||
|
||||
```bash
|
||||
./gradlew clean check jar
|
||||
```
|
||||
|
||||
Mark acceptance criteria complete only after implementation and verification.
|
||||
|
||||
## Git
|
||||
|
||||
Use conventional commits in the form `type(scope): description`, with summaries under 72 characters.
|
||||
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.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
A Purpur 26.2 plugin for shared physical quest boards. Players can escrow rewards for requested items, deliver those items at any quest board, and claim delivered or returned items safely.
|
||||
|
||||
The approved behavior is specified in the [OKF knowledge bundle](knowledge/index.md).
|
||||
The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-quest-board/index.md).
|
||||
|
||||
## Status
|
||||
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: Spigot Quest Board Knowledge
|
||||
description: Entry point for the Spigot Quest Board OKF knowledge bundle.
|
||||
okf_version: "0.1"
|
||||
---
|
||||
|
||||
# Spigot Quest Board Knowledge
|
||||
|
||||
This bundle specifies shared physical quest boards, reward escrow, item deliveries, item claims, player commands, administration, persistence, and plugin delivery requirements.
|
||||
|
||||
Login guidance is covered by [quest browsing](user-stories/us-004-browse-available-quests.md) and [recurring pending-item reminders](user-stories/us-007-expire-quests-and-claim-held-items.md).
|
||||
|
||||
## Explore
|
||||
|
||||
- [User stories](user-stories/index.md)
|
||||
- [Knowledge log](log.md)
|
||||
@@ -1,135 +0,0 @@
|
||||
---
|
||||
type: Log
|
||||
title: Spigot Quest Board Knowledge Log
|
||||
description: Chronological record of material decisions affecting Spigot Quest Board.
|
||||
---
|
||||
|
||||
# Spigot Quest Board Knowledge Log
|
||||
|
||||
## 2026-09-10T01:38:21Z — Inventory-item quest requests
|
||||
|
||||
- Extended [US-003](user-stories/us-003-create-a-block-delivery-quest.md) and [US-005](user-stories/us-005-deliver-blocks-and-complete-a-quest.md) to support inventory item materials, including shulker shells, rather than only blocks.
|
||||
- Validation and autocomplete use item eligibility and reject air and non-item materials; command, dialog, notification, and claim wording now describes items.
|
||||
- Preserved the persistence format and existing escrow, delivery, and claim transitions.
|
||||
- Confirmed catalog regressions failed before the fix using mocked server material properties, then verified shell creation, persisted settlement and claim acknowledgement, and existing regressions: all 134 tests and the plugin JAR passed `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Initial quest-board design
|
||||
|
||||
- Administrators create physical quest boards, and every board exposes the same global quests and claims.
|
||||
- Players create quests by selecting a requested block material and quantity and escrowing reward items from their inventory.
|
||||
- Completing players deliver the requested block items at a board and immediately receive the escrowed reward.
|
||||
- Delivered blocks remain held by the quest system until the issuer claims them at a board.
|
||||
- Cancelled and seven-day-expired quests return escrowed rewards through the same claim system rather than direct inventory delivery.
|
||||
- Inventory overflow from rewards or claims is dropped at the receiving player's feet.
|
||||
- Player `/quests` commands are disabled by default so administrators can require physical-board interaction.
|
||||
- The board interface follows Spigot Base by using Purpur's supported native dialog API.
|
||||
|
||||
## 2026-09-05 — Foundation started
|
||||
|
||||
- Approved work begins with an OKF knowledge bundle, Java 25/Purpur 26.2 Gradle foundation, automated verification, and a public Gitea repository.
|
||||
|
||||
## 2026-09-05 — Foundation completed
|
||||
|
||||
- Published the project to the public `dmg/spigot-quest-board` Gitea repository.
|
||||
- Added strict Java 25/Purpur 26.2 Gradle builds, plugin metadata, a metadata regression test, and CI/release workflows modeled on Spigot Base.
|
||||
- Verified the plugin foundation and JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Shared physical quest boards
|
||||
|
||||
- Added durable world-UUID and block-coordinate board registration through `/questadmin createboard`.
|
||||
- Registered main-hand interactions open one shared native Purpur dialog while unregistered blocks remain untouched.
|
||||
- Persistence publishes a board only after an atomic YAML save succeeds and rejects duplicate locations.
|
||||
- Verified 11 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Quest creation and reward escrow
|
||||
|
||||
- Added board-dialog and `/quests create <block> <quantity>` creation using a valid block material, positive quantity, and the exact held reward stack.
|
||||
- Escrow preserves full Bukkit item metadata in durable Base64-backed YAML and rolls inventory removal back if persistence fails.
|
||||
- Quests receive UUID identifiers and UTC creation and seven-day expiration timestamps.
|
||||
- Verified 26 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Shared quest browsing
|
||||
|
||||
- Added globally shared active-quest listings to every board and to `/quests` and `/quests list`.
|
||||
- Listings include requested blocks, exact reward summaries, issuer names, and boundary-safe remaining durations.
|
||||
- Added persisted lifecycle status with backward-compatible active defaults and filtered stale quest IDs from contextual completion and cancellation suggestions.
|
||||
- Verified 37 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Block delivery and quest completion
|
||||
|
||||
- Added board actions and `/quests complete <quest>` for exact requested-material delivery from player inventories.
|
||||
- Completion serializes state transitions, holds delivered blocks in durable issuer claims, and grants exact escrowed rewards with owner-protected overflow drops.
|
||||
- Added durable online and next-login issuer notifications and rollback before persistence succeeds.
|
||||
- Verified 49 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Issuer quest cancellation
|
||||
|
||||
- Added issuer-only board actions and `/quests cancel <quest>` with ownership-filtered autocomplete.
|
||||
- Cancellation atomically moves exact reward escrow into an issuer claim without directly changing inventory.
|
||||
- Serialized cancellation against completion and retained active state when persistence fails.
|
||||
- Verified 58 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Quest expiration and held-item claims
|
||||
|
||||
- Added boundary-safe scheduled expiration that moves exact rewards into durable issuer claims.
|
||||
- Added claim collection at every board and through `/quests claim`, distinguishing delivered blocks from cancelled or expired reward returns.
|
||||
- Inventory overflow drops at the claimant's feet with ownership protection, and failed claim acknowledgement rolls inventory and drops back before retry.
|
||||
- Added persisted online and next-login expiry notifications.
|
||||
- Verified 73 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Administrative player-command control
|
||||
|
||||
- Disabled all player `/quests` command forms and autocomplete by default while preserving equivalent physical-board actions.
|
||||
- Added persistent `/questadmin commands enable|disable` control with permission-aware autocomplete and failure-safe updates.
|
||||
- Kept administrative board creation available independently of the player-command setting.
|
||||
- Verified 82 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Screen-fitting quest-board dialogs
|
||||
|
||||
- Replaced the clipped 800-pixel combined board screen with a compact 420-pixel dashboard.
|
||||
- Split browsing, creation, and claims into dedicated native dialog screens with Back navigation.
|
||||
- Presented active quests as individual detail dialogs while retaining completion and issuer cancellation actions.
|
||||
- Verified 88 tests, including a 250-quest navigation case, and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Generated physical quest boards
|
||||
|
||||
- Added `/questadmin createboard physical` to generate a five-wide, four-tall board above the targeted ground anchor facing the administrator.
|
||||
- Used oak-log pillars, an oak-plank face, and three oak wall signs with obfuscated decorative text.
|
||||
- Registered all visible planks and signs in one durable operation and added obstruction checks plus block rollback when construction or persistence fails.
|
||||
- Preserved existing single-block board creation and persisted board compatibility.
|
||||
- Verified 103 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Readable physical-board signage
|
||||
|
||||
- Added centered `Quest Board` and right-click instruction signs on the two layers above each generated board's three decorative signs.
|
||||
- Registered all five signs and the plank face as shared-board interaction locations.
|
||||
- Added exact legacy-structure detection and failure-safe startup upgrades for previously generated three-sign boards without touching custom or altered structures.
|
||||
- Verified 111 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Glowing readable board signs
|
||||
|
||||
- Enabled glowing front-side text on generated title and instruction signs while retaining non-glowing decorative signs.
|
||||
- Added exact full-structure detection to refresh existing generated boards once without modifying custom or altered signs.
|
||||
- Added two-sign snapshot rollback when a refresh cannot complete safely.
|
||||
- Verified 116 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Nearby command-based quest creation
|
||||
|
||||
- Allowed `/quests create <block> <quantity>` and its material and quantity autocomplete within five blocks of any registered board location even while global player commands are disabled.
|
||||
- Kept listing, completion, cancellation, and claiming commands disabled under that setting while preserving global command behavior when enabled.
|
||||
- Enforced same-world Euclidean proximity with an inclusive five-block boundary for custom and generated boards.
|
||||
- Verified 121 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-05 — Named reward identification
|
||||
|
||||
- Displayed custom reward names together with their material type in shared board details and command listings, such as `1 × Shopping List (PAPER)`.
|
||||
- Stored safe plain-text custom names alongside unchanged exact item metadata and inferred names from valid historical escrow data when possible.
|
||||
- Kept malformed or unavailable metadata from blocking quest browsing by falling back to material descriptions.
|
||||
- Verified 128 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
|
||||
## 2026-09-07T01:31:27Z — Login quest guidance and recurring claim reminders
|
||||
|
||||
- Extended [US-004](user-stories/us-004-browse-available-quests.md) with a private active, unexpired quest count on every login and guidance to visit the quest board to accept or create a quest.
|
||||
- Extended [US-007](user-stories/us-007-expire-quests-and-claim-held-items.md) with reminders on every login while actual pending claims remain, independently of notification acknowledgement and across reloads.
|
||||
- Preserved existing real-time and durable notifications without changing claim storage or collection.
|
||||
- Confirmed new behavior tests failed before implementation, then verified all 130 tests and the plugin JAR with `./gradlew clean check jar`.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: Spigot Quest Board User Stories
|
||||
description: Catalog of user stories for the Spigot Quest Board plugin.
|
||||
---
|
||||
|
||||
# Spigot Quest Board User Stories
|
||||
|
||||
1. [US-001: Build and release the plugin](us-001-build-and-release-plugin.md)
|
||||
2. [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
3. [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
4. [US-004: Browse available quests](us-004-browse-available-quests.md) — includes login quest counts and board guidance.
|
||||
5. [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
|
||||
6. [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md)
|
||||
7. [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) — includes recurring login reminders for unclaimed items.
|
||||
8. [US-008: Control player quest commands](us-008-control-player-quest-commands.md)
|
||||
9. [US-009: Use a screen-fitting quest-board interface](us-009-use-a-screen-fitting-quest-board-interface.md)
|
||||
10. [US-010: Generate a physical quest-board structure](us-010-generate-a-physical-quest-board.md)
|
||||
11. [US-011: Add readable physical-board signage](us-011-add-readable-physical-board-signage.md)
|
||||
12. [US-012: Create quests by command near a board](us-012-create-quests-near-a-board.md)
|
||||
13. [US-013: Show custom reward item names](us-013-show-custom-reward-item-names.md)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-001: Build and release the plugin"
|
||||
description: Give maintainers repeatable Purpur builds, automated verification, and versioned public Gitea releases.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-001: Build and release the plugin
|
||||
|
||||
As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested, correctly versioned artifacts can be distributed consistently.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [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] Plugin metadata declares the entrypoint, player and admin commands, and permissions.
|
||||
- [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] The project is published in the public `dmg/spigot-quest-board` Gitea repository.
|
||||
- [x] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Quest Board names and identifiers.
|
||||
|
||||
## Related
|
||||
|
||||
- [User-story catalog](index.md)
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-002: Create and use shared quest boards"
|
||||
description: Let administrators establish persistent physical boards that expose one shared quest system.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-002: Create and use shared quest boards
|
||||
|
||||
As an **administrator**, I want to turn a targeted block into a quest board so that players can interact with quests at controlled physical locations.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] An authorized administrator can use `/questadmin createboard` to register the block they are targeting.
|
||||
- [x] Creation rejects a missing, invalid, or already registered target without changing state.
|
||||
- [x] Registered boards persist across server restarts with their world and block coordinates.
|
||||
- [x] Interacting with any registered board opens the quest-board interface.
|
||||
- [x] Every registered board exposes the same global quests and claimable items.
|
||||
- [x] The interface uses Purpur's supported native dialog API and follows the interaction style of Spigot Base.
|
||||
- [x] Ordinary block interaction is not intercepted at unregistered locations.
|
||||
- [x] Administrative actions require the `spigotquestboard.admin` permission, granted to server operators by default.
|
||||
- [x] Automated tests verify board registration, persistence, shared visibility, authorization, and interaction routing.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-004: Browse available quests](us-004-browse-available-quests.md)
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-003: Create an item-delivery quest"
|
||||
description: Let a player request inventory items while safely escrowing an inventory-funded reward.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-003: Create an item-delivery quest
|
||||
|
||||
As a **player**, I want to request an item material and quantity in exchange for items I already own so that another player can fulfill my request safely.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Requests accept all inventory item materials, including shulker shells and existing block items, while rejecting air, invalid names, and non-item materials.
|
||||
- [x] Contextual material autocomplete includes non-block items; command and dialog wording describes items rather than only blocks.
|
||||
- [x] Regression tests verify shell creation, autocomplete, and existing block-item support.
|
||||
|
||||
- [x] A player can create a quest through a registered quest board by selecting a valid item material, a positive quantity, and reward items from their inventory.
|
||||
- [x] Reward items must exist in the issuer's inventory and are removed only when quest creation succeeds.
|
||||
- [x] Removed rewards are held durably in escrow by the quest system.
|
||||
- [x] A created quest records a unique identifier, issuer UUID and current name, requested material and quantity, exact reward items, creation time, and expiration time.
|
||||
- [x] Each quest expires exactly seven days after successful creation.
|
||||
- [x] Invalid input, insufficient reward items, or persistence failure leaves the issuer's inventory unchanged and creates no quest.
|
||||
- [x] When player commands are enabled, `/quests create ...` provides equivalent validated creation behavior with contextual autocomplete.
|
||||
- [x] Quest state and item metadata survive server restarts without duplication or loss.
|
||||
- [x] Automated tests verify validation, escrow, rollback, timestamps, command routing, and persistence.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
|
||||
- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-004: Browse available quests"
|
||||
description: Let players inspect globally available quests and their essential terms.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-004: Browse available quests
|
||||
|
||||
As a **player**, I want to browse current quests so that I can decide which block deliveries to fulfill.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Every registered board lists the same active quests.
|
||||
- [x] Each listing shows the requested block material, quantity, reward, issuer, and time remaining.
|
||||
- [x] Remaining durations are clear and never display an expired quest as active.
|
||||
- [x] Completed, cancelled, and expired quests are excluded from the active listing.
|
||||
- [x] When player commands are enabled, `/quests` and `/quests list` provide the same active quest information in chat.
|
||||
- [x] Listing and autocomplete do not expose stale quest identifiers as completable or cancellable.
|
||||
- [x] Automated tests verify filtering, displayed fields, duration boundaries, and command aliases.
|
||||
|
||||
- [x] Every login privately reports the global active, unexpired quest count with natural zero and singular wording, followed by “Visit the quest board to accept or create a quest.”
|
||||
- [x] Automated tests verify repeated login summaries, count wording, and exclusion of completed, cancelled, and expired quests.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
|
||||
- [US-013: Show custom reward item names](us-013-show-custom-reward-item-names.md)
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-005: Deliver items and complete a quest"
|
||||
description: Let a player deliver requested items at a quest board and receive the escrowed reward.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-005: Deliver items and complete a quest
|
||||
|
||||
As a **player**, I want to deliver requested items to a quest board so that I receive the promised reward and the issuer can claim my delivery.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Non-block requested items, including shulker shells, can be delivered and held for issuer claiming using existing escrow and rollback protections.
|
||||
- [x] Delivery notifications and claim messages refer to items, and regression tests verify shell settlement and existing block deliveries.
|
||||
|
||||
- [x] An active quest offers a Complete Quest action through every registered board.
|
||||
- [x] Completion requires the delivering player to possess the full requested quantity of the exact item material.
|
||||
- [x] Successful completion removes the requested items from the delivering player's inventory and stores them as a claim for the issuer.
|
||||
- [x] Successful completion gives the exact escrowed reward items to the delivering player.
|
||||
- [x] Reward items that do not fit are dropped safely at the delivering player's feet with a clear message.
|
||||
- [x] The issuer is notified immediately when online or on their next login when offline that delivered items can be claimed at a quest board.
|
||||
- [x] When player commands are enabled, `/quests complete <quest>` provides equivalent behavior with contextual autocomplete.
|
||||
- [x] Completion is atomic and exactly one player can complete a quest, including simultaneous attempts.
|
||||
- [x] Validation or persistence failure does not consume delivered items, release rewards, or change quest state.
|
||||
- [x] Completed quests are no longer shown as active or completable.
|
||||
- [x] Automated tests verify inventory validation, settlement, overflow, notifications, rollback, and concurrent completion protection.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-006: Cancel an owned quest"
|
||||
description: Let an issuer cancel an active quest and reclaim its escrowed reward safely.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-006: Cancel an owned quest
|
||||
|
||||
As a **quest issuer**, I want to cancel my active quest so that I can reclaim the reward when I no longer need the requested blocks.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] An issuer can cancel their own active quest through any registered board.
|
||||
- [x] A player cannot cancel a quest issued by another player.
|
||||
- [x] Completed, cancelled, and expired quests cannot be cancelled.
|
||||
- [x] Cancellation removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer.
|
||||
- [x] The reward is not inserted directly into the issuer's inventory during cancellation.
|
||||
- [x] When player commands are enabled, `/quests cancel <quest>` provides equivalent behavior and only autocompletes the player's cancellable quest identifiers.
|
||||
- [x] Cancellation and simultaneous completion are serialized so items cannot be duplicated or lost.
|
||||
- [x] Persistence failure leaves the quest active and its reward escrowed.
|
||||
- [x] Automated tests verify ownership, state validation, claim creation, autocomplete, rollback, and completion races.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-007: Expire quests and claim held items"
|
||||
description: Hold delivered blocks and returned rewards until their owner safely claims them.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-007: Expire quests and claim held items
|
||||
|
||||
As a **quest issuer**, I want delivered blocks and returned rewards held at the shared quest board so that I can retrieve them safely.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] An uncompleted quest expires seven days after its creation time.
|
||||
- [x] Expiration removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer.
|
||||
- [x] Completed-quest claims contain the exact block items delivered by the completing player.
|
||||
- [x] Claims from completion, cancellation, and expiration can be collected through any registered board.
|
||||
- [x] The board clearly distinguishes delivered blocks from returned rewards.
|
||||
- [x] Online issuers receive a real-time message when items become claimable.
|
||||
- [x] Offline issuers receive a message on their next login.
|
||||
- [x] When player commands are enabled, `/quests claim` collects the same pending claims.
|
||||
- [x] Items are inserted into the claimant's inventory where space permits; overflow is dropped safely at their feet with a clear message.
|
||||
- [x] A claim is removed only after all of its items have been inserted or dropped successfully.
|
||||
- [x] Pending claims and notification state survive logout and server restart without duplication or loss.
|
||||
- [x] Automated tests verify expiry boundaries, each claim source, notifications, overflow, failure recovery, and persistence.
|
||||
|
||||
- [x] Every login with pending claims shows “You have items waiting to be claimed. Visit the quest board to collect them.” independently of previous notification delivery.
|
||||
- [x] Reminders stop once all items are claimed, preserve real-time notifications, and do not change claims or item storage.
|
||||
- [x] Automated tests verify recurring reminders across logins and reloads, isolation by player, and silence after collection.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
|
||||
- [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-008: Control player quest commands"
|
||||
description: Let administrators require physical-board interaction by controlling access to player quest commands.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-008: Control player quest commands
|
||||
|
||||
As an **administrator**, I want to enable or disable player quest commands so that I can require players to use physical quest boards.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Player `/quests` commands are disabled by default.
|
||||
- [x] An authorized administrator can use `/questadmin commands enable|disable` with contextual autocomplete.
|
||||
- [x] The command setting persists across server restarts.
|
||||
- [x] When disabled, `/quests`, `list`, `complete`, `cancel`, and `claim` reject execution with a clear message directing the player to a quest board; nearby creation follows [US-012](us-012-create-quests-near-a-board.md).
|
||||
- [x] Disabling commands does not prevent any equivalent action through a registered board.
|
||||
- [x] `/questadmin` remains available to authorized administrators regardless of the player-command setting.
|
||||
- [x] Unauthorized users cannot change the setting.
|
||||
- [x] Automated tests verify the default, persistence, authorization, every gated subcommand, and autocomplete.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)
|
||||
- [US-012: Create quests by command near a board](us-012-create-quests-near-a-board.md)
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-009: Use a screen-fitting quest-board interface"
|
||||
description: Split the oversized quest-board dialog into compact navigable screens that fit the player's display.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-009: Use a screen-fitting quest-board interface
|
||||
|
||||
As a **player**, I want the quest-board interface to fit on screen so that I can read quest information and reach every action.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] The oversized combined dialog is replaced by a compact dashboard.
|
||||
- [x] Dialog message bodies use a maximum width of 420 pixels.
|
||||
- [x] Browsing, quest creation, and pending claims use dedicated screens rather than one combined body.
|
||||
- [x] Active quests are presented as individual navigable entries instead of one unbounded text listing.
|
||||
- [x] Each quest detail shows its issuer, requested material and quantity, reward, and time remaining.
|
||||
- [x] Completion, issuer-only cancellation, creation, and claim collection remain available through the board.
|
||||
- [x] Nested screens provide Back controls that return toward the quest-board dashboard.
|
||||
- [x] Large active-quest collections remain navigable without producing an unbounded single dialog.
|
||||
- [x] Automated tests verify width limits, screen separation, navigation, displayed content, and action routing.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-004: Browse available quests](us-004-browse-available-quests.md)
|
||||
- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
|
||||
- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md)
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-010: Generate a physical quest-board structure"
|
||||
description: Let an administrator generate and register a decorative oak quest board at a targeted ground anchor.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-010: Generate a physical quest-board structure
|
||||
|
||||
As an **administrator**, I want quest-board creation to optionally construct a recognizable physical board so that I do not need to build each board manually.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `/questadmin createboard physical` generates and registers a physical quest board while the existing `/questadmin createboard` behavior remains unchanged.
|
||||
- [x] The targeted block is treated as the ground anchor and remains unchanged.
|
||||
- [x] The generated board faces the administrator and is five blocks wide and four blocks tall.
|
||||
- [x] The outer columns use oak-log pillars and the center uses oak planks.
|
||||
- [x] Oak wall signs on the front display decorative obfuscated or gibberish text.
|
||||
- [x] Clicking generated visible planks or signs opens the same globally shared quest-board interface.
|
||||
- [x] Generation requires empty space and refuses to overwrite an existing structure.
|
||||
- [x] Structure generation and interaction-location registration form one failure-safe transaction; failure restores changed blocks and registers nothing.
|
||||
- [x] Generated interaction locations persist across restarts and remain compatible with existing registered boards.
|
||||
- [x] The `physical` argument is offered through permission-aware command autocomplete.
|
||||
- [x] Automated tests verify geometry, facing direction, obstruction handling, rollback, registration, persistence, and autocomplete.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-009: Use a screen-fitting quest-board interface](us-009-use-a-screen-fitting-quest-board-interface.md)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-011: Add readable physical-board signage"
|
||||
description: Give generated quest boards a readable title and browsing instruction above their decorative signs.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-011: Add readable physical-board signage
|
||||
|
||||
As a **player**, I want readable signs on a generated quest board so that I know what it is and how to open it.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] A generated physical board has a centered top sign reading `Quest Board` across its sign lines.
|
||||
- [x] A centered sign immediately below instructs the player to right-click a sign below to browse quests.
|
||||
- [x] The existing lower row retains three decorative signs with obfuscated or gibberish text.
|
||||
- [x] All five signs and the visible oak planks open the globally shared quest-board interface.
|
||||
- [x] New physical boards reserve and validate space for all five signs without overwriting blocks.
|
||||
- [x] Existing generated boards with the prior three-sign layout are detected from their exact registered oak structure and upgraded with the two centered readable signs.
|
||||
- [x] Existing custom single-block boards and unrelated structures are not modified.
|
||||
- [x] Existing-board upgrades never overwrite occupied sign locations and persist new interaction locations failure-safely.
|
||||
- [x] Automated tests verify sign placement, readable text, decorative text, interaction registration, obstruction handling, and prior-layout migration.
|
||||
- [x] The title and instruction signs use glowing front-side text for readability while decorative signs remain non-glowing.
|
||||
- [x] New boards receive glowing readable signs, and exact existing generated five-sign boards are refreshed on startup without modifying custom signs.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-010: Generate a physical quest-board structure](us-010-generate-a-physical-quest-board.md)
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-012: Create quests by command near a board"
|
||||
description: Allow command-based quest creation and material autocomplete near a physical board even when global player commands are disabled.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-012: Create quests by command near a board
|
||||
|
||||
As a **player**, I want to use the quest-creation command near a quest board so that I can use material autocomplete while still interacting at the physical board.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] When global player quest commands are disabled, `/quests create <item> <quantity>` remains available to a player within five blocks of a registered board interaction location.
|
||||
- [x] Material and quantity autocomplete remain available for nearby quest creation.
|
||||
- [x] A player farther than five blocks from every registered board is directed to move closer and no quest or escrow change occurs.
|
||||
- [x] Board proximity requires the player and registered location to be in the same world.
|
||||
- [x] A distance of exactly five blocks is accepted and a greater distance is rejected.
|
||||
- [x] Root listing, `list`, `complete`, `cancel`, and `claim` remain disabled while global player commands are disabled.
|
||||
- [x] When global player quest commands are enabled, all command behavior, including creation, remains available regardless of board proximity.
|
||||
- [x] Custom single-block boards and every registered interaction location on generated boards satisfy the proximity requirement.
|
||||
- [x] Board-dialog creation remains available regardless of command settings or command proximity rules.
|
||||
- [x] Automated tests verify boundaries, cross-world behavior, autocomplete, command settings, disabled subcommands, and generated-board proximity.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
|
||||
- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-008: Control player quest commands](us-008-control-player-quest-commands.md)
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-013: Show custom reward item names"
|
||||
description: Display a reward item's custom name together with its material type when browsing quests.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-013: Show custom reward item names
|
||||
|
||||
As a **player**, I want named reward items identified by both custom name and material so that I understand exactly what a quest will award.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] A reward with a custom display name is shown as amount, readable custom name, and material type, such as `1 × Shopping List (PAPER)`.
|
||||
- [x] An unnamed reward continues to show its amount and material type, such as `3 × DIAMOND`.
|
||||
- [x] Styled custom names are converted to safe readable plain text without changing the escrowed item's exact metadata.
|
||||
- [x] Quest-board detail dialogs and `/quests` listings use the same reward representation.
|
||||
- [x] Newly escrowed rewards persist the readable custom name alongside their exact serialized item data.
|
||||
- [x] Existing persisted named rewards derive their custom name from valid stored item metadata when possible.
|
||||
- [x] Missing, malformed, or unreadable item metadata safely falls back to the material type without preventing quest browsing.
|
||||
- [x] Automated tests verify named, unnamed, styled, persisted, historical, and malformed reward metadata.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md)
|
||||
- [US-004: Browse available quests](us-004-browse-available-quests.md)
|
||||
Reference in New Issue
Block a user