Create a specialitem

This example shows how to create a simple special item with custom behavior.

Special items combine item creation with event handling to create interactive features.

Deep dive: [[SpecialItems|Core-API/Items/SpecialItems]]

---

Steps

1. Create a class extending PixelSpecialItem
2. Define the item in createItem()
3. Listen for interactions using @EventHandler
4. Register the special item
5. Add it to a category

---

Implementation

package net.mixelpixel.example.bukkit.item.specialitem;

import net.mixelpixel.core.bukkit.api.BukkitCoreLibrary;
import net.mixelpixel.core.bukkit.api.coreaddon.specialitem.item.PixelSpecialItem;
import net.mixelpixel.core.bukkit.api.event.events.PixelPlayerInteractEvent;
import net.mixelpixel.core.bukkit.api.inventory.InventoryHandler;
import net.mixelpixel.core.bukkit.api.player.BukkitPixelPlayer;
import net.mixelpixel.core.bukkit.api.util.item.ItemBuilder;
import net.mixelpixel.example.bukkit.ExamplePlugin;
import org.bukkit.Material;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.block.Action;
import org.bukkit.inventory.EquipmentSlot;
import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;

public class TitleSpecialItem extends PixelSpecialItem<ExamplePlugin> {

    public TitleSpecialItem(@NotNull ExamplePlugin plugin) {
        super(
                plugin,
                "Title-Selector",
                SpecialType.EXAMPLE,
                "28.03.2025 12:00:00"
        );
    }

    @Override
    public @NotNull ItemStack createItem() {
        return ItemBuilder.material(Material.NAME_TAG)
                .glowing()
                .name(
                        "<white><obf><b>ii</b></obf></white>" +
                                " <gradient:#FFD700:#DE0A26><b>Title selection</b></gradient>" +
                                " <white><obf><b>ii</b></obf></white>"
                )
                .lore(
                        " <dark_gray>►</dark_gray> Right-click this item, to",
                        "   open a title selection and",
                        "   redeem an <gold>exclusive title</gold>!"
                )
                .build();
    }

    @EventHandler(priority = EventPriority.HIGHEST)
    public void onInteract(PixelPlayerInteractEvent event) {
        EquipmentSlot hand = event.getHand();
        if (hand == null) return;

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

        ItemStack item = event.getItem();
        if (item == null || !isItem(item)) return;

        event.setCancelled(true);

        BukkitPixelPlayer player = event.getPlayer();

        InventoryHandler inventoryHandler = BukkitCoreLibrary.getInventoryHandler();
        inventoryHandler.openInventory(
                getPlugin(),
                player,
                TitleSelectorInventory.class,
                "Select a title",
                9
        );
    }

}

---

Special item type

package net.mixelpixel.example.bukkit.item.specialitem;

import net.mixelpixel.core.bukkit.api.coreaddon.specialitem.item.PixelSpecialItemType;
import net.mixelpixel.core.bukkit.api.coreaddon.specialitem.item.SpecialItemType;
import org.jetbrains.annotations.NotNull;

public class SpecialType {

    @NotNull
    public static final SpecialItemType EXAMPLE = new PixelSpecialItemType(
            1,
            "Example",
            "Example",
            "<red>Example</red>"
    );

}

---

Registering the special item

TitleSpecialItem titleSpecialItem = new TitleSpecialItem(this);
SpecialItemHandler specialItemHandler = BukkitCoreLibrary.getSpecialItemHandler();
specialItemHandler.registerSpecialItem(titleSpecialItem);

---

Adding the item to a category

// creates a category - most of the time there already exists a category


SpecialItemCategory exampleCategory = specialItemHandler.createCategory(
        "Example",
        "<red>Example Items</red>",
        0,
        ResourcePackItems.BAG.build()
);

// adds the item to the category


exampleCategory.addItem(titleSpecialItem);

---

Explanation

• PixelSpecialItem is the base class for special items
• createItem() defines the item appearance
• @EventHandler listens for player interactions (each special item automatically acts as a PixelListener)
• isItem(item) checks if the clicked item matches this special item
• Special items must be registered and added to a category

---

Notes

• Always use the existing SpecialType class
• Do not create new PixelSpecialItemType instances without approval
• Keep special item logic simple and focused

---

Next step

[[Create a sql table and execute stuff|Core-API/Build-your-first-feature/Data-&-Persistence/Create-a-sql-table-and-execute-stuff]]