PresentsHunt

# 🎁 PresentsHunt - Gift Hunt A plugin that adds an exciting gift hunt with different themed modes. Players search for hidden gift heads throughout the world and receive rewards for collecting them. ## 🧩 Version Compatibility | **Plugin version** | **Supported Paper** | **Java** | |--------------------|-----------------------|----------| | `1.3.0` | `1.20.1` – `26.2` | 25 | | `1.2.1` | `1.20.1` – `1.21.11` | 21 | ## ✨ Features - 🎄 **Themed Modes**: Christmas, Halloween, Easter, and custom mode - 🏆 **Achievement System**: Players collect event items to earn rewards - 📊 **Leaderboard**: Player rankings with PlaceholderAPI integration - 🎯 **Administrative Tools**: Easy management and cleanup of event items (no need to remember exact locations) - 🔊 **Effects**: Particles and sounds when interacting with event items - 📝 **Configurable Messages**: Support for MiniMessage format - 🔧 **API Integration**: PlaceholderAPI support for integration with other plugins ## ✨ Dependencies **Optional** - (https://modrinth.com/plugin/placeholderapi) ## ⚙️ Configuration Main settings in `config.yml`: ```yaml # Mode Selection (HALLOWEEN, CHRISTMAS, EASTER, CUSTOM) presentsMode: CHRISTMAS # How many event items need to be found to get a reward totalPresents: 30 # Commands for each found event item and when a player finds all # In these commands, you can use the variables %player%, %found%, and %total%. commands: foundCommands: rewardCommands: - "give %player% diamond 10" leaderboard: maxPlayersCount: 100 # How many players will be stored in the leaderboard to display the position in the top # Music when interacting with the head sounds: found: "block.pumpkin.carve" alreadyFound: "entity.zombie.ambient" complete: "entity.firework_rocket.blast" # Effects when interacting with the head particles: found: "SWEEP_ATTACK" alreadyFound: "SQUID_INK" ``` ### Head Textures Pre-configured textures available for each mode: - **CHRISTMAS**: New Year gift - **HALLOWEEN**: Halloween pumpkin - **EASTER**: Easter egg - **CUSTOM**: Custom head (configure your own texture) ## 🎮 Usage ### For Players 1. Find hidden event item heads in the world 2. Right-click the event item to collect it 3. Collect event items to earn rewards 4. Use `/presentshunt stats` to view statistics ### For Administrators ``` /presentshunt give - Get a head (event item) /presentshunt stats - Show plugin statistics /presentshunt reload - Reload configuration /presentshunt locate - Find event items within radius /presentshunt cleanup - Remove event items within radius /presentshunt resetplayer <player> - Reset player data /presentshunt resetall - Reset all player data /presentshunt setmode - Set a new event mode /presentshunt replace - Replace all items of the selected event with the current one in the radius ``` ### Placing Gifts 1. Get a head with `/presentshunt give` command 2. Place the head anywhere in the world 3. The head is automatically marked as a collectible event item ## 📊 PlaceholderAPI The plugin supports PlaceholderAPI with the following placeholders: ``` %presentshunt_found% - Number of found event items %presentshunt_total% - Total number of event items %presentshunt_mode% - Current hunt mode %presentshunt_completed% - Number of players who completed the hunt %presentshunt_players% - Number of players with data %presentshunt_position% - Ranking position %presentshunt_status% - Completion status (Completed/In Progress/Not Started) %presentshunt_top_1_status% - Status of player in 1st place %presentshunt_top_2_status% - Status of player in 2nd place ... and so on up to 10th place ``` ## 🔧 Permissions ``` presentshunt.use - Collecting Event Items (default: true) presentshunt.admin - Administrative commands (default: op) ``` ## 📥 Installation ### Installation Steps 1. Download the latest version 2. Place the `PresentsHunt.jar` file in the `plugins/` folder 3. Restart the server 4. Configure the configuration file `plugins/PresentsHunt/config.yml` and apply changes with the `/presentshunt reload` command 5. Use the `/presentshunt give` command to get a event head