G | Creating Custom Events & Behaviors

G | Creating Custom Events & Behaviors

---

Table of Contents

• 1. Overview
• 2. What Are Custom Events and Behaviors?
• 3. Registering Custom Event Listeners
  • 3.1 Manual Registration
  • 3.2 Auto-Registration (for Large Projects)
• 4. Writing Event Listener Classes
  • 4.1 Basic Listener Example
  • 4.2 Advanced Patterns
• 5. Integration With FXItems Behaviors
• 6. Common Use Cases
• 7. Troubleshooting & Tips
• 8. See Also

---

1. Overview

Custom events and behaviors allow you to add new functionality to your plugin or addon, react to in-game events, and extend FXItems in powerful ways.
FXItems lets you register Bukkit/Spigot event listeners and combine them with the FXItems behavior interfaces for complex logic.

---

2. What Are Custom Events and Behaviors?

• Custom Event Listeners: Java classes that implement Bukkit’s Listener interface and respond to Minecraft events (e.g., player movement, damage, crafting, etc.).
• Behaviors: FXItems-specific logic attached to items or foods, responding to FXItems hooks and events (see E | Advanced: Custom Effects in FXItems).

You can use both systems together for deep integration and advanced features.

---

3. Registering Custom Event Listeners

3.1 Manual Registration

Register listeners using the FXItems Registry API:

Registry registry = new RegistryAPI();
registry.registerEvent(
    this,                // Your plugin instance
    MyCustomListener.class // Your class (implements Listener)
);

• Place registration in your plugin's onEnable() or initialization code.
• Listeners are active for as long as your plugin is enabled.

3.2 Auto-Registration (for Large Projects)

If you have many listeners, you can use a reflection-based registrar to auto-register all classes implementing Listener in a given package.
This is similar to behavior auto-registration.

---

4. Writing Event Listener Classes

4.1 Basic Listener Example

public class PlayerJumpListener implements Listener {
    @EventHandler
    public void onPlayerJump(PlayerJumpEvent event) {
        Player player = event.getPlayer();
        player.sendMessage("§aYou jumped!");
        // You can run any FXItems API calls here, e.g. give custom items, trigger effects, etc.
    }
}

• Each method handling an event must be annotated with @EventHandler.
• You can listen to any Bukkit/Spigot event, including custom ones from other plugins.

4.2 Advanced Patterns

• Conditional Logic: Only run code for players holding a specific FXItem.

  @EventHandler
  public void onPlayerMove(PlayerMoveEvent event) {
      Player player = event.getPlayer();
      ItemStack held = player.getInventory().getItemInMainHand();
      if (CustomItemUtils.isCustomItem(held, "wind_boots")) {
          player.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 40, 1));
      }
  }

• Combining With Behaviors: Call methods on your FXItemBehavior from listeners for cross-feature logic.

---

5. Integration With FXItems Behaviors

• You can use event listeners to trigger FXItems abilities, apply cooldowns, modify mana, give/take items, and more.
• Use utility APIs (CooldownUtils, ManaUtils, etc.) inside your event handlers for full feature support.
• For passive effects (e.g., buffs while an item is in inventory), use onPassive in FXItemBehavior (see E | Advanced: Custom Effects in FXItems).

---

6. Common Use Cases

• Granting bonuses when players jump, sprint, or take damage while holding specific items.
• Blocking or customizing vanilla game events (e.g., preventing item drops, canceling teleportation).
• Creating new gameplay mechanics tied to FXItems (e.g., custom triggers, achievements, progression).
• Integrating with other plugins’ custom events.

---

7. Troubleshooting & Tips

• Nothing happens?
  • Ensure your class implements Listener and your methods use @EventHandler.
  • Confirm you registered your listener in onEnable() (or via auto-registration).
  • Check server logs for errors.
• Performance:
  • Keep event logic efficient—avoid heavy computation in common events like PlayerMoveEvent.
• Conflicts:
  • If you override vanilla behavior, test with other plugins for compatibility.

---

8. See Also

• B | The Registry System: Items, Foods, Commands, Events
• E | Advanced: Custom Effects in FXItems
• I | Utility: CustomItemUtils
• S | Auto-Registration System

---