C | Creating Custom Items

C | Creating Custom Items

---

Table of Contents

• 1. Overview
• 2. FXItemDefinition: All Options & Parameters
• 3. FXItemBehavior: Custom Logic
• 4. FXItemRecipe: Recipes & Crafting
• 5. Registering Your Item
  • 5.1 Manual Registration
  • 5.2 Auto-Registration
• 6. Real-World Examples
• 7. Advanced Features
• 8. Troubleshooting & FAQ
• 9. See Also

---

1. Overview

Every custom item in FXItems is defined and configured using the FXItemDefinition class.
FXItems does not use attribute files or YAML for items: everything is in code, with clear API options for every aspect of appearance, lore, behavior, and crafting.

---

2. FXItemDefinition: All Options & Parameters

Constructor

public FXItemDefinition(
    String id,
    String displayName,
    Material material,
    Rarity rarity,
    FXItemBehavior behavior,
    Integer customModelData,
    boolean oneTimeCraft,
    boolean unbreakable,
    boolean hideFlags,
    List<String> lore,
    FXItemRecipe recipe
)

Parameter Reference

Parameter	Type	Required	Description
id	String	Yes	Unique identifier for the item. Lowercase, no spaces recommended.
displayName	String	Yes	Name shown in-game. Supports § color codes.
material	Material	Yes	Minecraft material (Material.DIAMOND_SWORD, etc.).
rarity	Rarity	No	Enum: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY.
behavior	FXItemBehavior	No	Custom logic for the item (see below).
customModelData	Integer (nullable)	No	For resource-pack custom models. Null for none.
oneTimeCraft	boolean	No	If true, only craftable once per player/server.
unbreakable	boolean	No	If true, item never takes durability damage.
hideFlags	boolean	No	If true, hides vanilla item flags in tooltip.
lore	List	No	Tooltip text. Color codes supported.
recipe	FXItemRecipe	No	Crafting recipe. See below.

Notes:

• Only id, displayName, and material are strictly required.
• All other fields can be null or left as default.
• For best practice, fill out all fields for clarity and documentation.

---

3. FXItemBehavior: Custom Logic

Custom logic for items (active abilities, passives, events, etc.) is implemented by your own class that implements FXItemBehavior.

Example Interface

public interface FXItemBehavior {
    default void onRightClick(Player player, ItemStack item, Block block, Action action) {}
    default void onLeftClick(Player player, ItemStack item, Block block, Action action) {}
    default void onAttack(EntityDamageByEntityEvent event, Player player, ItemStack item) {}
    default void onPassive(Player player, ItemStack item) {}
    // ...extend as FXItems is updated!
}

Example Implementation

public class MythrilSwordBehavior implements FXItemBehavior {
    @Override
    public void onRightClick(Player player, ItemStack item, Block clickedBlock, Action action) {
        player.getWorld().strikeLightning(player.getLocation());
        player.sendMessage("§bYou called lightning!");
    }
}

• Any method not relevant can be left unimplemented (they default to empty).
• Many hooks are supported: right/left click, attack, damage taken, passive tick, etc.
• See Advanced: Custom Effects in FXItems for more.

---

4. FXItemRecipe: Recipes & Crafting

Constructor

public FXItemRecipe(
    List<ItemStack> ingredients, // 9 elements, top-left to bottom-right
    boolean shaped,
    int outputAmount,
    boolean enabled
)

Parameter	Description
ingredients	List of 9 ItemStacks (use Material.AIR for empty slot).
shaped	true = shaped, false = shapeless recipe.
outputAmount	How many items produced per craft.
enabled	Enables/disables the recipe.

Recipe Features

• Supports custom items as ingredients (must match by displayName + material).
• Recipes can be updated by re-registering the item.

---

5. Registering Your Item

5.1 Manual Registration

Registry registry = new RegistryAPI();
registry.registerItem("mythril_sword", mythrilSwordDefinition);

• Place registration in your plugin's onEnable() or similar setup.

5.2 Auto-Registration

Recommended for large codebases.

1. Annotate your behavior class:

   @AutoRegister
   public class MythrilSwordBehavior implements FXItemBehavior { ... }

2. In your plugin's main class:

   BehaviorAutoRegistrar.registerAll(this, "your.base.package");

• All annotated behaviors in the package are discovered and registered.

---

6. Real-World Examples

Simple Custom Sword

FXItemDefinition simpleSword = new FXItemDefinition(
    "simple_sword",
    "§bSimple Sword",
    Material.IRON_SWORD,
    Rarity.UNCOMMON,
    new SimpleSwordBehavior(),
    null,    // customModelData
    false,   // oneTimeCraft
    false,   // unbreakable
    true,    // hideFlags
    Arrays.asList("§7A basic enchanted sword."),
    null     // recipe
);

Sword With Advanced Recipe & Model

FXItemDefinition mythrilSword = new FXItemDefinition(
    "mythril_sword",
    "§bMythril Sword",
    Material.DIAMOND_SWORD,
    Rarity.RARE,
    new MythrilSwordBehavior(),
    5, // customModelData (resource pack)
    false,
    true,
    true,
    Arrays.asList(
        "§7A sword forged from mythril.",
        "",
        "§fRight Click: Shoots a beam!"
    ),
    new FXItemRecipe(
        Arrays.asList(
            new ItemStack(Material.AIR),
            new ItemStack(Material.DIAMOND),
            new ItemStack(Material.AIR),
            new ItemStack(Material.IRON_BLOCK),
            new ItemStack(Material.STICK),
            new ItemStack(Material.IRON_BLOCK),
            new ItemStack(Material.AIR),
            new ItemStack(Material.STICK),
            new ItemStack(Material.AIR)
        ),
        true, // shaped
        1,    // outputAmount
        true  // enabled
    )
);

---

7. Advanced Features

• Custom Model Data: Integrate with resource packs for truly unique visuals.
• One-Time Craft: Use for legendary or quest items (see OneTimeCraftUtils).
• Hide Flags: Make tooltips clean for custom items (e.g., hide vanilla enchantments/attributes).
• Passives: Use onPassive for effects that apply while held or in inventory.

---

8. Troubleshooting & FAQ

• "My item isn't working":

  • Check that the ID is unique and matches in registration/crafting.
  • Make sure you re-register your item after any code change.
  • Confirm your behavior class is correct and not missing required methods.

• "Recipe isn't showing up":

  • Double-check ingredient order (3x3, top-left to bottom-right).
  • Confirm that all custom ingredients are also registered items.

• "Color codes not working":

  • Use § for color codes in displayName and lore.

• "How do I change rarity colors?":

  • Edit RarityLang.yml in the plugin folder.

---

9. See Also

• B | The Registry System: Items, Foods, Commands, Events
• D | Creating Custom Foods
• E | Advanced: Custom Effects in FXItems
• S | Auto-Registration System
• L | OneTimeCraftUtils

---