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

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

---

Table of Contents

• 1. Overview
• 2. Setup & Dependency
• 3. Using the Registry API
• 4. Using the Utils API
• 5. Registering Content Dynamically
• 6. Registering Commands with Permission Levels (v1.2+)
• 7. Example: Minimal Addon Plugin
• 8. Best Practices & Gotchas
• 9. See Also

---

1. Overview

FXItems exposes a modular API for developers to create addons and integrate custom content (items, foods, events, commands, utilities) into the plugin or their own plugins.
As of v1.2+, all registration and utility access is handled via RegistryAPI and UtilsAPI, and commands now support permission level control.

---

2. Setup & Dependency

• Add FXItems as a dependency in your plugin.yml:

  depend: [FXItems]

• If using Maven/Gradle, add FXItems as a dependency (see repo for details).

---

3. Using the Registry API

Import the interfaces and implementations:

import com.noctify.API.Registry;
import com.noctify.API.RegistryAPI;

Instantiate the registry:

Registry registry = new RegistryAPI();

Register a custom item:

registry.registerItem("MY_SWORD", new MySwordDefinition());

Register a custom food:

registry.registerFood("MY_FOOD", new MyFoodDefinition(), new MyFoodBehavior());

Register an event listener:

registry.registerEvent(plugin, MyJoinListener.class);

Register a command:

registry.registerCommand(plugin, "mycommand", MyCommand.class);

---

4. Using the Utils API

Import and instantiate:

import com.noctify.API.Utils;
import com.noctify.API.UtilsAPI;

Utils utils = new UtilsAPI();

Examples:

// Set a cooldown
utils.setCooldown(player.getUniqueId(), "SuperPower", 30);

// Check if an item is a custom FXItem
if (utils.isCustomItem(item, Material.DIAMOND_SWORD, "&aLegendary Sword")) { ... }

// Give/take mana
utils.setMana(player, 100);
utils.useMana(player, 10);

See P | Utility: EntitySizeUtils and others for full method lists.

---

5. Registering Content Dynamically

You can register content at runtime (not just on startup).
For example, you can make an FXItems-based plugin that loads new items, commands, or events after FXItems loads, or based on config/packs.

---

6. Registering Commands with Permission Levels (v1.2+)

FXItems v1.2+ lets you specify permission levels for commands, using PermissionLevel:

import com.noctify.Main.Registration.PermissionLevel;

// Register with explicit permission level and command class
registry.registerCommand(plugin, "mycommand", MyCommand.class, PermissionLevel.ADMIN);

// Register by name (command class auto-detected), with permission level
registry.registerCommand(plugin, "mycommand", PermissionLevel.ADMIN);

// Register by class (defaults to PLAYER)
registry.registerCommand(plugin, "mycommand", MyCommand.class); // Defaults to PLAYER

// Register by name (defaults to PLAYER)
registry.registerCommand(plugin, "mycommand"); // Defaults to PLAYER

Permission Levels:

• PLAYER (default): All players can use the command.
• ADMIN: Only players with the fxitems.owner permission can use the command.

How it works:

• If a command is registered with ADMIN, only players with the fxitems.owner permission node may execute it.
• The permission check is handled by FXItems automatically.
• You can use PermissionUtils.getPermissionLevel(Player) to get a player's permission level in your own logic.

Example:

if (PermissionUtils.getPermissionLevel(player) == PermissionLevel.ADMIN) {
    // Allow admin-only features
}

---

7. Example: Minimal Addon Plugin

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

        // Register a custom item
        registry.registerItem("SUPER_BOW", new SuperBowDefinition());

        // Register a command only admins can use
        registry.registerCommand(this, "superadmin", SuperAdminCommand.class, PermissionLevel.ADMIN);
    }
}

---

8. Best Practices & Gotchas

• Always use the API (RegistryAPI, UtilsAPI) to ensure compatibility.
• Auto-Registration:
  If you place your classes in the correct com.noctify.Custom subpackage, they will be auto-registered at startup.
• Permission Levels:
  Register commands with explicit permission levels for security. Use ADMIN for sensitive commands.
• Dynamic Registration:
  You can register/unregister content at runtime (for reloads, packs, etc).
• Test permissions:
  Make sure your permissions logic matches your intended access control.

---

9. See Also

• B | The Registry System
• S | Auto-Registration System
• U | Changelog