Skip to content

E | Advanced: Custom Effects in FXItems

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

E | Advanced: Custom Effects in FXItems

Table of Contents

1. Overview

Beyond simple item/food stats, FXItems supports powerful custom effects and active abilities for both items and foods. This is achieved with behavior interfaces (FXItemBehavior, FXFoodBehavior), utility APIs, and integration with Minecraft’s event system.

2. Understanding FXItemBehavior and FXFoodBehavior

  • FXItemBehavior: Attach custom logic to any item (e.g., right/left click, on attack, on passive, on drop, etc.)
  • FXFoodBehavior: Attach custom logic to foods (e.g., onEat, onConsume, etc.)

You can implement as many or as few hooks as you want; unimplemented methods are simply ignored.

3. Supported Effect Hooks and Event Triggers

3.1 FXItemBehavior Hooks

These are the most common, but always check your FXItems version for new/extended hooks!

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) {}
    default void onHeld(Player player, ItemStack item) {}
    default void onDrop(Player player, ItemStack item) {}
    default void onInventoryTick(Player player, ItemStack item) {}
    // ...extend as the API grows!
}

Common use cases:

  • onRightClick: Fire projectiles, cast spells, activate abilities.
  • onAttack: Modify outgoing damage, apply custom effects, trigger crits.
  • onPassive/onHeld/onInventoryTick: Grant buffs while held or in inventory.
  • onDrop: Prevent or customize item dropping behavior.

3.2 FXFoodBehavior Hooks

public interface FXFoodBehavior {
    default void onEat(Player player, ItemStack food, FXFoodDefinition def) {}
    // Additional: onConsume, onHeld, etc. if your version supports
}
  • onEat: Apply potion effects, heal, teleport, run commands, summon mobs, etc.

4. Using EffectUtils and Utility APIs

FXItems comes with a suite of utility classes to make advanced effects easy.

  • EffectUtils: Apply potion effects, particles, sounds, and more.
    • EffectUtils.applyPotionEffect(Player, PotionEffectType, duration, level, showParticles)
    • EffectUtils.spawnParticles(World, Particle, Location, count, ...)
    • EffectUtils.playSound(Player, Sound, volume, pitch)
  • CooldownUtils: Manage per-player cooldowns for abilities.
    • CooldownUtils.isOnCooldown(Player, "key")
    • CooldownUtils.setCooldown(Player, "key", ticks)
  • ManaUtils: Get, set, and modify custom mana for players.
    • ManaUtils.getMana(Player)
    • ManaUtils.setMana(Player, value)
    • ManaUtils.addMana(Player, value)
  • ProjectileUtils: Spawn custom projectiles with callbacks.
    • ProjectileUtils.spawnProjectile(EntityType, Location, Vector, Consumer<Projectile>)
  • TeleportUtils, OneTimeCraftUtils, etc.: See utility wiki pages for full API.

5. Creating Complex Abilities: Examples

5.1 Cooldowns

@Override
public void onRightClick(Player player, ItemStack item, Block block, Action action) {
    if (CooldownUtils.isOnCooldown(player, "beamsword")) {
        player.sendMessage("§cStill recharging!");
        return;
    }
    // Do ability...
    CooldownUtils.setCooldown(player, "beamsword", 40); // 2 seconds (20 ticks = 1 sec)
}

5.2 Mana Consumption

@Override
public void onRightClick(Player player, ItemStack item, Block block, Action action) {
    ManaUtils mana = new ManaUtilsAPI();
    if (mana.getMana(player) < 50) {
        player.sendMessage("§bNot enough mana!");
        return;
    }
    mana.addMana(player, -50);
    // Ability effect...
}

5.3 Custom Projectiles

@Override
public void onRightClick(Player player, ItemStack item, Block block, Action action) {
    Location loc = player.getEyeLocation();
    Vector direction = loc.getDirection().multiply(2.0);
    ProjectileUtils.spawnProjectile(EntityType.SNOWBALL, loc, direction, projectile -> {
        projectile.setCustomName("Beam");
        // Add trail, on-hit effect, etc.
    });
}

5.4 Multi-Stage Effects

@Override
public void onAttack(EntityDamageByEntityEvent event, Player player, ItemStack item) {
    event.setDamage(event.getDamage() * 2);
    player.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 60, 1));
    player.getWorld().spawnParticle(Particle.CRIT, player.getLocation(), 20);
    player.playSound(player.getLocation(), Sound.ENTITY_PLAYER_ATTACK_CRIT, 1, 1);
}

6. Integration with Bukkit/Spigot Events

  • You can combine FXItems hooks with any Bukkit event for ultra-complex logic.
  • Register your own listeners using the Registry API: 
    registry.registerEvent(this, MyCustomListener.class);
  • Many advanced items use a mix of FXItemBehavior and event listeners.

7. Persistent Data, NBT, and Advanced State

  • For persistent state (e.g., item-bound cooldowns, custom tags), use Bukkit's PersistentDataContainer.
  • You may read/write custom NBT on ItemStack in your FXItemBehavior methods: 
    ItemMeta meta = item.getItemMeta();
NamespacedKey key = new NamespacedKey("yourplugin", "yourtag");
meta.getPersistentDataContainer().set(key, PersistentDataType.INTEGER, 1337);
item.setItemMeta(meta);
  • This enables per-item or per-player custom data.

8. Troubleshooting & Gotchas

  • Unregistered behaviors:
    • If your item/food isn't triggering effects, check registration and class annotations.
  • Server performance:
    • Avoid intensive logic in onPassive/onInventoryTick—these run frequently!
  • Effect stacking:
    • Be careful with infinite duration potion effects; use short bursts and reapply if needed.
  • Compatibility:
    • Some hooks may require specific server versions (e.g., certain events in newer MC).

9. See Also

FXItems Wiki

Clone this wiki locally