🎁 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 - PlaceholderAPI

⚙️ Configuration

Main settings in config.yml:

# 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 [radius] - Find event items within radius
/presentshunt cleanup [radius] - Remove event items within radius
/presentshunt resetplayer <player> - Reset player data
/presentshunt resetall - Reset all player data
/presentshunt setmode [mode] - Set a new event mode
/presentshunt replace [mode] [radius] - 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