Plugins / CrateForge

Public API

Public API

CrateForge exposes a public developer API via the CrateForgeApi interface and 3 Bukkit events. Use it to integrate CrateForge with other plugins or to build custom features.

Getting the API Instance

CrateForgePlugin implements CrateForgeApi. Get the instance via Bukkit's plugin manager:

import com.thecuouz.crateforge.api.CrateForgeApi;
import org.bukkit.Bukkit;

// In your plugin's onEnable or wherever you need it:
CrateForgeApi api = (CrateForgeApi) Bukkit.getPluginManager().getPlugin("CrateForge");

if (api == null) {
    getLogger().warning("CrateForge not found — integration disabled.");
}

Add CrateForge to your plugin.yml as a soft dependency:

# plugin.yml
name: MyPlugin
version: 1.0
softdepend:
  - CrateForge

CrateForgeApi Interface

Crate Access

// Get a single crate by ID
Optional<Crate> crate = api.getCrate("legendary");

if (crate.isPresent()) {
    Crate c = crate.get();
    System.out.println("Crate: " + c.getId());
    System.out.println("Animation: " + c.getAnimation());
    System.out.println("Prizes: " + c.getPrizes().size());
}

// Get all loaded crates
Collection<Crate> allCrates = api.getCrates();
for (Crate c : allCrates) {
    System.out.println(c.getId() + " — " + c.getPrizes().size() + " prizes");
}

Key Management

// Give a player 1 legendary key (also fires KeyObtainedEvent)
api.giveKey(player, "legendary_key", 1);

// Give multiple keys
api.giveKey(player, "common_key", 5);

Note: giveKey() fires a KeyObtainedEvent which other plugins can listen to.

Token Economy

// Get a player's token balance
int balance = api.getTokenBalance(player, "premium");
System.out.println(player.getName() + " has " + balance + " premium tokens");

// Give tokens to a player
api.giveTokens(player, "premium", 100);

// Take tokens from a player (returns false if insufficient balance)
boolean success = api.takeTokens(player, "premium", 50);
if (!success) {
    player.sendMessage("Not enough tokens!");
}

Bukkit Events

CrateForge fires 3 custom events you can listen to in your plugin.

CrateOpenStartEvent

Fired when a player initiates a crate open (before the animation plays). Can be cancelled or used to override the prize.

import com.thecuouz.crateforge.api.event.CrateOpenStartEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class CrateListener implements Listener {

    @EventHandler
    public void onCrateOpenStart(CrateOpenStartEvent e) {
        Player player = e.getPlayer();
        Crate crate = e.getCrate();

        // Cancel the crate open entirely
        if (someCondition) {
            e.setCancelled(true);
            player.sendMessage("You cannot open this crate right now!");
            return;
        }

        // Override the rolled prize with a specific prize
        Prize mySpecificPrize = crate.getPrizes().stream()
            .filter(p -> p.getId().equals("diamond_sword"))
            .findFirst()
            .orElse(null);

        if (mySpecificPrize != null) {
            e.setPrize(mySpecificPrize);  // Forces this prize to be given
        }

        // e.getPrize() — the currently rolled prize (before any override)
        // e.getKey()   — the key item used
    }
}

Event Properties:

CratePrizeWonEvent

Fired after the animation finishes and rewards are granted to the player. Cannot be cancelled (rewards already given).

import com.thecuouz.crateforge.api.event.CratePrizeWonEvent;

@EventHandler
public void onPrizeWon(CratePrizeWonEvent e) {
    Player player = e.getPlayer();
    Crate crate = e.getCrate();
    Prize prize = e.getPrize();

    // Log wins to a database
    myDatabase.logWin(player.getUniqueId(), crate.getId(), prize.getId());

    // Announce legendary wins globally
    if (prize.getRarity() == Rarity.LEGENDARY) {
        Bukkit.broadcastMessage(
            player.getName() + " won " + prize.getDisplayName() + " from " + crate.getDisplayName() + "!"
        );
    }
}

Note: CrateForge's own built-in loot broadcasts (e.g. "Steve won Godly Sword from Legendary Crate") are emitted through the TTS-Studio chat pipeline, so they appear prefixed with CrateForge: in the configured purple. Broadcasts you emit yourself from CratePrizeWonEvent listeners are unprefixed by default — wrap them with the TTS-Studio ChatPrefix helper if you want them branded.

// (illustrative — only when reusing the suite chat helper)
import com.ttsstudio.sdk.chat.ChatPrefix;
import com.ttsstudio.sdk.PluginIdentity;

ChatPrefix.broadcast(PluginIdentity.of(crateforgePlugin),
    player.getName() + " won " + prize.getDisplayName() + " from " + crate.getDisplayName() + "!");

Event Properties:

KeyObtainedEvent

Fired when a player receives a crate key (via api.giveKey(), /cf givekey, mob drops, or the shop).

import com.thecuouz.crateforge.api.event.KeyObtainedEvent;

@EventHandler
public void onKeyObtained(KeyObtainedEvent e) {
    Player player = e.getPlayer();
    String keyId = e.getKeyId();
    int amount = e.getAmount();
    KeyObtainSource source = e.getSource(); // COMMAND, SHOP, MOB_DROP, API

    // Send a notification
    player.sendMessage("You received " + amount + "x " + keyId + "!");

    // Track key distribution in stats
    myStats.recordKeyGiven(player.getUniqueId(), keyId, amount, source);
}

Event Properties:

Full API Summary

Navigation

Home | PlaceholderAPI | Commands & Permissions | Crate Format