Q | FXItems API (com.noctify.API) & Making Addons

FXItems API (com.noctify.API) & Making Addons

The FXItems API (com.noctify.API) provides a set of static helper classes—primarily Registry and Utils—that allow external plugins, modules, and advanced users to register new content, interact with FXItems' core systems, and leverage its utilities for custom development or addon creation.

Overview

• Registry.java — Lets you register custom items, foods, behaviors, commands, and events from any plugin or addon.
• Utils.java — Exposes utility functions for cooldowns, custom item checks, effects, entity size, mana, projectiles, teleports, and more.

---

1. Registry API

Registering Custom Content

All methods are static. You can call them from your plugin on startup (onEnable()):

Register a Custom Item:

Registry.registerItem("MyItemName", MyItemClass.class);

• Registers a new item by name and class.

Register a Custom Item Behavior:

Registry.registerBehavior(plugin, "MyItemName", MyItemBehaviorClass.class);

• Binds a Listener (ability/behavior) to the item.

Register a Custom Recipe:

Registry.addRecipe(plugin, MyItemClass.class);

• Registers a crafting recipe for your item (uses your class’ getRecipe() method).

Register a Command:

Registry.registerCommand(plugin, "mycommand", MyCommandClass.class);
// or registerCommand(plugin, "mycommand"); // for default executor

• Adds a command with a CommandExecutor or by name only.

Register an Event Listener:

Registry.registerEvent(plugin, MyEventListenerClass.class);
// or Registry.registerEvent(plugin, "MyEventListenerClassName");

• Registers a custom Bukkit event Listener (by class or by name).

Register a Custom Food:

Registry.registerFood(plugin, "MyFoodName", MyFoodClass.class, MyFoodBehaviorClass.class);

• Registers a new food item, its effects, and optional custom behavior.

---

2. Utils API

The Utils class gives static access to all major utility systems in FXItems. You can use these from any plugin.

Cooldown Utilities

boolean isCooldown = Utils.isOnCooldown(player.getUniqueId(), "AbilityName");
double timeLeft = Utils.getRemainingCooldown(player.getUniqueId(), "AbilityName");
Utils.setCooldown(player.getUniqueId(), "AbilityName", 30);
Utils.sendCooldownMessage(player, "AbilityName", timeLeft);
Utils.clearAllCooldowns();

Custom Item Utilities

boolean isSpecial = Utils.isCustomItem(itemStack, Material.BLAZE_ROD, "§dMagic Wand");

Effect Utilities

Utils.addEffectWhileHolding(player, Material.BLAZE_ROD, PotionEffectType.FIRE_RESISTANCE, 200, 1);
Utils.removeEffectTask(player);

Entity Size Utilities

Utils.setSize(entity, 2.0f); // Double the entity size
Utils.resetSize(entity);     // Reset size to normal

Mana Utilities

Utils.initializeManaUtils(plugin); // Must be called once during startup
boolean used = Utils.useMana(player, 10);
Utils.setMana(player, 100);
int mana = Utils.getMana(player);

One-Time Craft Utilities

Utils.registerOneTimeCraft(oneTimeCraftUtilsInstance, "LegendarySword", legendarySwordItemStack);
Map<String, OneTimeCraftUtils.OneTimeCraftItem> crafts = Utils.getRegisteredOneTimeCraftItems();

Projectile Utilities

Utils.initializeProjectileUtils(plugin); // Call once on startup
Utils.createCustomProjectile(
    plugin, player, Particle.FLAME, 6, false, false, 1, false,
    2.0, 8.0, false, EntityType.ARROW, false, "", 60, 0
);

• For ModelEngine projectiles, set useModelEngine to true and provide a model ID.

Teleport Utilities

boolean success = Utils.teleportPlayer(player, targetLocation, 100, true, true, true);
// Teleports player with settings for max distance, direction, sound, and particles

---

3. Making Addons for FXItems

To create an addon/plugin that extends FXItems:

1. Add FXItems as a dependency in your build system (plugin.yml and build.gradle/maven).
2. Import the API classes:

   import com.noctify.API.Registry;
   import com.noctify.API.Utils;

3. In your plugin’s onEnable(), use the Registry methods to register your items, foods, commands, and event listeners.
4. Use the Utils methods to interact with FXItems’ core mechanics (cooldowns, effects, projectiles, etc.).
5. Distribute your plugin: Users must have FXItems installed for your addon to function.

---

Example Addon Plugin

public class MyFXAddon extends JavaPlugin {
    @Override
    public void onEnable() {
        // Register a custom item and its behavior
        Registry.registerItem("ThunderStaff", ThunderStaff.class);
        Registry.registerBehavior(this, "ThunderStaff", ThunderStaffBehavior.class);

        // Register a custom command
        Registry.registerCommand(this, "zap", ZapCommand.class);

        // Use FXItems utilities
        Utils.initializeManaUtils(this);
        Utils.initializeProjectileUtils(this);
    }
}

---

Notes & Best Practices

• Always call initializeManaUtils and initializeProjectileUtils in your onEnable if you use mana or projectiles.
• Register your content in onEnable() for reliability.
• All registration and utility methods are static for easy access.
• Check for FXItems presence/version if you distribute your addon.

---

Complete API Reference

See source for latest details:
Registry.java
Utils.java

---

With the FXItems API, you can seamlessly build and distribute new custom items, foods, commands, and mechanics—empowering your server or community to unleash even more creativity!