4 Commits
Author SHA1 Message Date
dmg de8ff83c3c feat(notifications): add login quest counts and claim reminders
Release / release (push) Successful in 2m40s
CI / build (push) Successful in 1m17s
2026-09-06 21:34:24 -04:00
dmg 02f74d1822 feat(quests): show custom reward item names
Release / release (push) Successful in 2m37s
CI / build (push) Successful in 1m11s
2026-09-05 11:39:01 -04:00
dmg e12e31c0ad feat(quests): allow nearby command creation
Release / release (push) Successful in 2m50s
CI / build (push) Successful in 1m8s
2026-09-05 10:03:30 -04:00
dmg 07061a3622 fix(board): make readable signs glow
Release / release (push) Successful in 2m26s
CI / build (push) Successful in 1m4s
2026-09-05 09:36:21 -04:00
31 changed files with 993 additions and 36 deletions
+2 -2
View File
@@ -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 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 <quest>` 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 <quest>`. 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 <quest>` 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 <quest>`. 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
@@ -23,7 +23,7 @@ The plugin JAR is written to `build/libs/`.
## Player commands
Player commands are disabled by default and can be enabled persistently by an administrator. When disabled, players are directed to use a physical quest board.
Player commands are disabled by default and can be enabled persistently by an administrator. When disabled, players within five blocks of a registered board can still use `/quests create <block> <quantity>` with material and quantity autocomplete; other player command forms remain disabled.
```text
/quests
+2
View File
@@ -9,6 +9,8 @@ okf_version: "0.1"
This bundle specifies shared physical quest boards, reward escrow, block 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)
+28
View File
@@ -98,3 +98,31 @@ description: Chronological record of material decisions affecting Spigot Quest B
- 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`.
+4 -2
View File
@@ -9,11 +9,13 @@ description: Catalog of user stories for the Spigot Quest Board plugin.
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 a block-delivery quest](us-003-create-a-block-delivery-quest.md)
4. [US-004: Browse available quests](us-004-browse-available-quests.md)
4. [US-004: Browse available quests](us-004-browse-available-quests.md) — includes login quest counts and board guidance.
5. [US-005: Deliver blocks 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)
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)
@@ -19,7 +19,11 @@ As a **player**, I want to browse current quests so that I can decide which bloc
- [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 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)
@@ -24,6 +24,10 @@ As a **quest issuer**, I want delivered blocks and returned rewards held at the
- [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 blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
@@ -14,7 +14,7 @@ As an **administrator**, I want to enable or disable player quest commands so th
- [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`, `create`, `complete`, `cancel`, and `claim` reject execution with a clear message directing the player to a quest board.
- [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.
@@ -25,3 +25,4 @@ As an **administrator**, I want to enable or disable player quest commands so th
- [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-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)
@@ -20,6 +20,8 @@ As a **player**, I want readable signs on a generated quest board so that I know
- [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
@@ -0,0 +1,29 @@
---
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 <block> <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)
@@ -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)
@@ -0,0 +1,8 @@
package games.dmg.spigotquestboard;
import java.util.UUID;
@FunctionalInterface
interface BoardProximity {
boolean isWithin(UUID worldId, double x, double y, double z, double maximumDistance);
}
@@ -7,7 +7,7 @@ import java.util.Map;
import java.util.Objects;
import java.util.Set;
final class BoardRegistry {
final class BoardRegistry implements BoardProximity {
private final BoardRepository repository;
private Map<BoardId, RegisteredBoard> boards;
@@ -46,6 +46,30 @@ final class BoardRegistry {
return boards.size();
}
@Override
public synchronized boolean isWithin(
java.util.UUID worldId,
double x,
double y,
double z,
double maximumDistance
) {
Objects.requireNonNull(worldId, "worldId");
if (maximumDistance < 0.0) {
return false;
}
double maximumDistanceSquared = maximumDistance * maximumDistance;
return boards.keySet().stream()
.filter(id -> id.worldId().equals(worldId))
.anyMatch(id -> {
double deltaX = x - id.x();
double deltaY = y - id.y();
double deltaZ = z - id.z();
return deltaX * deltaX + deltaY * deltaY + deltaZ * deltaZ
<= maximumDistanceSquared;
});
}
synchronized Map<BoardId, RegisteredBoard> registeredBoards() {
return Map.copyOf(boards);
}
@@ -1,6 +1,7 @@
package games.dmg.spigotquestboard;
import java.io.IOException;
import java.time.Clock;
import java.util.Objects;
import java.util.UUID;
import java.util.logging.Level;
@@ -15,11 +16,17 @@ final class BukkitIssuerNotifier implements IssuerNotifier, Listener {
private final QuestService quests;
private final Server server;
private final Logger logger;
private final Clock clock;
BukkitIssuerNotifier(QuestService quests, Server server, Logger logger) {
this(quests, server, logger, Clock.systemUTC());
}
BukkitIssuerNotifier(QuestService quests, Server server, Logger logger, Clock clock) {
this.quests = Objects.requireNonNull(quests, "quests");
this.server = Objects.requireNonNull(server, "server");
this.logger = Objects.requireNonNull(logger, "logger");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
@@ -32,7 +39,20 @@ final class BukkitIssuerNotifier implements IssuerNotifier, Listener {
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
deliver(event.getPlayer());
Player player = event.getPlayer();
int count = quests.activeQuests(clock.instant()).size();
String summary = switch (count) {
case 0 -> "No quests are currently available.";
case 1 -> "1 quest is currently available.";
default -> count + " quests are currently available.";
};
player.sendMessage(summary + " Visit the quest board to accept or create a quest.");
if (!quests.claimsFor(player.getUniqueId()).isEmpty()) {
player.sendMessage(
"You have items waiting to be claimed. Visit the quest board to collect them."
);
}
deliver(player);
}
void deliver(Player player) {
@@ -13,6 +13,7 @@ import org.bukkit.block.Sign;
import org.bukkit.block.data.BlockData;
import org.bukkit.block.data.type.WallSign;
import org.bukkit.block.sign.Side;
import org.bukkit.block.sign.SignSide;
final class BukkitPhysicalBoardWorld implements PhysicalBoardWorld {
private static final Component DECORATIVE_TEXT = Component.text("xxxxxxxx")
@@ -64,9 +65,11 @@ final class BukkitPhysicalBoardWorld implements PhysicalBoardWorld {
throw new IllegalStateException("Oak wall sign did not create sign state");
}
List<Component> lines = signLines(placement.signKind());
SignSide front = sign.getSide(Side.FRONT);
for (int line = 0; line < lines.size(); line++) {
sign.getSide(Side.FRONT).line(line, lines.get(line));
front.line(line, lines.get(line));
}
front.setGlowingText(placement.signKind() != PhysicalBoardSignKind.DECORATIVE);
if (!sign.update(true, false)) {
throw new IllegalStateException("Could not configure physical quest-board sign");
}
@@ -74,6 +77,14 @@ final class BukkitPhysicalBoardWorld implements PhysicalBoardWorld {
@Override
public boolean matches(PhysicalBoardPlan.Placement placement, BoardFacing facing) {
return matches(placement, facing,
placement.signKind() != PhysicalBoardSignKind.DECORATIVE);
}
@Override
public boolean matches(
PhysicalBoardPlan.Placement placement, BoardFacing facing, boolean glowingText
) {
Block block = block(placement.location());
Material material = Material.matchMaterial(placement.material());
if (material == null || block.getType() != material) {
@@ -87,9 +98,13 @@ final class BukkitPhysicalBoardWorld implements PhysicalBoardWorld {
|| !(block.getState() instanceof Sign sign)) {
return false;
}
SignSide front = sign.getSide(Side.FRONT);
if (front.isGlowingText() != glowingText) {
return false;
}
List<Component> expected = signLines(placement.signKind());
for (int line = 0; line < expected.size(); line++) {
if (!expected.get(line).equals(sign.getSide(Side.FRONT).line(line))) {
if (!expected.get(line).equals(front.line(line))) {
return false;
}
}
@@ -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;
}
}
@@ -32,14 +32,21 @@ final class PhysicalBoardUpgrader {
int upgraded = 0;
Map<BoardId, RegisteredBoard> registered = registry.registeredBoards();
for (Candidate candidate : candidates(registered)) {
if (!hasLegacyRegistrations(candidate, registered)) {
boolean legacy = hasLegacyRegistrations(candidate, registered);
boolean full = hasFullRegistrations(candidate, registered);
if (!legacy && !full) {
continue;
}
PhysicalBoardWorld world = worlds.open(candidate.anchor().worldId());
if (world != null && isLegacyBoard(candidate, world)
&& upgrade(candidate, world)) {
if (world == null) {
continue;
}
if (legacy && isLegacyBoard(candidate, world) && upgradeLegacy(candidate, world)) {
upgraded++;
registered = registry.registeredBoards();
} else if (full && isNonGlowingFullBoard(candidate, world)) {
refreshReadableSigns(candidate, world);
upgraded++;
}
}
return upgraded;
@@ -60,6 +67,19 @@ final class PhysicalBoardUpgrader {
);
}
private static boolean hasFullRegistrations(
Candidate candidate, Map<BoardId, RegisteredBoard> registered
) {
PhysicalBoardPlan plan = PhysicalBoardPlan.create(candidate.anchor(), candidate.facing());
for (BoardId location : plan.interactionLocations()) {
RegisteredBoard board = registered.get(location);
if (board == null || !candidate.worldName().equals(board.worldName())) {
return false;
}
}
return true;
}
private boolean isLegacyBoard(Candidate candidate, PhysicalBoardWorld world) {
PhysicalBoardPlan plan = PhysicalBoardPlan.create(candidate.anchor(), candidate.facing());
for (PhysicalBoardPlan.Placement placement : legacyPlacements(plan)) {
@@ -75,8 +95,21 @@ final class PhysicalBoardUpgrader {
return true;
}
private boolean upgrade(Candidate candidate, PhysicalBoardWorld world) throws IOException {
List<PhysicalBoardPlan.Placement> signs = newSigns(
private boolean isNonGlowingFullBoard(Candidate candidate, PhysicalBoardWorld world) {
PhysicalBoardPlan plan = PhysicalBoardPlan.create(candidate.anchor(), candidate.facing());
for (PhysicalBoardPlan.Placement placement : plan.placements()) {
boolean matches = placement.sign()
? world.matches(placement, candidate.facing(), false)
: world.matches(placement, candidate.facing());
if (!matches) {
return false;
}
}
return true;
}
private boolean upgradeLegacy(Candidate candidate, PhysicalBoardWorld world) throws IOException {
List<PhysicalBoardPlan.Placement> signs = readableSigns(
PhysicalBoardPlan.create(candidate.anchor(), candidate.facing())
);
Map<BoardId, Object> snapshots = new LinkedHashMap<>();
@@ -153,7 +186,30 @@ final class PhysicalBoardUpgrader {
return Set.copyOf(locations);
}
private void refreshReadableSigns(Candidate candidate, PhysicalBoardWorld world)
throws IOException {
List<PhysicalBoardPlan.Placement> signs = readableSigns(
PhysicalBoardPlan.create(candidate.anchor(), candidate.facing())
);
Map<BoardId, Object> snapshots = new LinkedHashMap<>();
try {
for (PhysicalBoardPlan.Placement sign : signs) {
snapshots.put(sign.location(), world.snapshot(sign.location()));
}
for (PhysicalBoardPlan.Placement sign : signs) {
world.place(sign, candidate.facing());
}
} catch (RuntimeException exception) {
rollback(world, snapshots, exception);
throw new IOException("Could not refresh physical quest-board signs", exception);
}
}
private static List<PhysicalBoardPlan.Placement> newSigns(PhysicalBoardPlan plan) {
return readableSigns(plan);
}
private static List<PhysicalBoardPlan.Placement> readableSigns(PhysicalBoardPlan plan) {
return plan.placements().stream().filter(placement ->
placement.signKind() == PhysicalBoardSignKind.TITLE
|| placement.signKind() == PhysicalBoardSignKind.INSTRUCTION
@@ -11,5 +11,11 @@ interface PhysicalBoardWorld {
return false;
}
default boolean matches(
PhysicalBoardPlan.Placement placement, BoardFacing facing, boolean glowingText
) {
return false;
}
void restore(BoardId location, Object snapshot);
}
@@ -14,6 +14,7 @@ import org.bukkit.entity.Player;
final class QuestCommand implements CommandExecutor, TabCompleter {
private static final List<String> QUANTITIES = List.of("1", "16", "32", "64");
private static final double COMMAND_CREATION_DISTANCE = 5.0;
private final QuestCreationGateway creator;
private final QuestBrowser browser;
private final QuestCompletionGateway completer;
@@ -21,6 +22,7 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
private final QuestClaimGateway claimant;
private final Clock clock;
private final PlayerCommandSettings playerCommands;
private final BoardProximity boardProximity;
QuestCommand(QuestCreationGateway creator, QuestBrowser browser, Clock clock) {
this(creator, browser, null, null, null, clock);
@@ -53,7 +55,7 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
QuestClaimGateway claimant,
Clock clock
) {
this(creator, browser, completer, canceller, claimant, clock, null);
this(creator, browser, completer, canceller, claimant, clock, null, null);
}
QuestCommand(
@@ -64,6 +66,19 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
QuestClaimGateway claimant,
Clock clock,
PlayerCommandSettings playerCommands
) {
this(creator, browser, completer, canceller, claimant, clock, playerCommands, null);
}
QuestCommand(
QuestCreationGateway creator,
QuestBrowser browser,
QuestCompletionGateway completer,
QuestCancellationGateway canceller,
QuestClaimGateway claimant,
Clock clock,
PlayerCommandSettings playerCommands,
BoardProximity boardProximity
) {
this.creator = Objects.requireNonNull(creator, "creator");
this.browser = Objects.requireNonNull(browser, "browser");
@@ -72,6 +87,7 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
this.claimant = claimant;
this.clock = Objects.requireNonNull(clock, "clock");
this.playerCommands = playerCommands;
this.boardProximity = boardProximity;
}
@Override
@@ -79,10 +95,19 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
CommandSender sender, Command command, String label, String[] arguments
) {
if (!playerCommandsEnabled()) {
sender.sendMessage(
"Player quest commands are disabled. Use a physical quest board instead."
);
return true;
if (isCreate(arguments) && sender instanceof Player player) {
if (!isNearBoard(player)) {
sender.sendMessage(
"Move closer to a quest board to create a quest by command."
);
return true;
}
} else {
sender.sendMessage(
"Player quest commands are disabled. Use a physical quest board instead."
);
return true;
}
}
if (arguments.length == 0
|| (arguments.length == 1 && "list".equalsIgnoreCase(arguments[0]))) {
@@ -178,9 +203,20 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
public List<String> onTabComplete(
CommandSender sender, Command command, String alias, String[] arguments
) {
if (!playerCommandsEnabled() || !(sender instanceof Player)) {
if (!(sender instanceof Player player)) {
return List.of();
}
if (!playerCommandsEnabled()) {
if (!isNearBoard(player)) {
return List.of();
}
if (arguments.length == 1) {
return startsWith(List.of("create"), arguments[0]);
}
if (!isCreate(arguments)) {
return List.of();
}
}
if (arguments.length == 1) {
return startsWith(
List.of("create", "list", "complete", "cancel", "claim"), arguments[0]
@@ -196,7 +232,6 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
return startsWith(browser.completableQuestIds(clock.instant()), arguments[1]);
}
if (arguments.length == 2 && "cancel".equalsIgnoreCase(arguments[0])) {
Player player = (Player) sender;
return startsWith(
browser.cancellableQuestIds(player.getUniqueId(), clock.instant()), arguments[1]
);
@@ -208,6 +243,21 @@ final class QuestCommand implements CommandExecutor, TabCompleter {
return playerCommands == null || playerCommands.enabled();
}
private boolean isNearBoard(Player player) {
if (boardProximity == null) {
return false;
}
org.bukkit.Location location = player.getLocation();
return boardProximity.isWithin(
player.getWorld().getUID(), location.getX(), location.getY(), location.getZ(),
COMMAND_CREATION_DISTANCE
);
}
private static boolean isCreate(String[] arguments) {
return arguments.length > 0 && "create".equalsIgnoreCase(arguments[0]);
}
private static List<String> startsWith(List<String> candidates, String prefix) {
String normalized = prefix.toLowerCase(Locale.ROOT);
return candidates.stream()
@@ -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)");
}
@@ -41,7 +41,7 @@ public final class SpigotQuestBoardPlugin extends JavaPlugin {
);
Clock clock = Clock.systemUTC();
BukkitIssuerNotifier notifier = new BukkitIssuerNotifier(
quests, getServer(), getLogger()
quests, getServer(), getLogger(), clock
);
QuestCompletionGateway completer = new QuestCompletionController(
quests, new BukkitQuestCompletionInventory(), notifier
@@ -98,7 +98,8 @@ public final class SpigotQuestBoardPlugin extends JavaPlugin {
return new CommandHandlers(
new QuestAdminCommand(boards, playerCommands),
new QuestCommand(
creator, browser, completer, canceller, claimant, clock, playerCommands
creator, browser, completer, canceller, claimant, clock, playerCommands,
boards
)
);
}
@@ -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;
@@ -69,6 +69,24 @@ final class BoardRegistryTest {
assertEquals(0, repository.saveCount);
}
@Test
void proximityUsesSameWorldAndAcceptsExactFiveBlockBoundary() throws Exception {
RecordingRepository repository = new RecordingRepository(new BoardState(Set.of(BOARD)));
BoardRegistry registry = new BoardRegistry(repository);
assertTrue(registry.isWithin(
BOARD.id().worldId(), BOARD.id().x() + 3.0, BOARD.id().y() + 4.0,
BOARD.id().z(), 5.0
));
assertFalse(registry.isWithin(
BOARD.id().worldId(), BOARD.id().x() + 3.01, BOARD.id().y() + 4.0,
BOARD.id().z(), 5.0
));
assertFalse(registry.isWithin(
UUID.randomUUID(), BOARD.id().x(), BOARD.id().y(), BOARD.id().z(), 5.0
));
}
@Test
void failedPersistenceDoesNotPublishBoard() throws Exception {
BoardRepository repository = new BoardRepository() {
@@ -4,15 +4,21 @@ import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.contains;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.clearInvocations;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import java.util.UUID;
import java.util.logging.Logger;
import org.bukkit.Server;
import org.bukkit.entity.Player;
import org.bukkit.event.player.PlayerJoinEvent;
import org.junit.jupiter.api.Test;
final class BukkitIssuerNotifierTest {
@@ -82,6 +88,90 @@ final class BukkitIssuerNotifierTest {
assertTrue(service.state().notifications().isEmpty());
}
@Test
void everyLoginReportsAvailableQuestsWithNaturalWordingAndBoardHint() throws Exception {
QuestService service = new QuestService(new Repository());
Instant now = Instant.EPOCH.plusSeconds(604800);
BukkitIssuerNotifier notifier = new BukkitIssuerNotifier(
service, mock(Server.class), Logger.getAnonymousLogger(),
Clock.fixed(now, ZoneOffset.UTC)
);
Player player = mock(Player.class);
when(player.getUniqueId()).thenReturn(UUID.randomUUID());
PlayerJoinEvent event = mock(PlayerJoinEvent.class);
when(event.getPlayer()).thenReturn(player);
String hint = " Visit the quest board to accept or create a quest.";
// Expired at exactly login time, even before the expiry task runs.
createQuest(service, Instant.EPOCH);
Quest completed = createQuest(service, now);
service.complete(completed.id(), new EscrowItem("STONE", 1, null), now);
Quest cancelled = createQuest(service, now);
service.cancel(cancelled.id(), cancelled.issuerId(), now);
notifier.onPlayerJoin(event);
verify(player).sendMessage("No quests are currently available." + hint);
createQuest(service, now);
notifier.onPlayerJoin(event);
verify(player).sendMessage("1 quest is currently available." + hint);
createQuest(service, now);
notifier.onPlayerJoin(event);
notifier.onPlayerJoin(event);
verify(player, times(2)).sendMessage("2 quests are currently available." + hint);
verify(player, never()).sendMessage(contains("items waiting"));
}
@Test
void claimsAreRemindedOnEveryLoginAcrossReloadsUntilAllCollected() throws Exception {
Repository repository = new Repository();
QuestService service = completedService(repository);
UUID issuer = service.state().notifications().values().iterator().next().recipientId();
Quest cancelled = service.create(
issuer, "Issuer", "STONE", 1,
List.of(new EscrowItem("DIAMOND", 1, null)), Instant.EPOCH
);
service.cancel(cancelled.id(), issuer, Instant.EPOCH.plusSeconds(1));
Player player = mock(Player.class);
when(player.getUniqueId()).thenReturn(issuer);
PlayerJoinEvent event = mock(PlayerJoinEvent.class);
when(event.getPlayer()).thenReturn(player);
String reminder = "You have items waiting to be claimed. "
+ "Visit the quest board to collect them.";
BukkitIssuerNotifier notifier = new BukkitIssuerNotifier(
service, mock(Server.class), Logger.getAnonymousLogger()
);
notifier.onPlayerJoin(event);
notifier.onPlayerJoin(event);
verify(player, times(2)).sendMessage(reminder);
assertTrue(service.pendingNotifications(issuer).isEmpty());
assertEquals(2, service.claimsFor(issuer).size());
service = new QuestService(repository);
notifier = new BukkitIssuerNotifier(service, mock(Server.class), Logger.getAnonymousLogger());
notifier.onPlayerJoin(event);
verify(player, times(3)).sendMessage(reminder);
service.acknowledgeClaim(issuer, service.claimsFor(issuer).getFirst().id());
notifier.onPlayerJoin(event);
verify(player, times(4)).sendMessage(reminder);
clearInvocations(player);
when(player.getUniqueId()).thenReturn(UUID.randomUUID());
notifier.onPlayerJoin(event);
verify(player, never()).sendMessage(reminder);
when(player.getUniqueId()).thenReturn(issuer);
service.acknowledgeClaim(issuer, service.claimsFor(issuer).getFirst().id());
notifier.onPlayerJoin(event);
verify(player, never()).sendMessage(reminder);
}
private static Quest createQuest(QuestService service, Instant now) throws Exception {
return service.create(
UUID.randomUUID(), "Issuer", "STONE", 1,
List.of(new EscrowItem("DIAMOND", 1, null)), now
);
}
private static QuestService completedService(Repository repository) throws Exception {
QuestService service = new QuestService(repository);
Quest quest = service.create(
@@ -89,6 +89,34 @@ final class BukkitPhysicalBoardWorldTest {
assertFalse(adapter.matches(placement, BoardFacing.SOUTH));
}
@Test
void readableSignsGlowWhileDecorativeSignsDoNot() {
UUID worldId = UUID.randomUUID();
BoardId location = new BoardId(worldId, 1, 65, 2);
World world = mock(World.class);
Block block = mock(Block.class);
WallSign wallSign = mock(WallSign.class);
Sign sign = mock(Sign.class);
SignSide signSide = mock(SignSide.class);
when(world.getUID()).thenReturn(worldId);
when(world.getBlockAt(1, 65, 2)).thenReturn(block);
when(block.getBlockData()).thenReturn(wallSign);
when(block.getState()).thenReturn(sign);
when(sign.getSide(Side.FRONT)).thenReturn(signSide);
when(sign.update(true, false)).thenReturn(true);
BukkitPhysicalBoardWorld adapter = new BukkitPhysicalBoardWorld(world);
adapter.place(new PhysicalBoardPlan.Placement(
location, "OAK_WALL_SIGN", PhysicalBoardSignKind.TITLE
), BoardFacing.NORTH);
verify(signSide).setGlowingText(true);
adapter.place(new PhysicalBoardPlan.Placement(
location, "OAK_WALL_SIGN", PhysicalBoardSignKind.DECORATIVE
), BoardFacing.NORTH);
verify(signSide).setGlowingText(false);
}
@Test
void rendersReadableTitleAndInstructionText() {
assertEquals(
@@ -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<ItemStack> itemStacks = Mockito.mockStatic(ItemStack.class)) {
itemStacks.when(() -> ItemStack.deserializeBytes(Mockito.any(byte[].class)))
.thenReturn(mismatched);
assertEquals(escrow, escrow.inferCustomName());
assertThrows(IllegalStateException.class, escrow::toItemStack);
}
}
}
@@ -41,6 +41,10 @@ final class PhysicalBoardCreatorTest {
assertTrue(repository.state.boards().stream().allMatch(
board -> board.worldName().equals("survival")
));
assertTrue(PhysicalBoardPlan.create(ANCHOR, BoardFacing.NORTH)
.interactionLocations().stream().allMatch(location -> registry.isWithin(
location.worldId(), location.x(), location.y(), location.z(), 5.0
)));
}
@Test
@@ -35,6 +35,33 @@ final class PhysicalBoardUpgraderTest {
assertEquals(2, world.placed.size());
}
@Test
void refreshesBothReadableSignsOnAnExactRegisteredFullBoard() throws Exception {
RecordingRepository repository = new RecordingRepository(fullRegistrations(), false);
BoardRegistry registry = new BoardRegistry(repository);
FakeWorld world = fullWorld(false);
assertEquals(1, upgrader(registry, world).upgrade());
assertEquals(17, registry.size());
assertEquals(0, repository.saves);
assertEquals(Set.of(PhysicalBoardSignKind.TITLE, PhysicalBoardSignKind.INSTRUCTION),
world.placed.values().stream().map(PhysicalBoardPlan.Placement::signKind)
.collect(Collectors.toSet()));
assertTrue(newSigns().stream().allMatch(sign -> world.glowing.get(sign.location())));
}
@Test
void doesNotReportOrRefreshAnAlreadyGlowingFullBoard() throws Exception {
RecordingRepository repository = new RecordingRepository(fullRegistrations(), false);
FakeWorld world = fullWorld(true);
assertEquals(0, upgrader(new BoardRegistry(repository), world).upgrade());
assertTrue(world.placed.isEmpty());
assertEquals(0, repository.saves);
}
@Test
void doesNotAlterCustomBoardsOrStructuresThatDoNotExactlyMatch() throws Exception {
RegisteredBoard custom = new RegisteredBoard(
@@ -58,6 +85,23 @@ final class PhysicalBoardUpgraderTest {
assertTrue(changedWorld.placed.isEmpty());
}
@Test
void doesNotRefreshAFullBoardWithCustomSignText() throws Exception {
RecordingRepository repository = new RecordingRepository(fullRegistrations(), false);
FakeWorld world = fullWorld(false);
PhysicalBoardPlan.Placement title = newSigns().stream()
.filter(sign -> sign.signKind() == PhysicalBoardSignKind.TITLE)
.findFirst().orElseThrow();
world.existing.put(title.location(), new PhysicalBoardPlan.Placement(
title.location(), title.material(), PhysicalBoardSignKind.INSTRUCTION
));
assertEquals(0, upgrader(new BoardRegistry(repository), world).upgrade());
assertTrue(world.placed.isEmpty());
assertTrue(newSigns().stream().noneMatch(sign -> world.glowing.get(sign.location())));
}
@Test
void doesNotOverwriteAnOccupiedNewSignCell() throws Exception {
RecordingRepository repository = new RecordingRepository(legacyRegistrations(), false);
@@ -89,6 +133,19 @@ final class PhysicalBoardUpgraderTest {
assertEquals(0, repository.saves);
}
@Test
void rollsBackBothReadableSignsWhenFullBoardRefreshFails() throws Exception {
RecordingRepository repository = new RecordingRepository(fullRegistrations(), false);
FakeWorld world = fullWorld(false);
world.failPlacement = 1;
assertThrows(IOException.class,
() -> upgrader(new BoardRegistry(repository), world).upgrade());
assertTrue(newSigns().stream().noneMatch(sign -> world.glowing.get(sign.location())));
assertEquals(0, repository.saves);
}
@Test
void rollsBackBothCellsWhenAtomicPersistenceFails() throws Exception {
RecordingRepository repository = new RecordingRepository(legacyRegistrations(), true);
@@ -120,6 +177,12 @@ final class PhysicalBoardUpgraderTest {
.collect(Collectors.toSet());
}
private static Set<RegisteredBoard> fullRegistrations() {
return plan().interactionLocations().stream()
.map(location -> new RegisteredBoard(location, "survival"))
.collect(Collectors.toSet());
}
private static FakeWorld legacyWorld() {
FakeWorld world = new FakeWorld();
plan().placements().stream().filter(placement ->
@@ -132,6 +195,19 @@ final class PhysicalBoardUpgraderTest {
return world;
}
private static FakeWorld fullWorld(boolean readableGlowing) {
FakeWorld world = new FakeWorld();
plan().placements().forEach(placement -> {
world.existing.put(placement.location(), placement);
if (placement.sign()) {
world.facings.put(placement.location(), FACING);
world.glowing.put(placement.location(),
placement.signKind() != PhysicalBoardSignKind.DECORATIVE && readableGlowing);
}
});
return world;
}
private static java.util.List<PhysicalBoardPlan.Placement> newSigns() {
return plan().placements().stream().filter(placement ->
placement.signKind() == PhysicalBoardSignKind.TITLE
@@ -140,8 +216,13 @@ final class PhysicalBoardUpgraderTest {
}
private static final class FakeWorld implements PhysicalBoardWorld {
private record Snapshot(
PhysicalBoardPlan.Placement placement, BoardFacing facing, Boolean glowing
) { }
private final Map<BoardId, PhysicalBoardPlan.Placement> existing = new HashMap<>();
private final Map<BoardId, BoardFacing> facings = new HashMap<>();
private final Map<BoardId, Boolean> glowing = new HashMap<>();
private final Map<BoardId, PhysicalBoardPlan.Placement> placed = new HashMap<>();
private int placements;
private int failPlacement = -1;
@@ -151,7 +232,9 @@ final class PhysicalBoardUpgraderTest {
}
@Override public Object snapshot(BoardId location) {
return existing.get(location);
return new Snapshot(
existing.get(location), facings.get(location), glowing.get(location)
);
}
@Override public void place(PhysicalBoardPlan.Placement placement, BoardFacing facing) {
@@ -160,6 +243,8 @@ final class PhysicalBoardUpgraderTest {
}
existing.put(placement.location(), placement);
facings.put(placement.location(), facing);
glowing.put(placement.location(),
placement.signKind() != PhysicalBoardSignKind.DECORATIVE);
placed.put(placement.location(), placement);
}
@@ -170,13 +255,25 @@ final class PhysicalBoardUpgraderTest {
&& (!placement.sign() || facing == facings.get(placement.location()));
}
@Override public boolean matches(
PhysicalBoardPlan.Placement placement, BoardFacing facing, boolean glowingText
) {
return matches(placement, facing)
&& glowingText == glowing.getOrDefault(placement.location(), false);
}
@Override public void restore(BoardId location, Object snapshot) {
if (snapshot == null) {
existing.remove(location);
facings.remove(location);
Snapshot captured = (Snapshot) snapshot;
restore(existing, location, captured.placement());
restore(facings, location, captured.facing());
restore(glowing, location, captured.glowing());
}
private static <T> void restore(Map<BoardId, T> values, BoardId location, T value) {
if (value == null) {
values.remove(location);
} else {
PhysicalBoardPlan.Placement placement = (PhysicalBoardPlan.Placement) snapshot;
existing.put(location, placement);
values.put(location, value);
}
}
}
@@ -11,6 +11,8 @@ import java.util.List;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.atomic.AtomicInteger;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
@@ -44,6 +46,54 @@ final class PluginCommandWiringTest {
assertTrue(worldLookups.get() > 0);
}
@Test
void playerCommandUsesBoardRegistryForNearbyCreation() throws Exception {
UUID worldId = UUID.randomUUID();
BoardId boardId = new BoardId(worldId, 10, 64, 20);
BoardRegistry boards = new BoardRegistry(new BoardRepository() {
@Override public BoardState load() {
return new BoardState(Set.of(new RegisteredBoard(boardId, "survival")));
}
@Override public void save(BoardState state) { }
});
PlayerCommandSettings settings = new PlayerCommandSettings(
new PlayerCommandSettingsRepository() {
@Override public boolean loadEnabled() { return false; }
@Override public void saveEnabled(boolean enabled) { }
}
);
QuestCreationGateway creator = mock(QuestCreationGateway.class);
Quest created = mock(Quest.class);
when(created.id()).thenReturn(UUID.randomUUID());
when(creator.create(
org.mockito.ArgumentMatchers.any(),
org.mockito.ArgumentMatchers.anyString(),
org.mockito.ArgumentMatchers.anyInt(),
org.mockito.ArgumentMatchers.any()
)).thenReturn(created);
SpigotQuestBoardPlugin.CommandHandlers handlers =
SpigotQuestBoardPlugin.commandHandlers(
boards, settings, creator, mock(QuestBrowser.class), null, null, null,
Clock.systemUTC()
);
World world = mock(World.class);
when(world.getUID()).thenReturn(worldId);
Player player = mock(Player.class);
when(player.getWorld()).thenReturn(world);
when(player.getLocation()).thenReturn(new Location(world, 13, 68, 20));
assertTrue(handlers.quests().onCommand(
player, mock(Command.class), "quests", new String[] {"create", "stone", "1"}
));
verify(creator).create(
org.mockito.ArgumentMatchers.eq(player),
org.mockito.ArgumentMatchers.eq("stone"),
org.mockito.ArgumentMatchers.eq(1),
org.mockito.ArgumentMatchers.any()
);
}
@Test
void adminAndPlayerCommandsShareThePersistedSetting() throws Exception {
PlayerCommandSettings settings = new PlayerCommandSettings(
@@ -14,15 +14,19 @@ import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import java.util.UUID;
import org.bukkit.Location;
import org.bukkit.World;
import org.bukkit.command.Command;
import org.bukkit.entity.Player;
import org.junit.jupiter.api.Test;
final class QuestCommandTest {
private static final Instant NOW = Instant.parse("2026-09-05T03:00:00Z");
private static final UUID WORLD_ID =
UUID.fromString("00000000-0000-0000-0000-000000000099");
@Test
void disabledSettingGatesEveryPlayerCommandFormAndAutocomplete() throws Exception {
void disabledSettingGatesNonCreationCommandForms() throws Exception {
QuestCreationGateway creator = mock(QuestCreationGateway.class);
QuestBrowser browser = mock(QuestBrowser.class);
QuestCompletionGateway completer = mock(QuestCompletionGateway.class);
@@ -43,7 +47,6 @@ final class QuestCommandTest {
List<String[]> forms = List.of(
new String[] {},
new String[] {"list"},
new String[] {"create", "stone", "1"},
new String[] {"complete", "quest-id"},
new String[] {"cancel", "quest-id"},
new String[] {"claim"}
@@ -62,6 +65,97 @@ final class QuestCommandTest {
verifyNoInteractions(creator, browser, completer, canceller, claimant);
}
@Test
void disabledSettingAllowsNearbyCreationAndOnlyCreationAutocomplete() throws Exception {
RecordingCreator creator = new RecordingCreator();
PlayerCommandSettings settings = settings(false);
BoardProximity proximity = (worldId, x, y, z, maximumDistance) -> {
assertEquals(WORLD_ID, worldId);
assertEquals(4.0, x);
assertEquals(3.0, y);
assertEquals(0.0, z);
assertEquals(5.0, maximumDistance);
return true;
};
QuestCommand executor = new QuestCommand(
creator, now -> List.of(), null, null, null,
Clock.fixed(NOW, ZoneOffset.UTC), settings, proximity
);
Player player = playerAt(4.0, 3.0, 0.0);
Command command = mock(Command.class);
assertTrue(executor.onCommand(
player, command, "quests", new String[] {"create", "stone", "1"}
));
assertEquals(1, creator.calls);
assertEquals(List.of("create"), executor.onTabComplete(
player, command, "quests", new String[] {""}
));
assertTrue(executor.onTabComplete(
player, command, "quests", new String[] {"li"}
).isEmpty());
assertEquals(List.of("STONE", "STONE_BRICKS"), executor.onTabComplete(
player, command, "quests", new String[] {"create", "sto"}
));
assertEquals(List.of("1", "16", "32", "64"), executor.onTabComplete(
player, command, "quests", new String[] {"create", "stone", ""}
));
assertTrue(executor.onTabComplete(
player, command, "quests", new String[] {"complete", ""}
).isEmpty());
}
@Test
void disabledSettingRejectsAwayCreationBeforeCreatorOrEscrowGateway() throws Exception {
QuestCreationGateway creator = mock(QuestCreationGateway.class);
QuestCommand executor = new QuestCommand(
creator, mock(QuestBrowser.class), null, null, null,
Clock.fixed(NOW, ZoneOffset.UTC), settings(false),
(worldId, x, y, z, maximumDistance) -> false
);
Player player = playerAt(5.01, 0.0, 0.0);
Command command = mock(Command.class);
assertTrue(executor.onCommand(
player, command, "quests", new String[] {"create", "stone", "1"}
));
verify(player).sendMessage("Move closer to a quest board to create a quest by command.");
verifyNoInteractions(creator);
assertTrue(executor.onTabComplete(
player, command, "quests", new String[] {""}
).isEmpty());
assertTrue(executor.onTabComplete(
player, command, "quests", new String[] {"create", "sto"}
).isEmpty());
}
@Test
void enabledSettingPreservesAllCommandsWithoutConsultingProximity() throws Exception {
RecordingCreator creator = new RecordingCreator();
QuestBrowser browser = now -> List.of(creator.quest(1));
QuestCommand executor = new QuestCommand(
creator, browser, null, null, null, Clock.fixed(NOW, ZoneOffset.UTC),
settings(true),
(worldId, x, y, z, maximumDistance) -> {
throw new AssertionError("Enabled commands must bypass board proximity");
}
);
Player player = mock(Player.class);
Command command = mock(Command.class);
assertTrue(executor.onCommand(
player, command, "quests", new String[] {"create", "stone", "1"}
));
assertTrue(executor.onCommand(player, command, "quests", new String[] {"list"}));
assertEquals(List.of("create"), executor.onTabComplete(
player, command, "quests", new String[] {"cr"}
));
assertEquals(1, creator.calls);
}
@Test
void routesValidatedCreateArgumentsWithCurrentUtcTime() {
RecordingCreator creator = new RecordingCreator();
@@ -238,6 +332,23 @@ final class QuestCommandTest {
).isEmpty());
}
private static PlayerCommandSettings settings(boolean enabled) throws Exception {
return new PlayerCommandSettings(new PlayerCommandSettingsRepository() {
@Override public boolean loadEnabled() { return enabled; }
@Override public void saveEnabled(boolean newValue) { }
});
}
private static Player playerAt(double x, double y, double z) {
World world = mock(World.class);
when(world.getUID()).thenReturn(WORLD_ID);
Location location = new Location(world, x, y, z);
Player player = mock(Player.class);
when(player.getWorld()).thenReturn(world);
when(player.getLocation()).thenReturn(location);
return player;
}
private static QuestCommand command(RecordingCreator creator) {
return command(creator, now -> List.of());
}
@@ -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)));
@@ -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<ItemStack> 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<ItemStack> 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");