BenthPinata is a comprehensive Spigot plugin that adds fun, rewarding, and fully customizable Piñata events to your Minecraft server. Designed for server owners, this plugin allows you to bring your community together to attack a common goal, compete for the top spot, and win amazing rewards. Breathe new life into your server with easy configuration and powerful features!

---

🤔 Why Choose BenthPinata?

• 🏆 High Performance: Built with modern coding practices and asynchronous operations to ensure the lowest possible impact on your server's performance.
• 🧩 Smart Dependency Handling: No rigid requirements! BenthPinata uses a smart hologram system. It prioritizes ProtocolLib for smooth, packet-based holograms. If not found, it falls back to DecentHolograms. If neither is available, the plugin runs perfectly without holograms, ensuring it never breaks your server.
• 🔧 Ultimate Flexibility: Create the event of your dreams by customizing nearly every setting across config.yml, rewards.yml, and abilities.yml.
• ✅ Active Development: A project that is consistently updated and values community feedback.

---

🚀 Core Features

• Unlimited Piñata Types: Create as many Piñata types as you want, each with different health, locations, and abilities.
  • Advanced Mob Support: Make your Piñata not just a sheep, but a Zombie, Horse, Llama, or even a fully custom entity using NBT tags!
• Advanced Ability System: Trigger special abilities as the Piñata's health drops, such as knocking back nearby players, blinding them, or applying negative potion effects.
• Comprehensive Reward Mechanics:
  • Per-Hit Rewards: Players can win small, chance-based rewards with every hit.
  • Damage Thresholds: Give guaranteed rewards to players who reach specific damage milestones.
  • Final Rewards: Honor the top damage dealers with incredible prizes when the event ends.
• Dynamic Visual Feedback:
  • Smart Hologram System: Displays the Piñata's health dynamically. It uses high-performance, packet-based holograms with ProtocolLib (recommended), falls back to DecentHolograms, or works without any hologram dependency.
  • Boss Bar: A built-in Boss Bar provides real-time health tracking for all nearby players.
  • Stunning Effects: Engaging particle and sound effects make the event feel alive.
• Automatic Event System:
  • Start events automatically at set intervals (e.g., every 2 hours).
  • Trigger an event when the server's player count reaches a certain threshold.
  • Schedule events for specific days and times (e.g., every Friday at 8:00 PM).
• Statistics & Leaderboards: Track players' total damage and Piñata kills. Use the /pinata stats top command to list the best players.
• PlaceholderAPI Support: Display plugin stats and leaderboards in other plugins like scoreboards, menus, and more.
• Easy Management: Manage events effortlessly with simple, permission-based commands.

---

✅ Supported Versions

This plugin is built on modern server APIs and has been tested for compatibility across a wide range of versions.

Minecraft Version	Support Status	Minecraft Version	Support Status
1.21.X	✅ Compatible	1.16.X	✅ Compatible
1.20.X	✅ Compatible	1.15.X	✅ Compatible
1.19.X	✅ Compatible	1.14.X	✅ Compatible
1.18.X	✅ Compatible	1.13.X	✅ Compatible
1.17.X	✅ Compatible	1.12.X & Older	❌ Incompatible

---

🔧 Installation

1. Download the Plugin: Grab the latest .jar file from the Releases page.
2. Install Dependencies (Optional but Recommended):
   • For the best experience (Packet Holograms): Install ProtocolLib.
   • For an alternative (Block-based Holograms): If you don't use ProtocolLib, you can install DecentHolograms.
   • For placeholder support: It is highly recommended to install PlaceholderAPI.
   • Reminder: The plugin works perfectly even if no hologram plugin is installed!
3. Upload Files: Place the downloaded BenthPinata.jar file (and any dependencies) into your server's plugins folder.
4. Start the Server: Start your server. The necessary configuration files (config.yml, messages.yml, etc.) will be automatically generated in the plugins/BenthPinata folder.
5. Configure: Edit config.yml to set your Piñata's spawn location and other settings. Use the /pinata reload command in-game to apply your changes.

---

💻 Commands and Permissions

Note: You can use /pinataevent or /pinyata as aliases for the main command /pinata.

Command	Description	Permission
/pinata help	Shows the help menu.	benthpinata.command.help
/pinata start <type> [location]	Starts a Piñata event of the specified type.	benthpinata.command.start
/pinata list	Lists all active Piñatas.	benthpinata.command.list
/pinata kill <id>	Kills the Piñata with the specified ID.	benthpinata.command.kill
/pinata killall	Kills all active Piñatas and stops all tasks.	benthpinata.command.killall
/pinata reload	Reloads the entire plugin configuration.	benthpinata.command.reload
/pinata stats	Shows your own Piñata statistics.	benthpinata.stats
/pinata stats top <damage|kills>	Lists the top players by damage or kills.	benthpinata.stats.top
/pinata stats reset <player|all>	Resets the stats for a player or for everyone.	benthpinata.stats.reset
(All Permissions)	Grants access to all of the commands above.	benthpinata.admin

---

⚙️ Configuration Files

The plugin stores all its settings in the plugins/BenthPinata/ directory.

• config.yml: Contains main settings like Piñata types, locations, health, effects, and the auto-event system.
• messages.yml: Contains all user-facing messages, titles, and hologram texts. Fully translatable.
• rewards.yml: Defines all reward commands and their chances for per-hit, damage-threshold, and final rewards.
• abilities.yml: Defines the special abilities for your Piñata types.
• stats.yml: The data file where player statistics are stored. It's not recommended to edit this file manually.

---

🛠️ Example Configuration

Here is a small snippet from config.yml to show its flexibility:

pinata-types:
  # A Zombie Piñata named 'dungeon' that glows and has no AI
  dungeon:
    spawn-location: 'world;15;70;25'
    health: 250
    entity-type: 'ZOMBIE'
    mob-options:
      is-baby: false
      glowing: true
      custom-name: '&4&lDUNGEON PIÑATA'
      custom-name-visible: true
      # This ensures the Piñata is silent and does not move.
      nbt-data: '{ "Silent": 1b, "NoAI": 1b }'

---

🧩 PlaceholderAPI Support

If PlaceholderAPI is installed on your server, you can use the following placeholders to display BenthPinata data in other plugins.

Player Statistics

• %bp_stats_damage% - Shows the player's total damage dealt to Piñatas.
• %bp_stats_kills% - Shows the player's total number of Piñata kills.

Leaderboards

• %bp_top_damage_<rank>_name% - Shows the name of the player at <rank> on the damage leaderboard (e.g., %bp_top_damage_1_name%).
• %bp_top_damage_<rank>_value% - Shows the damage value of the player at <rank>.
• %bp_top_kills_<rank>_name% - Shows the name of the player at <rank> on the kills leaderboard.
• %bp_top_kills_<rank>_value% - Shows the kill count of the player at <rank>.

---

💬 Support and Feedback

If you find a bug or have a feature suggestion, please open an issue on the GitHub Issues page.

---

📄 License

This project is licensed under the MIT License, which supports free and open-source software. Check the LICENSE file for more details.