feat(gear): add Tyrant legacy tools and weapons

2026-09-09 22:02:59 -04:00
parent 553db666e1
commit 0c4a95801a
27 changed files with 411 additions and 44 deletions
@@ -0,0 +1,46 @@
+---
+type: User Story
+title: "US-022: Purchase legacy tools and weapons"
+description: Let a fully unlocked Tyrant spend choices on lasting Netherite tools and weapons alongside legacy armor.
+status: done
+---
+
+# US-022: Purchase legacy tools and weapons
+
+As the **fully unlocked Tyrant**, I want to purchase named tools and weapons so that continued victories create useful, transferable reign trophies.
+
+## Acceptance criteria
+
+- [x] After all six standard unlocks, the active Tyrant may spend one choice each on Axe, Pickaxe, Sword, Hoe, and Shovel in any order alongside armor, with no armor prerequisites.
+- [x] All five items are Netherite: Axe has Sharpness VI, Efficiency VI, Mending I; Pickaxe, Hoe, and Shovel have Efficiency VI, Mending I; Sword has Sharpness VI, Mending I.
+- [x] Each item uses the armor naming/lore convention and remains ordinary transferable, persistent, repairable equipment without role binding or recovery.
+- [x] Each of nine distinct legacy rewards can be purchased once per reign; losing or transferring an item does not restore eligibility.
+- [x] Claims survive restart, preserve existing saved armor claims, and reset with the reign while delivered items remain untouched.
+- [x] Full inventory, paused games, unauthorized players, incomplete unlocks, no choices, malformed requests, and repeated interactions cannot consume choices or issue rewards.
+- [x] The control panel lists all nine rewards and confirms the selected item, enchantments, and one-choice cost before executing the authoritative claim path and refreshing.
+- [x] `/tyrant gear <axe|pickaxe|sword|hoe|shovel>` offers contextual, case-insensitive completion with no extra arguments; `/tyrant armor` remains unchanged.
+
+## Implementation
+
+Extend the existing legacy reward service and historical armor-named state types to share one durable claim set. Preserve the `game.claimed-armor` storage key and original enum values for compatibility; new tool values are additional claims, not armor prerequisites.
+
+- [Reward types and command parsing](../../src/main/java/games/dmg/spigottyrant/TyrantArmorPiece.java)
+- [Item specification](../../src/main/java/games/dmg/spigottyrant/TyrantArmorSpec.java) and [Bukkit item creation](../../src/main/java/games/dmg/spigottyrant/BukkitTyrantArmorItemFactory.java)
+- [Shared claim rules](../../src/main/java/games/dmg/spigottyrant/TyrantArmorService.java), [command delivery](../../src/main/java/games/dmg/spigottyrant/TyrantCommand.java), and [panel confirmation](../../src/main/java/games/dmg/spigottyrant/BukkitTyrantControlPanelRenderer.java)
+- [State persistence](../../src/main/java/games/dmg/spigottyrant/YamlTyrantStateRepository.java)
+
+## Validation scope
+
+Verified `./gradlew clean check jar`: 177 tests passed, zero failures/errors/skips, Java compilation with `-Xlint:all -Werror`, and JAR packaging. OKF v0.1 validation checks all 29 Markdown documents for YAML frontmatter, story statuses and acceptance criteria, reserved index/log structure, and repository-local links. Initial red tests failed on missing tool rewards and gear completion before implementation.
+
+Automated coverage includes all nine inventory deliveries and full-inventory rejections, tool-first claims and duplicate prevention, lifecycle/authorization/progression guards, repeated gear command execution against updated state, malformed and cross-category requests, sorted case-insensitive completion, exact item specifications and confirmation lore, unique panel slots, backward-compatible YAML loading and mixed-claim restart round trips, and succession reset.
+
+No live-server smoke test has been performed. Persistence uses the existing state manager: saving YAML and saving Minecraft inventory are not a cross-store atomic transaction, so abrupt crashes or disk failures during delivery retain the preexisting armor-path risk. Older plugin binaries do not understand new tool enum values; backward compatibility means loading older armor saves in this version, not safe downgrade after new claims.
+
+## Related
+
+- [Progress and purchase unlocks](us-003-progress-and-purchase-unlocks.md)
+- [Configure and persist state](us-012-configure-and-persist-state.md)
+- [Tyrant control panel](us-015-manage-tyrant-control-panel.md)
+- [Contextual completion](us-018-complete-commands-contextually.md)
+- [Legacy armor](us-021-claim-tyrant-legacy-armor.md)