C | Creating Custom Items

Creating Custom Items (Full Guide)

This is a complete guide to making custom items with FXItems.
We'll cover every method you can implement, how to make advanced recipes, how to add abilities, and every registration step.

---

Step 1: Define Your Item Class

• Place your item class in com.noctify.Custom.ItemAttributes.
• Use static methods for item construction, lore, recipes, and more.

Example: MagicWand

public class MagicWand {
    public static ItemStack createItem() {
        ItemStack wand = new ItemStack(Material.BLAZE_ROD);
        ItemMeta meta = wand.getItemMeta();
        meta.setDisplayName("§dMagic Wand");
        meta.setLore(List.of("§7Casts powerful spells!"));
        wand.setItemMeta(meta);
        return wand;
    }

    // Optional: Custom lore for book GUIs or display
    public static List<String> getLore() {
        return List.of("§7A wand crackling with arcane power.");
    }

    // Optional: Add a custom shaped recipe
    public static ShapedRecipe getRecipe(Plugin plugin, NamespacedKey key) {
        ShapedRecipe recipe = new ShapedRecipe(key, createItem());
        recipe.shape(" S ", " B ", " R ");
        recipe.setIngredient('S', Material.NETHER_STAR);
        recipe.setIngredient('B', Material.BLAZE_ROD);
        recipe.setIngredient('R', Material.REDSTONE_BLOCK);
        return recipe;
    }
}

What does each method do?

• createItem() — Constructs the ItemStack with display name, lore, etc. Used for giving/spawning the item.
• getLore() — Optional, for GUIs or help pages.
• getRecipe() — Returns a Bukkit Recipe object for registration.

---

Step 2: Register Your Item

In ItemRegistry's initialize(Plugin plugin):

registerItem("MagicWand", MagicWand.class);
addRecipe(plugin, MagicWand.class); // Uses your getRecipe() method

---

Step 3: Add Custom Item Behavior (Abilities)

Place custom behaviors in com.noctify.Custom.ItemBehavior.

Example: Right-click to Cast Fireball (with Cooldown)

public class MagicWandBehavior implements Listener {
    public MagicWandBehavior(Plugin plugin) {}

    @EventHandler
    public void onPlayerUse(PlayerInteractEvent event) {
        Player player = event.getPlayer();
        // Use CustomItemUtils to match the item
        if (!CustomItemUtils.isCustomItem(event.getItem(), Material.BLAZE_ROD, "§dMagic Wand")) return;
        // Cooldown check
        if (CooldownUtils.isOnCooldown(player.getUniqueId(), "MagicWandAbility")) {
            CooldownUtils.sendCooldownMessage(player, "MagicWandAbility", CooldownUtils.getRemainingCooldown(player.getUniqueId(), "MagicWandAbility"));
            return;
        }
        // Ability: Launch fireball
        player.launchProjectile(Fireball.class).setIsIncendiary(false);
        player.sendMessage("§bYou cast a spell!");
        CooldownUtils.setCooldown(player.getUniqueId(), "MagicWandAbility", 15.0);
    }
}

Register the Behavior

In ItemRegistry:

registerBehavior(plugin, "MagicWand", MagicWandBehavior.class);

---

Step 4: Make Legendary/One-Time Craft Items

You may want to allow only a single crafting per server (e.g., legendary artifacts).

Example: Register as One-Time Craft

OneTimeCraftUtils.registerOneTimeItem(MagicWand.class);

In your crafting event listener, block crafting if OneTimeCraftUtils.hasBeenCrafted(MagicWand.class) is true.

---

Step 5: Using Utilities in Items

You can use any utility (see Utility Class Documentation) in your item abilities, such as:

• ManaUtils for mana costs
• ProjectileUtils for custom projectiles
• EffectUtils for temporary buffs

---

Step 6: Testing

1. Register your item. Reload/restart server.
2. Use /fxgive <player> MagicWand to spawn your item.
3. Try right-clicking and observe ability, cooldown, etc.

---

Advanced: Custom Model Projectiles

If you have ModelEngine installed, use ProjectileUtils.createCustomProjectile() to launch projectiles with custom models from your item behavior.

---

Example: Custom Model Projectile

ProjectileUtils.createCustomProjectile(
    plugin, 
    player, 
    Particle.FLAME, 
    8, // damage
    true, // silent
    false, // gravity
    1, // knockback
    false, // pierce
    2.5, // speed
    20.0, // range
    false, // explosive
    EntityType.ARROW, 
    true, // customModel
    "my_model", 
    60, // lifetime ticks
    0 // spread
);

See ProjectileUtils for details.

---

Full Checklist for Custom Items

• Item class with createItem()
• Optional: getRecipe(), getLore()
• Register in ItemRegistry
• Optional: Custom behavior in ItemBehavior, registered with registerBehavior
• (Optional) One-time crafting with OneTimeCraftUtils
• (Optional) Use utility classes for effects, mana, etc.

---

Next: Creating Custom Foods (Complete Example)