From 02f74d182266db2ebf54c4392ec0fdd4a512abb4 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Sat, 5 Sep 2026 11:39:01 -0400 Subject: [PATCH] feat(quests): show custom reward item names --- README.md | 2 +- knowledge/log.md | 7 ++ knowledge/user-stories/index.md | 1 + .../us-004-browse-available-quests.md | 1 + .../us-013-show-custom-reward-item-names.md | 26 ++++ .../dmg/spigotquestboard/EscrowItem.java | 62 ++++++++- .../QuestListingFormatter.java | 3 + .../spigotquestboard/YamlQuestRepository.java | 12 +- .../dmg/spigotquestboard/EscrowItemTest.java | 82 ++++++++++++ .../QuestListingFormatterTest.java | 13 ++ .../YamlQuestRepositoryTest.java | 119 ++++++++++++++++++ 11 files changed, 322 insertions(+), 6 deletions(-) create mode 100644 knowledge/user-stories/us-013-show-custom-reward-item-names.md create mode 100644 src/test/java/games/dmg/spigotquestboard/EscrowItemTest.java diff --git a/README.md b/README.md index 08c5d8e..10b425c 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The approved behavior is specified in the [OKF knowledge bundle](knowledge/index ## Status -Administrators can register persistent shared quest boards by targeting a block within five blocks and running `/questadmin createboard`. They can instead run `/questadmin createboard physical` to generate a five-wide oak board above the targeted ground anchor, with glowing centered title and browsing-instruction signs above three decorative signs; its visible panel blocks and all five signs are registered. Right-clicking any registered board opens a compact native dashboard with dedicated browsing, creation, and claim screens. A player can request a block and quantity while escrowing the exact reward stack held in their main hand. Every board and `/quests list` show the same active quests with requested blocks, rewards, issuers, and time remaining. Players can complete quests at any board or with `/quests complete ` by delivering the required blocks. Exact escrowed rewards are granted immediately, and delivered blocks are held for the issuer. Issuers can cancel their own active quests at any board or with `/quests cancel `. Completed deliveries and rewards from cancelled or seven-day-expired quests are held durably and can be collected at any board or with `/quests claim`; inventory overflow drops at the claimant's feet. +Administrators can register persistent shared quest boards by targeting a block within five blocks and running `/questadmin createboard`. They can instead run `/questadmin createboard physical` to generate a five-wide oak board above the targeted ground anchor, with glowing centered title and browsing-instruction signs above three decorative signs; its visible panel blocks and all five signs are registered. Right-clicking any registered board opens a compact native dashboard with dedicated browsing, creation, and claim screens. A player can request a block and quantity while escrowing the exact reward stack held in their main hand. Every board and `/quests list` show the same active quests with requested blocks, rewards, issuers, and time remaining; custom reward names are shown together with their material type. Players can complete quests at any board or with `/quests complete ` by delivering the required blocks. Exact escrowed rewards are granted immediately, and delivered blocks are held for the issuer. Issuers can cancel their own active quests at any board or with `/quests cancel `. Completed deliveries and rewards from cancelled or seven-day-expired quests are held durably and can be collected at any board or with `/quests claim`; inventory overflow drops at the claimant's feet. ## Requirements diff --git a/knowledge/log.md b/knowledge/log.md index 6d7fc32..ef5210d 100644 --- a/knowledge/log.md +++ b/knowledge/log.md @@ -112,3 +112,10 @@ description: Chronological record of material decisions affecting Spigot Quest B - 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`. diff --git a/knowledge/user-stories/index.md b/knowledge/user-stories/index.md index f769bf8..6ce3a04 100644 --- a/knowledge/user-stories/index.md +++ b/knowledge/user-stories/index.md @@ -18,3 +18,4 @@ description: Catalog of user stories for the Spigot Quest Board plugin. 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) diff --git a/knowledge/user-stories/us-004-browse-available-quests.md b/knowledge/user-stories/us-004-browse-available-quests.md index 37a6881..bbd3d45 100644 --- a/knowledge/user-stories/us-004-browse-available-quests.md +++ b/knowledge/user-stories/us-004-browse-available-quests.md @@ -23,3 +23,4 @@ As a **player**, I want to browse current quests so that I can decide which bloc - [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) - [US-005: Deliver blocks 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) diff --git a/knowledge/user-stories/us-013-show-custom-reward-item-names.md b/knowledge/user-stories/us-013-show-custom-reward-item-names.md new file mode 100644 index 0000000..44b6fe1 --- /dev/null +++ b/knowledge/user-stories/us-013-show-custom-reward-item-names.md @@ -0,0 +1,26 @@ +--- +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 a block-delivery quest](us-003-create-a-block-delivery-quest.md) +- [US-004: Browse available quests](us-004-browse-available-quests.md) diff --git a/src/main/java/games/dmg/spigotquestboard/EscrowItem.java b/src/main/java/games/dmg/spigotquestboard/EscrowItem.java index dbd487b..34a29e6 100644 --- a/src/main/java/games/dmg/spigotquestboard/EscrowItem.java +++ b/src/main/java/games/dmg/spigotquestboard/EscrowItem.java @@ -2,10 +2,17 @@ package games.dmg.spigotquestboard; import java.util.Base64; import java.util.Objects; +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer; import org.bukkit.Material; import org.bukkit.inventory.ItemStack; +import org.bukkit.inventory.meta.ItemMeta; + +record EscrowItem(String material, int amount, String serializedItem, String customName) { + EscrowItem(String material, int amount, String serializedItem) { + this(material, amount, serializedItem, null); + } -record EscrowItem(String material, int amount, String serializedItem) { EscrowItem { Objects.requireNonNull(material, "material"); material = material.trim().toUpperCase(java.util.Locale.ROOT); @@ -18,24 +25,43 @@ record EscrowItem(String material, int amount, String serializedItem) { if (serializedItem != null && serializedItem.isBlank()) { throw new IllegalArgumentException("Serialized item must not be blank"); } + customName = normalizeReadableName(customName); } static EscrowItem fromItemStack(ItemStack stack) { Objects.requireNonNull(stack, "stack"); - if (stack.getType().isAir() || stack.getAmount() <= 0) { + if (isAir(stack.getType()) || stack.getAmount() <= 0) { throw new IllegalArgumentException("Reward stack must not be empty"); } ItemStack snapshot = stack.clone(); return new EscrowItem( snapshot.getType().name(), snapshot.getAmount(), - Base64.getEncoder().encodeToString(snapshot.serializeAsBytes()) + Base64.getEncoder().encodeToString(snapshot.serializeAsBytes()), + readableCustomName(snapshot) ); } + EscrowItem inferCustomName() { + if (customName != null || serializedItem == null) { + return this; + } + try { + String inferredName = readableCustomName(deserializeExactItem()); + return inferredName == null + ? this : new EscrowItem(material, amount, serializedItem, inferredName); + } catch (RuntimeException | LinkageError exception) { + return this; + } + } + ItemStack toItemStack() { if (serializedItem == null) { return new ItemStack(Objects.requireNonNull(Material.matchMaterial(material)), amount); } + return deserializeExactItem(); + } + + private ItemStack deserializeExactItem() { final ItemStack stack; try { stack = ItemStack.deserializeBytes(Base64.getDecoder().decode(serializedItem)); @@ -47,4 +73,34 @@ record EscrowItem(String material, int amount, String serializedItem) { } return stack; } + + private static boolean isAir(Material material) { + return material == Material.AIR || material == Material.CAVE_AIR + || material == Material.VOID_AIR; + } + + private static String readableCustomName(ItemStack stack) { + if (!stack.hasItemMeta()) { + return null; + } + ItemMeta metadata = stack.getItemMeta(); + if (!metadata.hasCustomName()) { + return null; + } + Component name = metadata.customName(); + if (name == null) { + return null; + } + return normalizeReadableName( + PlainTextComponentSerializer.plainText().serialize(name) + ); + } + + private static String normalizeReadableName(String name) { + if (name == null) { + return null; + } + String normalized = name.replaceAll("[\\p{Cntrl}\\s]+", " ").trim(); + return normalized.isEmpty() ? null : normalized; + } } diff --git a/src/main/java/games/dmg/spigotquestboard/QuestListingFormatter.java b/src/main/java/games/dmg/spigotquestboard/QuestListingFormatter.java index b57cc49..7d899d3 100644 --- a/src/main/java/games/dmg/spigotquestboard/QuestListingFormatter.java +++ b/src/main/java/games/dmg/spigotquestboard/QuestListingFormatter.java @@ -37,6 +37,9 @@ final class QuestListingFormatter { } private static String formatReward(EscrowItem item) { + if (item.customName() != null) { + return item.amount() + " × " + item.customName() + " (" + item.material() + ")"; + } return item.amount() + " × " + item.material() + (item.serializedItem() == null ? "" : " (with exact item data)"); } diff --git a/src/main/java/games/dmg/spigotquestboard/YamlQuestRepository.java b/src/main/java/games/dmg/spigotquestboard/YamlQuestRepository.java index c4a0363..cbce62f 100644 --- a/src/main/java/games/dmg/spigotquestboard/YamlQuestRepository.java +++ b/src/main/java/games/dmg/spigotquestboard/YamlQuestRepository.java @@ -165,9 +165,14 @@ final class YamlQuestRepository implements QuestRepository { if (data != null && !(data instanceof String)) { throw new IllegalArgumentException("Invalid item-data"); } + Object customName = entry.get("custom-name"); + if (customName != null && !(customName instanceof String)) { + throw new IllegalArgumentException("Invalid custom-name"); + } items.add(new EscrowItem( - requiredString(entry, "material"), requiredInteger(entry, "amount"), (String) data - )); + requiredString(entry, "material"), requiredInteger(entry, "amount"), + (String) data, (String) customName + ).inferCustomName()); } return items; } @@ -181,6 +186,9 @@ final class YamlQuestRepository implements QuestRepository { if (item.serializedItem() != null) { serialized.put("item-data", item.serializedItem()); } + if (item.customName() != null) { + serialized.put("custom-name", item.customName()); + } serializedItems.add(serialized); } return serializedItems; diff --git a/src/test/java/games/dmg/spigotquestboard/EscrowItemTest.java b/src/test/java/games/dmg/spigotquestboard/EscrowItemTest.java new file mode 100644 index 0000000..fecbf9c --- /dev/null +++ b/src/test/java/games/dmg/spigotquestboard/EscrowItemTest.java @@ -0,0 +1,82 @@ +package games.dmg.spigotquestboard; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +import java.util.Base64; +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.format.NamedTextColor; +import net.kyori.adventure.text.format.TextDecoration; +import org.bukkit.Material; +import org.bukkit.inventory.ItemStack; +import org.bukkit.inventory.meta.ItemMeta; +import org.junit.jupiter.api.Test; +import org.mockito.MockedStatic; +import org.mockito.Mockito; + +final class EscrowItemTest { + @Test + void capturesStyledCustomNameAsSafePlainTextWithoutChangingSerializedBytes() { + byte[] exactBytes = new byte[] {1, 2, 3, 4}; + ItemStack original = mock(ItemStack.class); + ItemStack snapshot = mock(ItemStack.class); + ItemMeta metadata = mock(ItemMeta.class); + when(original.getType()).thenReturn(Material.PAPER); + when(original.getAmount()).thenReturn(2); + when(original.clone()).thenReturn(snapshot); + when(snapshot.getType()).thenReturn(Material.PAPER); + when(snapshot.getAmount()).thenReturn(2); + when(snapshot.serializeAsBytes()).thenReturn(exactBytes); + when(snapshot.hasItemMeta()).thenReturn(true); + when(snapshot.getItemMeta()).thenReturn(metadata); + when(metadata.hasCustomName()).thenReturn(true); + when(metadata.customName()).thenReturn( + Component.text(" Shopping", NamedTextColor.GOLD, TextDecoration.BOLD) + .append(Component.text("\nList ", NamedTextColor.BLUE)) + ); + + EscrowItem escrow = EscrowItem.fromItemStack(original); + + assertEquals("Shopping List", escrow.customName()); + assertArrayEquals(exactBytes, Base64.getDecoder().decode(escrow.serializedItem())); + } + + @Test + void ignoresVanillaDisplayNameWhenNoTrueCustomNameExists() { + ItemStack original = mock(ItemStack.class); + ItemStack snapshot = mock(ItemStack.class); + ItemMeta metadata = mock(ItemMeta.class); + when(original.getType()).thenReturn(Material.DIAMOND); + when(original.getAmount()).thenReturn(3); + when(original.clone()).thenReturn(snapshot); + when(snapshot.getType()).thenReturn(Material.DIAMOND); + when(snapshot.getAmount()).thenReturn(3); + when(snapshot.serializeAsBytes()).thenReturn(new byte[] {9}); + when(snapshot.hasItemMeta()).thenReturn(true); + when(snapshot.getItemMeta()).thenReturn(metadata); + when(metadata.hasCustomName()).thenReturn(false); + + assertNull(EscrowItem.fromItemStack(original).customName()); + } + + @Test + void historicalInferenceDoesNotWeakenExactEnvelopeValidation() { + String data = Base64.getEncoder().encodeToString(new byte[] {7}); + EscrowItem escrow = new EscrowItem("PAPER", 1, data); + ItemStack mismatched = mock(ItemStack.class); + when(mismatched.getType()).thenReturn(Material.BOOK); + when(mismatched.getAmount()).thenReturn(1); + + try (MockedStatic itemStacks = Mockito.mockStatic(ItemStack.class)) { + itemStacks.when(() -> ItemStack.deserializeBytes(Mockito.any(byte[].class))) + .thenReturn(mismatched); + + assertEquals(escrow, escrow.inferCustomName()); + assertThrows(IllegalStateException.class, escrow::toItemStack); + } + } +} diff --git a/src/test/java/games/dmg/spigotquestboard/QuestListingFormatterTest.java b/src/test/java/games/dmg/spigotquestboard/QuestListingFormatterTest.java index d61d468..f37b9b8 100644 --- a/src/test/java/games/dmg/spigotquestboard/QuestListingFormatterTest.java +++ b/src/test/java/games/dmg/spigotquestboard/QuestListingFormatterTest.java @@ -32,6 +32,19 @@ final class QuestListingFormatterTest { assertTrue(listing.contains("Time remaining: 1d 1h 1m 1s")); } + @Test + void showsCustomRewardNameTogetherWithMaterialType() { + Quest quest = quest( + NOW.plusSeconds(60), + List.of(new EscrowItem("PAPER", 1, "opaque-exact-data", "Shopping List")) + ); + + String listing = QuestListingFormatter.format(quest, NOW); + + assertTrue(listing.contains("1 × Shopping List (PAPER)")); + assertFalse(listing.contains("PAPER (with exact item data)")); + } + @Test void roundsAnActiveSubsecondBoundaryUpToOneSecond() { Quest quest = quest(NOW.plusNanos(1), List.of(new EscrowItem("DIAMOND", 1, null))); diff --git a/src/test/java/games/dmg/spigotquestboard/YamlQuestRepositoryTest.java b/src/test/java/games/dmg/spigotquestboard/YamlQuestRepositoryTest.java index a8b91f1..e5ee90e 100644 --- a/src/test/java/games/dmg/spigotquestboard/YamlQuestRepositoryTest.java +++ b/src/test/java/games/dmg/spigotquestboard/YamlQuestRepositoryTest.java @@ -1,8 +1,11 @@ package games.dmg.spigotquestboard; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; import java.io.IOException; import java.nio.file.Files; @@ -12,8 +15,14 @@ import java.util.Base64; import java.util.List; import java.util.Map; import java.util.UUID; +import net.kyori.adventure.text.Component; +import org.bukkit.Material; +import org.bukkit.inventory.ItemStack; +import org.bukkit.inventory.meta.ItemMeta; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.io.TempDir; +import org.mockito.MockedStatic; +import org.mockito.Mockito; final class YamlQuestRepositoryTest { @TempDir Path temporaryDirectory; @@ -53,6 +62,90 @@ final class YamlQuestRepositoryTest { assertTrue(yaml.contains(itemData)); } + @Test + void persistsCustomNamesForRewardAndClaimItems() throws Exception { + Path path = temporaryDirectory.resolve("quests.yml"); + YamlQuestRepository repository = new YamlQuestRepository(path); + UUID ownerId = UUID.randomUUID(); + UUID questId = UUID.randomUUID(); + Quest quest = new Quest( + questId, ownerId, "Issuer", "STONE", 1, + List.of(new EscrowItem("PAPER", 1, "reward-data", "Shopping List")), + Instant.parse("2026-09-05T03:00:00Z"), + Instant.parse("2026-09-12T03:00:00Z"), QuestStatus.COMPLETED + ); + QuestClaim claim = new QuestClaim( + UUID.randomUUID(), questId, ownerId, + List.of(new EscrowItem("BOOK", 1, "claim-data", "Field Notes")), + Instant.parse("2026-09-05T03:01:00Z") + ); + QuestState state = new QuestState( + Map.of(questId, quest), Map.of(ownerId, List.of(claim)), Map.of() + ); + + repository.save(state); + + assertEquals(state, repository.load()); + String yaml = Files.readString(path); + assertTrue(yaml.contains("custom-name: Shopping List")); + assertTrue(yaml.contains("custom-name: Field Notes")); + } + + @Test + void infersHistoricalCustomNameFromExactDataAndPersistsItOnNextSave() throws Exception { + Path path = temporaryDirectory.resolve("quests.yml"); + String itemData = Base64.getEncoder().encodeToString(new byte[] {7}); + writeHistoricalQuest(path, itemData); + ItemStack stack = mock(ItemStack.class); + ItemMeta metadata = mock(ItemMeta.class); + when(stack.getType()).thenReturn(Material.PAPER); + when(stack.getAmount()).thenReturn(1); + when(stack.hasItemMeta()).thenReturn(true); + when(stack.getItemMeta()).thenReturn(metadata); + when(metadata.hasCustomName()).thenReturn(true); + when(metadata.customName()).thenReturn(Component.text("Archived List")); + YamlQuestRepository repository = new YamlQuestRepository(path); + + QuestState loaded; + try (MockedStatic itemStacks = Mockito.mockStatic(ItemStack.class)) { + itemStacks.when(() -> ItemStack.deserializeBytes(Mockito.any(byte[].class))) + .thenReturn(stack); + loaded = repository.load(); + } + + assertEquals("Archived List", loaded.quests().values().iterator().next() + .reward().getFirst().customName()); + assertEquals("Archived List", loaded.claims().values().iterator().next() + .getFirst().items().getFirst().customName()); + repository.save(loaded); + assertTrue(Files.readString(path).contains("custom-name: Archived List")); + } + + @Test + void malformedOrUnavailableHistoricalItemDataFallsBackWithoutFailingLoad() throws Exception { + Path malformedPath = temporaryDirectory.resolve("malformed.yml"); + writeHistoricalQuest(malformedPath, "not-base64%%% "); + + Quest malformedQuest = new YamlQuestRepository(malformedPath).load() + .quests().values().iterator().next(); + + assertNull(malformedQuest.reward().getFirst().customName()); + assertTrue(QuestListingFormatter.format( + malformedQuest, Instant.parse("2026-09-06T03:00:00Z") + ).contains("1 × PAPER (with exact item data)")); + + Path unavailablePath = temporaryDirectory.resolve("unavailable.yml"); + writeHistoricalQuest(unavailablePath, Base64.getEncoder().encodeToString(new byte[] {8})); + Quest unavailableQuest; + try (MockedStatic itemStacks = Mockito.mockStatic(ItemStack.class)) { + itemStacks.when(() -> ItemStack.deserializeBytes(Mockito.any(byte[].class))) + .thenThrow(new IllegalStateException("server item codec unavailable")); + unavailableQuest = new YamlQuestRepository(unavailablePath).load() + .quests().values().iterator().next(); + } + assertNull(unavailableQuest.reward().getFirst().customName()); + } + @Test void missingLifecycleStatusDefaultsToActiveForExistingYaml() throws Exception { Path path = temporaryDirectory.resolve("quests.yml"); @@ -161,6 +254,32 @@ final class YamlQuestRepositoryTest { assertEquals(QuestClaimType.RETURNED_REWARD, claim.type()); } + private static void writeHistoricalQuest(Path path, String itemData) throws IOException { + Files.writeString(path, """ + quests: + - id: 00000000-0000-0000-0000-000000000010 + issuer-id: 00000000-0000-0000-0000-000000000001 + issuer-name: Issuer + requested-material: STONE + requested-amount: 1 + created-at: '2026-09-05T03:00:00Z' + expires-at: '2026-09-12T03:00:00Z' + reward: + - material: PAPER + amount: 1 + item-data: '%s' + claims: + - id: 00000000-0000-0000-0000-000000000020 + quest-id: 00000000-0000-0000-0000-000000000010 + owner-id: 00000000-0000-0000-0000-000000000001 + created-at: '2026-09-05T04:00:00Z' + items: + - material: PAPER + amount: 1 + item-data: '%s' + """.formatted(itemData, itemData)); + } + @Test void malformedStateIsRejectedRatherThanPartiallyLoaded() throws Exception { Path path = temporaryDirectory.resolve("quests.yml");