K | Utility: ManaUtils

K | Utility: ManaUtils

---

Table of Contents

• 1. Overview
• 2. What is ManaUtils?
• 3. Basic Usage
• 4. API Reference
• 5. Advanced Patterns
• 6. Troubleshooting & Notes
• 7. See Also

---

1. Overview

ManaUtils is a utility in FXItems for handling custom player mana systems—perfect for magical items, abilities, skills, and more.
It gives you a simple API for getting, setting, modifying, and checking mana.

---

2. What is ManaUtils?

A toolkit for:

• Tracking per-player mana as an integer.
• Integrating mana costs into custom items, foods, or commands.
• Reading and modifying mana in any plugin that supports FXItems API.

Mana is stored persistently (usually via Bukkit's persistent data containers), so it survives server restarts and stays with the player.

---

3. Basic Usage

Example: Mana Cost on Item Use

ManaUtils mana = new ManaUtilsAPI();
if (mana.getMana(player) < 20) {
    player.sendMessage("§bNot enough mana!");
    return;
}
mana.addMana(player, -20); // Spend 20 mana
// Activate ability here...

---

4. API Reference

Methods

// Get current mana (returns int, default 0 if not set)
int ManaUtils.getMana(Player player);

// Set current mana (overwrites existing)
void ManaUtils.setMana(Player player, int value);

// Add/subtract mana (negative for cost, positive for restore)
void ManaUtils.addMana(Player player, int delta);

// Get maximum mana (default 100, can be customized in configs or via API)
int ManaUtils.getMaxMana(Player player);

// Set maximum mana
void ManaUtils.setMaxMana(Player player, int value);

// Restore mana to maximum
void ManaUtils.restoreMana(Player player);

// Check if player has at least N mana
boolean ManaUtils.hasMana(Player player, int amount);

// Get mana as percent (double between 0.0 and 1.0)
double ManaUtils.getManaPercent(Player player);

---

5. Advanced Patterns

Dynamic Max Mana

• You can grant bonus max mana based on permissions, items, or events:

  ManaUtils.setMaxMana(player, 200); // Double the default max!

Restore on Event

• Restore all mana on respawn, level up, or custom triggers:

  @EventHandler
  public void onPlayerRespawn(PlayerRespawnEvent event) {
      ManaUtils.restoreMana(event.getPlayer());
  }

Action Bar Mana Display

• Use the action bar to show mana after using an ability:

  EffectUtils.sendActionBar(player, "§9Mana: " + ManaUtils.getMana(player) + "/" + ManaUtils.getMaxMana(player));

Mana Regeneration

• Schedule a repeating task to regenerate mana:

  Bukkit.getScheduler().runTaskTimer(plugin, () -> {
      for (Player player : Bukkit.getOnlinePlayers()) {
          ManaUtils.addMana(player, 1); // +1 mana per tick or per period
      }
  }, 0, 20L); // every second

---

6. Troubleshooting & Notes

• Mana not updating?
  • Make sure you are modifying mana on the main thread (Bukkit API requirement).
  • Check if other plugins are resetting or conflicting with persistent data.
• Max Mana stuck at 100?
  • Use setMaxMana or update plugin configs if supported.
• Mana bar not visible?
  • You must implement your own visual feedback (actionbar, bossbar, etc.).

---

7. See Also

• E | Advanced: Custom Effects in FXItems
• H | Utility: CooldownUtils
• J | Utility: EffectUtils

---