CrateKeys: animated reward crates for Paper 1.21+.

Author: Standardan

.gitignore

@@ -0,0 +1,5 @@
+target/
+.idea/
+*.iml
+.vscode/
+.DS_Store

README.md

@@ -0,0 +1,58 @@
+# CrateKeys
+
+Reward **crates** with collectible keys and an **animated roulette** opening, for Paper 1.21+.
+Bind any block as a crate, hand out keys, and let players right-click to spin for weighted rewards.
+
+## Download
+
+**[Download the latest release »](https://github.com/Standardan/cratekeys/releases/latest)**
+
+Drop the `.jar` into your server's `plugins/` folder and restart. Requires Paper 1.21+ (Java 21).
+
+## Features
+
+- **Config-driven crates** — define crates, key items, and weighted reward tables in `config.yml`
+- **Animated spin GUI** — icons scroll across a roulette and land on the winning reward, with sound
+- **Tagged key items** — keys are identified by a PersistentDataContainer tag, not their name
+- **Block-bound crates** — `/crate setblock <crate>` turns any block into a crate; right-click with a key opens it
+- **Weighted rewards** run as console commands (`give`, `eco`, anything), so rewards are unlimited
+- The spin GUI is **click-locked** so players can't pull items out mid-animation
+
+## Commands (`cratekeys.admin`, default op)
+
+| Command | Description |
+|---|---|
+| `/crate givekey <player> <crate> [amount]` | Give crate keys |
+| `/crate setblock <crate>` | Bind the block you're looking at as a crate |
+| `/crate removeblock` | Unbind a crate block |
+| `/crate reload` | Reload config |
+| `/crate list` | List defined crates |
+
+## Configuration
+
+```yaml
+crates:
+  vote:
+    display-name: "<aqua><bold>Vote Crate</bold>"
+    key-name: "<aqua>Vote Key"
+    key-material: TRIPWIRE_HOOK
+    rewards:
+      - name: "<white>16 Diamonds"
+        weight: 50        # relative odds
+        icon: DIAMOND
+        commands:
+          - "give %player% diamond 16"
+```
+
+## Design notes
+
+- **The winner is decided before the animation starts** (`Crate#roll()` does a single weighted draw).
+  The roulette is pure presentation — it can't change the outcome, which keeps rewards honest and
+  the code simple.
+- **The GUI is identified by a custom `InventoryHolder`** (`SpinGui`), so the click listener cancels
+  interaction by *type*, never by fragile title-string matching.
+- **Animation runs on a repeating scheduler task** at a fixed tick interval and cancels itself when done.
+
+## Building
+
+JDK 21 + Maven. `mvn clean package` → `target/cratekeys-1.0.0.jar`.

pom.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>io.github.standardan</groupId>
+    <artifactId>cratekeys</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <maven.compiler.release>21</maven.compiler.release>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <repositories>
+        <repository>
+            <id>papermc</id>
+            <url>https://repo.papermc.io/repository/maven-public/</url>
+        </repository>
+    </repositories>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.papermc.paper</groupId>
+            <artifactId>paper-api</artifactId>
+            <version>1.21.4-R0.1-SNAPSHOT</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <finalName>${project.artifactId}-${project.version}</finalName>
+        <resources>
+            <resource>
+                <directory>src/main/resources</directory>
+                <filtering>true</filtering>
+            </resource>
+        </resources>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.13.0</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>

src/main/java/io/github/standardan/cratekeys/CrateKeysPlugin.java

@@ -0,0 +1,28 @@
+package io.github.standardan.cratekeys;
+
+import io.github.standardan.cratekeys.command.CrateCommand;
+import io.github.standardan.cratekeys.crate.CrateManager;
+import org.bukkit.command.PluginCommand;
+import org.bukkit.plugin.java.JavaPlugin;
+
+import java.util.Objects;
+
+public final class CrateKeysPlugin extends JavaPlugin {
+
+    @Override
+    public void onEnable() {
+        saveDefaultConfig();
+
+        CrateManager manager = new CrateManager(this);
+        manager.load();
+
+        getServer().getPluginManager().registerEvents(new CrateListener(this, manager), this);
+
+        PluginCommand command = Objects.requireNonNull(getCommand("crate"), "crate missing from plugin.yml");
+        CrateCommand handler = new CrateCommand(this, manager);
+        command.setExecutor(handler);
+        command.setTabCompleter(handler);
+
+        getLogger().info("CrateKeys enabled with " + manager.crates().size() + " crate(s).");
+    }
+}

src/main/java/io/github/standardan/cratekeys/CrateListener.java

@@ -0,0 +1,79 @@
+package io.github.standardan.cratekeys;
+
+import io.github.standardan.cratekeys.crate.Crate;
+import io.github.standardan.cratekeys.crate.CrateManager;
+import io.github.standardan.cratekeys.gui.SpinGui;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.block.Block;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.block.Action;
+import org.bukkit.event.inventory.InventoryClickEvent;
+import org.bukkit.event.inventory.InventoryDragEvent;
+import org.bukkit.event.player.PlayerInteractEvent;
+import org.bukkit.inventory.EquipmentSlot;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.plugin.Plugin;
+
+/**
+ * Opens crates when a player right-clicks a bound crate block with the right
+ * key, and locks the spin GUI so nothing can be clicked out of it.
+ */
+public final class CrateListener implements Listener {
+
+    private final Plugin plugin;
+    private final CrateManager manager;
+
+    public CrateListener(Plugin plugin, CrateManager manager) {
+        this.plugin = plugin;
+        this.manager = manager;
+    }
+
+    @EventHandler
+    public void onInteract(PlayerInteractEvent event) {
+        if (event.getHand() != EquipmentSlot.HAND || event.getAction() != Action.RIGHT_CLICK_BLOCK) {
+            return;
+        }
+        Block block = event.getClickedBlock();
+        if (block == null) {
+            return;
+        }
+        Crate crate = manager.getCrateAtBlock(block.getLocation());
+        if (crate == null) {
+            return; // not a crate block - ignore
+        }
+        event.setCancelled(true); // don't open the underlying chest, etc.
+
+        Player player = event.getPlayer();
+        if (manager.isSpinning(player.getUniqueId())) {
+            return;
+        }
+        ItemStack hand = player.getInventory().getItemInMainHand();
+        Crate keyCrate = manager.getCrateFromKey(hand);
+        if (keyCrate == null || !keyCrate.id().equals(crate.id())) {
+            player.sendMessage(Component.text("You need a ", NamedTextColor.RED)
+                    .append(crate.keyName())
+                    .append(Component.text(" to open this.", NamedTextColor.RED)));
+            return;
+        }
+
+        hand.setAmount(hand.getAmount() - 1); // consume one key
+        new SpinGui(plugin, manager, player, crate).open();
+    }
+
+    @EventHandler
+    public void onClick(InventoryClickEvent event) {
+        if (event.getInventory().getHolder() instanceof SpinGui) {
+            event.setCancelled(true); // can't take items mid-spin
+        }
+    }
+
+    @EventHandler
+    public void onDrag(InventoryDragEvent event) {
+        if (event.getInventory().getHolder() instanceof SpinGui) {
+            event.setCancelled(true);
+        }
+    }
+}

src/main/java/io/github/standardan/cratekeys/command/CrateCommand.java

@@ -0,0 +1,149 @@
+package io.github.standardan.cratekeys.command;
+
+import io.github.standardan.cratekeys.CrateKeysPlugin;
+import io.github.standardan.cratekeys.crate.Crate;
+import io.github.standardan.cratekeys.crate.CrateManager;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.Bukkit;
+import org.bukkit.block.Block;
+import org.bukkit.command.Command;
+import org.bukkit.command.CommandExecutor;
+import org.bukkit.command.CommandSender;
+import org.bukkit.command.TabCompleter;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+
+/**
+ * Admin command: give keys, bind/unbind crate blocks, reload, list.
+ */
+public final class CrateCommand implements CommandExecutor, TabCompleter {
+
+    private final CrateKeysPlugin plugin;
+    private final CrateManager manager;
+
+    public CrateCommand(CrateKeysPlugin plugin, CrateManager manager) {
+        this.plugin = plugin;
+        this.manager = manager;
+    }
+
+    @Override
+    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command,
+                             @NotNull String label, @NotNull String[] args) {
+        if (args.length == 0) {
+            sender.sendMessage(Component.text("/crate <givekey|setblock|removeblock|reload|list>",
+                    NamedTextColor.GRAY));
+            return true;
+        }
+        switch (args[0].toLowerCase(Locale.ROOT)) {
+            case "givekey" -> giveKey(sender, args);
+            case "setblock" -> setBlock(sender, args);
+            case "removeblock" -> removeBlock(sender);
+            case "reload" -> {
+                plugin.reloadConfig();
+                manager.load();
+                sender.sendMessage(Component.text("CrateKeys reloaded.", NamedTextColor.GREEN));
+            }
+            case "list" -> {
+                String ids = manager.crates().stream().map(Crate::id).reduce((a, b) -> a + ", " + b).orElse("(none)");
+                sender.sendMessage(Component.text("Crates: " + ids, NamedTextColor.AQUA));
+            }
+            default -> sender.sendMessage(Component.text("Unknown subcommand.", NamedTextColor.RED));
+        }
+        return true;
+    }
+
+    private void giveKey(CommandSender sender, String[] args) {
+        if (args.length < 3) {
+            sender.sendMessage(Component.text("Usage: /crate givekey <player> <crate> [amount]", NamedTextColor.RED));
+            return;
+        }
+        Player target = Bukkit.getPlayerExact(args[1]);
+        if (target == null) {
+            sender.sendMessage(Component.text("Player not online.", NamedTextColor.RED));
+            return;
+        }
+        Crate crate = manager.getCrate(args[2]);
+        if (crate == null) {
+            sender.sendMessage(Component.text("No crate named '" + args[2] + "'.", NamedTextColor.RED));
+            return;
+        }
+        int amount = 1;
+        if (args.length >= 4) {
+            try {
+                amount = Math.max(1, Integer.parseInt(args[3]));
+            } catch (NumberFormatException ignored) {
+                sender.sendMessage(Component.text("Amount must be a number.", NamedTextColor.RED));
+                return;
+            }
+        }
+        target.getInventory().addItem(manager.createKey(crate, amount));
+        sender.sendMessage(Component.text("Gave " + amount + " " + crate.id() + " key(s) to "
+                + target.getName() + ".", NamedTextColor.GREEN));
+    }
+
+    private void setBlock(CommandSender sender, String[] args) {
+        if (!(sender instanceof Player player)) {
+            sender.sendMessage("Run this in-game, looking at a block.");
+            return;
+        }
+        if (args.length < 2) {
+            player.sendMessage(Component.text("Usage: /crate setblock <crate>", NamedTextColor.RED));
+            return;
+        }
+        Crate crate = manager.getCrate(args[1]);
+        if (crate == null) {
+            player.sendMessage(Component.text("No crate named '" + args[1] + "'.", NamedTextColor.RED));
+            return;
+        }
+        Block block = player.getTargetBlockExact(5);
+        if (block == null) {
+            player.sendMessage(Component.text("Look at a block within 5 blocks.", NamedTextColor.RED));
+            return;
+        }
+        manager.bindBlock(block.getLocation(), crate.id());
+        player.sendMessage(Component.text("Bound that block as a " + crate.id() + " crate.", NamedTextColor.GREEN));
+    }
+
+    private void removeBlock(CommandSender sender) {
+        if (!(sender instanceof Player player)) {
+            sender.sendMessage("Run this in-game, looking at a crate block.");
+            return;
+        }
+        Block block = player.getTargetBlockExact(5);
+        if (block == null || !manager.unbindBlock(block.getLocation())) {
+            player.sendMessage(Component.text("That block isn't a crate.", NamedTextColor.RED));
+            return;
+        }
+        player.sendMessage(Component.text("Removed that crate block.", NamedTextColor.GREEN));
+    }
+
+    @Override
+    public List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command command,
+                                      @NotNull String alias, @NotNull String[] args) {
+        if (args.length == 1) {
+            return filter(List.of("givekey", "setblock", "removeblock", "reload", "list"), args[0]);
+        }
+        if (args.length == 2 && args[0].equalsIgnoreCase("setblock")) {
+            return filter(crateIds(), args[1]);
+        }
+        if (args.length == 3 && args[0].equalsIgnoreCase("givekey")) {
+            return filter(crateIds(), args[2]);
+        }
+        return List.of();
+    }
+
+    private List<String> crateIds() {
+        List<String> ids = new ArrayList<>();
+        manager.crates().forEach(c -> ids.add(c.id()));
+        return ids;
+    }
+
+    private List<String> filter(List<String> options, String prefix) {
+        return options.stream().filter(s -> s.startsWith(prefix.toLowerCase(Locale.ROOT))).toList();
+    }
+}