Skip to content

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

Jump to bottom
Sartaj Singh edited this page May 31, 2025 · 3 revisions

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

Table of Contents

1. Overview

The com.noctify.API package exposes the primary public API for FXItems.
It provides registry and utility interfaces that allow you to manage custom items, foods, commands, events, and to use powerful utility methods for gameplay features.
This API is designed for both addon/plugin developers and advanced server scripting.

2. What is the FXItems API?

FXItems API consists of two main interfaces:

  • Registry API (Registry, RegistryAPI)
    Lets you register and retrieve custom items, foods, commands, and events.
    This is the main entrypoint for adding your own content.

  • Utils API (Utils, UtilsAPI)
    Provides a wide range of utilities: cooldowns, custom item checks, potion effects, mana, projectiles, entity size, teleportation, and more.

Each has a concrete implementation (RegistryAPI, UtilsAPI) you instantiate and use.

3. Registry API: Registering Items, Foods, Commands, Events

Interface: com.noctify.API.Registry
Implementation: RegistryAPI

Registering a Custom Item

Registry registry = new RegistryAPI();
registry.registerItem("EXAMPLE_SWORD", new FXItemDefinition(...));
  • itemName is a unique string key for the item.
  • FXItemDefinition defines the item's material, lore, abilities, etc.

Registering a Custom Command

registry.registerCommand(plugin, "example", ExampleCommand.class);

or, for a command with default handling:

registry.registerCommand(plugin, "simplecommand");

Registering a Custom Event

registry.registerEvent(plugin, ExampleListener.class);

or

registry.registerEvent(plugin, "CustomEventName");

Registering a Custom Food

registry.registerFood("MAGIC_BREAD", new FXFoodDefinition(...), new FXFoodBehavior(...));

Getting a Custom Item

ItemStack item = registry.getCustomItem("EXAMPLE_SWORD");

4. Utils API: Using FXItems Utilities

Interface: com.noctify.API.Utils
Implementation: UtilsAPI

Cooldown Functions

Utils utils = new UtilsAPI();
utils.setCooldown(player.getUniqueId(), "ability_key", 30);
if (utils.isOnCooldown(player.getUniqueId(), "ability_key")) {
    double secondsLeft = utils.getRemainingCooldown(player.getUniqueId(), "ability_key");
    utils.sendCooldownMessage(player, "Ability Name", secondsLeft);
}
utils.clearAllCooldowns();

Custom Item Checks

if (utils.isCustomItem(item, Material.DIAMOND_SWORD, "§aExample Sword")) {
    // handle custom item logic
}

Effects While Holding

utils.addEffectWhileHolding(player, Material.BLAZE_ROD, PotionEffectType.FIRE_RESISTANCE, 200, 1);
// Removes all holding effects for a player:
utils.removeEffectTask(player);

Entity Size (Requires EntitySize Plugin)

utils.setSize(player, 2.0f);   // Double player size
utils.resetSize(player);       // Reset to normal size

Mana System

utils.initializeManaUtils(plugin);
utils.setMana(player, 100);
boolean used = utils.useMana(player, 10);
int mana = utils.getMana(player);
  • Mana automatically regenerates and is displayed with an action bar.

One-Time Craft Registration

utils.registerOneTimeCraft(oneTimeCraftUtils, "EXCALIBUR", excaliburItemStack);
Map<String, OneTimeCraftUtils.OneTimeCraftItem> items = utils.getRegisteredOneTimeCraftItems();

Projectiles (with or without ModelEngine)

utils.createCustomProjectile(
    plugin,
    player,
    Particle.FLAME,
    2,
    true,   // gravity
    false,  // glowing
    1,      // knockback
    false,  // silent
    2.0,    // speed
    8.0,    // damage
    false,  // speedBasedDamage
    EntityType.ARROW,
    false,  // useModelEngine
    "",     // modelId
    60,     // despawn time (ticks)
    0       // piercingLevel
);

Teleportation

boolean success = utils.teleportPlayer(player, targetLocation, 40, true, true, true);
  • Teleports the player with distance checks, sound, and particles.

5. Making Addons & Integration

You can build your own plugins/addons that depend on FXItems:

  1. Add FXItems as a dependency in your plugin’s plugin.yml and build system (Maven/Gradle).
  2. Import com.noctify.API.RegistryAPI and com.noctify.API.UtilsAPI.
  3. Register your content in your plugin’s onEnable() or initialization method, using the APIs above.

Example: Minimal Addon

public class MyAddon extends JavaPlugin {
    @Override
    public void onEnable() {
        Registry registry = new RegistryAPI();
        Utils utils = new UtilsAPI();

        // Register a custom item, command, or event
        registry.registerItem("MY_ITEM", new FXItemDefinition(...));
    }
}

Notes

  • You can retrieve and use all utilities (mana, cooldowns, size, projectiles, etc.) via UtilsAPI.
  • If your addon is providing new commands/events, register them through the API, not directly.

6. API Reference: Methods and Patterns

Registry API (Registry, RegistryAPI)

  • void registerItem(String itemName, FXItemDefinition itemDefinition)
  • ItemStack getCustomItem(String itemName)
  • void registerCommand(Plugin plugin, String commandName, Class<? extends CommandExecutor> commandClass)
  • void registerCommand(Plugin plugin, String commandName)
  • void registerEvent(Plugin plugin, Class<? extends Listener> eventClass)
  • void registerEvent(Plugin plugin, String eventName)
  • void registerFood(String foodName, FXFoodDefinition definition, FXFoodBehavior behavior)

Utils API (Utils, UtilsAPI)

  • boolean isOnCooldown(UUID playerId, String key)
  • double getRemainingCooldown(UUID playerId, String key)
  • void setCooldown(UUID playerId, String key, int seconds)
  • void sendCooldownMessage(Player player, String itemName, double timeLeft)
  • void clearAllCooldowns()
  • boolean isCustomItem(ItemStack item, Material material, String displayName)
  • void addEffectWhileHolding(Player player, Material itemMaterial, PotionEffectType effectType, int duration, int amplifier)
  • void removeEffectTask(Player player)
  • void setSize(Entity entity, float scale)
  • void resetSize(Entity entity)
  • void initializeManaUtils(Plugin plugin)
  • boolean useMana(Player player, int amount)
  • void setMana(Player player, int amount)
  • int getMana(Player player)
  • void registerOneTimeCraft(OneTimeCraftUtils instance, String name, ItemStack item)
  • Map<String, OneTimeCraftUtils.OneTimeCraftItem> getRegisteredOneTimeCraftItems()
  • void initializeProjectileUtils(Plugin plugin)
  • void createCustomProjectile(...)
  • boolean teleportPlayer(Player player, Location targetLocation, int maxDistance, boolean preserveDirection, boolean playSound, boolean spawnParticles)

7. Best Practices

  • Always use the API, not internal maps or static fields.
  • Check for plugin dependencies (EntitySize, ModelEngine) before using related features.
  • Use interface types (Registry, Utils) for forward compatibility.
  • Register all your custom content in your plugin’s onEnable() or init routine.
  • Test your integration on a dev server before deploying to production.

8. See Also

FXItems Wiki

Clone this wiki locally