Create Custom Items

01 / 13

Before starting: first recognize the running position

The first 30 lessons lay the foundation for ordinary Java programs. At this stage, the code is connected to the Paper server: the Minecraft client is responsible for entering the world, the server loads the plug-in, and the events and commands hand over player actions to your methods.

This book uses JDK 21 and Paper 1.21.11, and the client version is also consistent. The latest version on the download page may have changed, select it by version number. This book uses normal plugin.yml and the Bukkit API; no claims are made to support Folia at this stage.

The short examples in the picture frame are partial fragments. Read the location description of this section first, and do not save each as a plug-in. The file name will be clearly given for the complete file; when the same file is divided into multiple segments, they will be connected by number, and the package name, import and outer class will only appear once.

• Prediction: Write success conditions and expected messages first.
• Run: After successful construction, install and restart on the dedicated local test server.
• Verification: Ordinary players, management identities and consoles take corresponding paths respectively.

02 / 13

The article body and instructions are modified separately

The ordinary compass is renamed "Super Miner Compass" in the anvil, so come and apply for special abilities. The guard looked at the name and almost let me go. The display name can be changed, and reliable identification requires viewing the identity tag written by the plug-in.

ItemStack is the item and ItemMeta is the description and additional data. Write the PDC tag corresponding to NamespacedKey when making; check the material, data type and value when identifying. The name is responsible for allowing players to understand it, and the label is responsible for allowing the program to recognize it correctly.

ItemStack item = new ItemStack(Material.COMPASS);
var meta = item.getItemMeta();
meta.displayName(Component.text("Miner's Compass"));
meta.lore(List.of(Component.text("Right-click the main hand to view classroom tasks")));
item.setItemMeta(meta);

// If you forget setItemMeta, Check if the name and description are actually saved.

03 / 13

The anvil can be renamed but cannot prove identity.

Rename the ordinary compass to "Miner's Compass", it looks real, but the name is just a label. The program checks for PDC tags hidden in the item's data. The display name is responsible for the player to recognize it, and the data key is responsible for the program to recognize it.

compassKey = new NamespacedKey(this, "miner_compass");

meta.getPersistentDataContainer().set(
    compassKey, PersistentDataType.BYTE, (byte) 1);

04 / 13

Put production and recognition into the same class

Create a new CompassItems.java and put it into the de.teacherma.lesson37 package. Use the same key and the same type for production and identification to avoid writing miner_compass on one side and looking for mining_compass on the other, which is like sending the key to the wrong door.

package de.teacherma.lesson37;

import java.util.List;
import net.kyori.adventure.text.Component;
import org.bukkit.Material;
import org.bukkit.NamespacedKey;
import org.bukkit.inventory.ItemStack;
import org.bukkit.persistence.PersistentDataType;

public final class CompassItems {
    private CompassItems() { }
    public static ItemStack create(NamespacedKey key) {
        ItemStack item = new ItemStack(Material.COMPASS);
        var meta = item.getItemMeta();
        meta.displayName(Component.text("Miner's Compass"));
        meta.lore(List.of(Component.text("Right-click the main hand to view classroom tasks")));
        meta.getPersistentDataContainer().set(key, PersistentDataType.BYTE, (byte) 1);
        item.setItemMeta(meta);
        return item;
    }
    public static boolean isOurs(ItemStack item, NamespacedKey key) {
        if (item == null || item.getType() != Material.COMPASS || !item.hasItemMeta())
            return false;
        Byte marker = item.getItemMeta().getPersistentDataContainer()
                .get(key, PersistentDataType.BYTE);
        return Byte.valueOf((byte) 1).equals(marker);
    }
}

05 / 13

Check material type and value

item may be null when empty-handed. Ordinary compasses may not have meta; if they do have meta, they may not have our marks. The identification function eliminates mismatches in order, and finally compares whether the BYTE value is 1. Only checking "key exists" will include other tag values.

Byte marker = meta.getPersistentDataContainer()
        .get(compassKey, PersistentDataType.BYTE);
boolean ours = Byte.valueOf((byte) 1).equals(marker);

meta.getPersistentDataContainer().remove(compassKey);
item.setItemMeta(meta);

06 / 13

Don’t rush to report with both hands

Interaction events may be triggered by two hands respectively. If the off-hand is also holding a compass, two mission prompts may appear for the same action. We only accept EquipmentSlot.HAND, which is the main hand; we do not rely on "delete a message after sending it" to remedy it.

Stop and think about it: Should the True Compass still be recognized after it has been renamed by the player? Should the ordinary compass gain abilities after being renamed with the same name?

if (event.getHand() != EquipmentSlot.HAND) return;

Action action = event.getAction();
if (action != Action.RIGHT_CLICK_AIR
        && action != Action.RIGHT_CLICK_BLOCK) return;

• The master holds the compass in this lesson and right-clicks the air: a task is displayed.
• Right-click the block with the main hand: the task is displayed, and the original interaction with the block can still be continued.
• Holding the compass in the second hand or waving the left button: No tasks will be displayed in this lesson.

07 / 13

Reading tasks does not mean approval of interaction

When right-clicking on the air, the original version may predict "no action" and mark the event as cancelled. Therefore this read-only prompt listener does not have ignoreCancelled=true set. It only looks at message concurrency prompts, does not restore cancellation, and does not authorize block operations.

@EventHandler(priority = EventPriority.MONITOR)
public void onUse(PlayerInteractEvent event) {
    // After the main hand, actions, and items are all matched, only the task text is sent..
}

event.setCancelled(false); // Don’t do this in this lesson

08 / 13

Register command for compass project

The project name is set to BlockAcademyL37. The resources directory only requires plugin.yml, and there is no config.yml in this lesson. The main class and item tool class are in the lesson37 package, and the build script follows Lesson 31.

name: BlockAcademyL37
version: 1.0.0
main: de.teacherma.lesson37.CompassPlugin
api-version: '1.21.11'
author: TeacherMa
website: https://www.teacher-ma.de
commands:
  minercompass:
    description: Get the Classroom Miner's Compass
    usage: /minercompass
permissions:
  blockacademy.compass.give:
    default: op

src/main/java/de/teacherma/lesson37/
  CompassItems.java
  CompassPlugin.java

09 / 13

The first half of the compass main class

Create new CompassPlugin.java. This page first declares dependencies, creates a key, and registers commands and listeners; the next page continues with commands and interaction logic. Don't add a new class between two pages.

package de.teacherma.lesson37;

import java.util.Objects;
import net.kyori.adventure.text.Component;
import org.bukkit.NamespacedKey;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.block.Action;
import org.bukkit.event.player.PlayerInteractEvent;
import org.bukkit.inventory.EquipmentSlot;
import org.bukkit.plugin.java.JavaPlugin;

public final class CompassPlugin extends JavaPlugin implements Listener {
    private NamespacedKey compassKey;
    @Override
    public void onEnable() {
        compassKey = new NamespacedKey(this, "miner_compass");
        Objects.requireNonNull(getCommand("minercompass")).setExecutor(this);
        getServer().getPluginManager().registerEvents(this, this);
    }

10 / 13

lower half of compass main class

Immediately following the previous page. Check the sender, permissions and parameters before receiving it; put the compass that cannot fit in your backpack at your feet. The interactive method only does three filters and one prompt, and is short enough for you to explain line by line.

    @Override
    public boolean onCommand(CommandSender sender, Command command,
                             String label, String[] args) {
        if (!(sender instanceof Player p)) {
            sender.sendMessage("Please get the compass in the game"); return true;
        }
        if (!p.hasPermission("blockacademy.compass.give")) {
            p.sendMessage("Please collect it after authorization from the teacher"); return true;
        }
        if (args.length != 0) { p.sendMessage("Usage: /minercompass"); return true; }
        var left = p.getInventory().addItem(CompassItems.create(compassKey));
        left.values().forEach(item -> p.getWorld().dropItemNaturally(p.getLocation(), item));
        p.sendMessage(left.isEmpty() ? "The compass has been included in the package, try right-clicking on the main hand" : "Compass at feet");
        return true;
    }
    @EventHandler(priority = EventPriority.MONITOR)
    public void onUse(PlayerInteractEvent event) {
        if (event.getHand() != EquipmentSlot.HAND) return;
        Action action = event.getAction();
        if (action != Action.RIGHT_CLICK_AIR && action != Action.RIGHT_CLICK_BLOCK) return;
        if (!CompassItems.isOurs(event.getItem(), compassKey)) return;
        event.getPlayer().sendMessage(Component.text("Classroom tasks: Prepare tools and participate in the ore sprint competition!"));
    }
}

11 / 13

real and fake compasses take the exam together

Only testing the true compass will miss most of the problems. Prepare an ordinary compass, a renamed compass and a compass for this lesson, and let the "fake students" also take the exam. Document expectations and actualities, and don’t declare graduation just by seeing a sentence in the chat box.

12 / 13

Expansion challenges and own acceptance records

Leave the source code, actual running results and a problem record. Explain it in your own words first, and then run the verification; where the results are different from the predictions, they are often the most worthy of discussion.

• Wooden pickaxe: Add two lines of lore to the compass and explain why setItemMeta is needed.
• Iron pickaxe: four identification tests of production material, key, type and value. Ordinary items cannot be accidentally triggered.
• Diamond Pickaxe: Design a three-piece miner set, with different labels to distinguish functions; indicate the behavior after receiving permissions and restarting.
• Acceptance requirements: Test real items, fake items with the same name, empty hands, off-hands, and renamed real items; one operation cannot be repeated with two hands.

13 / 13

Leave the evidence for the next adventure

Divide "can compile", "number rules pass" and "actual performance of the game is correct" into three columns. Scenarios that are not running are written to be tested; when bugs are discovered, trigger conditions, expected, actual, minimum repairs, and retest results are recorded.

• Explain why each arrow in this lesson points from here to there; the parallel cards have no sequential meaning.
• First change a rule, then modify the description and expectations at the same time, and retest with the same input.