Bukkit API Cheatsheet

By bennetr on Tuesday, October 24, 2023

Plugin generator for IntelliJ IDEA

There is an IntelliJ Plugin that generates skeletons for plugin and mod projects.

Event cheatsheet

BlockBreakEvent, BlockPlaceEvent

Called when a player breaks / places a block.


Called when an entity (TNT, Fireball, Creeper, …) explodes.


Called when a player interacts with the crafting menu.

Example: Disable crafting

public class CraftingProtection implements Listener {
    @EventHandler(priority = EventPriority.LOWEST)
    public void onCrafting(PrepareItemCraftEvent event) {
        if (event.getInventory().getResult() != null) {
            event.getInventory().setResult(new ItemStack(Material.AIR));
            event.getViewers().forEach(player -> player.sendMessage(Component.text("You're not allowed to craft any items!").color(NamedTextColor.RED)));


Called when a player dies.


Called when a player respawns.


Called when a player tries to interact with something.

Example: Launch a fireball when the player right-clicks with a fire charge

public class Fireball implements Listener {
    public void onFireballShoot(PlayerInteractEvent event) {
        Player player = event.getPlayer();
        PlayerInventory inventory = player.getInventory();
        ItemStack itemStack = inventory.getItemInMainHand();

        if (itemStack.getType() == Material.FIRE_CHARGE) {
            if (itemStack.getAmount() <= 0) inventory.setItemInMainHand(null);
            else {
                itemStack.setAmount(itemStack.getAmount() - 1);


Called when a player joins the server.


Called when a player closes an inventory.

Example: Check items that a player bought from a villager

public class TradeHandler implements Listener {
    @EventHandler(priority = EventPriority.LOWEST)
    public void onVillagerGUIClose(InventoryCloseEvent event) {
        // If the GUI is not a villager GUI, quit
        if (!(event.getInventory() instanceof MerchantInventory)) return;

        // Check if the sender is a player
        if (!(event.getPlayer() instanceof Player player)) return;

        // ...

Run tasks every tick

The following code needs to go into the onEnable() method of your plugin class:

getServer().getScheduler().scheduleSyncRepeatingTask(this, () -> {
    // ...
}, 1L, 1L);

Source: Is there a ServerTickEvent? | Bukkit Forum

Working with villagers

public class VillagerUtils {
    public static void clearTrades(Villager villager) {
        List<MerchantRecipe> newRecipes = new ArrayList<>();

    public static void addTrade(Villager villager, ItemStack buyItem1, @Nullable ItemStack buyItem2, ItemStack sellItem) {
        List<MerchantRecipe> oldRecipes = villager.getRecipes();

        MerchantRecipe newRecipe = new MerchantRecipe(sellItem, 999999999);
        if (buyItem2 != null) newRecipe.addIngredient(buyItem2);

        List<MerchantRecipe> newRecipes = new ArrayList<>(oldRecipes);

    public static void addTrade(Villager villager, ItemStack buyItem1, ItemStack sellItem) {
        addTrade(villager, buyItem1, null, sellItem);

Source: Adding custom trades to villagers | Spigot Forum

Working with players

Kill a player


Source: Plugin Tutorial | Bukkit Wiki

Working with teams

Create a team

team = Bukkit.getScoreboardManager().getMainScoreboard().registerNewTeam("some_team");

Set the color, display name and prefix

team.displayName(Component.text("Some Team"));
team.prefix(Component.text("[Some Team] "));

Make invisible teammates have a transparent body


Add players from a list to the team


Source: Scoreboards / Teams with the Bukkit API | Bukkit Forum

Play sounds to a player

player.playSound(Sound.sound(Key.key("minecraft:block.sculk_sensor.clicking"), Sound.Source.MASTER, 0.5F, 1));

Working with items

Spawn an item

world.spawn(location, Item.class, item -> item.setItemStack(new ItemStack(Material.EMERALD, 3)))

Get the name of an item

public static String getDisplayName(ItemStack itemStack) {
    if (itemStack == null) return null;
    if (!itemStack.hasItemMeta()) return null;
    ItemMeta itemMeta = itemStack.getItemMeta();
    if (!itemMeta.hasDisplayName()) return null;
    return PlainTextComponentSerializer.plainText().serialize(itemMeta.displayName());

Working with entities

Check if an entity is in an area

public bool entityInArea(Entity entity, Location loc1, Location loc2) {
    Vector loc1Vector = new Vector(loc1.getX(), 0, loc1.getZ());
    Vector loc2Vector = new Vector(loc2.getX(), 0, loc2.getZ());
    Vector entityVector = new Vector(entity.getLocation().getX(), 0, entity.getLocation().getZ());
    return entityVector.isInAABB(startVector, endVector);

Working with potion effects

Add a potion effect to a player

player.addPotionEffect(new PotionEffect(PotionEffectType.FIRE_RESISTANCE, 200, 1));

Remove all potion effects from a player:


Source: Add potion effect | Bukkit Forum

Modify the world using the WorldEdit API

For adding the dependencies into your project, see API Usage | FAWE Wiki.

Convert a Bukkit Location to a WorldEdit BlockVector3

This function is also used in the examples below.

public static BlockVector3 location2BlockVector3(Location loc) {
    return BukkitAdapter.adapt(loc).toVector().toBlockPoint();

Fill an area with a material

public static void fill(Location loc1, Location loc2, Material mat) {
    World world = BukkitAdapter.adapt(loc1.getWorld());

    // Select the region
    Region selection = new CuboidRegion(world, location2BlockVector3(loc1), location2BlockVector3(loc2));

    // Create a BlockState with air
    BlockState blockState = BukkitAdapter.adapt(mat.createBlockData());

    // This EditSession will be closed after the setBlocks command is finished
    try (EditSession editSession = WorldEdit.getInstance().newEditSession(world)) {
        editSession.setBlocks(selection, blockState);

Copy a region to another location

public static void copy(Location startLoc, Location endLoc, Location pasteLoc) {
    World world = BukkitAdapter.adapt(startLoc.getWorld());

    // Select the region to copy
    CuboidRegion copyRegion = new CuboidRegion(world, location2BlockVector3(startLoc), location2BlockVector3(endLoc));
    BlockArrayClipboard clipboard = new BlockArrayClipboard(copyRegion);

    // This EditSessions will be closed after the copy and paste command is finished
    // Copy
    try (EditSession editSession = WorldEdit.getInstance().newEditSession(world)) {
        ForwardExtentCopy copyOperation = new ForwardExtentCopy(editSession, copyRegion, clipboard,copyRegion.getMinimumPoint());
        // You can specify settings here

    // Paste
    try (EditSession editSession = WorldEdit.getInstance().newEditSession(world)) {
        Operation pasteOperation = new ClipboardHolder(clipboard).createPaste(editSession).to(location2BlockVector3(pasteLoc)).build();
        // You can specify settings here


Creating custom commands

The Cloud CommandFramework is a really good library for adding commands.