Holy Grail

========================================

           HOLY GRAIL

   The Ultimate Capture & Hold Plugin

========================================

Transform your Rust server with an exciting capture-and-hold gameplay experience! The Holy Grail plugin introduces a legendary item that players must find, capture, and protect to earn rewards and eternal glory.

========================================

              OVERVIEW

========================================

Holy Grail spawns a unique, trackable item somewhere in your server's world. Players compete to find, capture, and hold onto the Grail. Whoever is holding the Grail when the wipe ends weather it's in there inventory or a player owned storage container is crowned the winner and receives configurable rewards along with their team if enabled the next time they log in after wipe!

========================================

             FEATURES

========================================

GRAIL SPAWNING & TRACKING

--------------------------

• Spawns in configurable loot containers across the map
• Automatic respawning if the Grail is lost or destroyed
• Tracks Grail location through player inventories, storage containers, vending machines, dropped items, and corpses
• Persistent tracking across server restarts

HOLD TIME & STATISTICS

--------------------------

• Tracks how long each player holds the Grail
• Time accumulates while Grail is in player inventory OR their owned containers
• Leaderboard system ranks players by total hold time
• Stats tracking for captures and hold time
• Wipe winner (current holder) automatically announced when server wipes

HOLDER EFFECTS

--------------------------

• Configurable visual glow effects on the Grail holder
• Health regeneration OR corruption (drain) while holding
• Calorie and hydration effects (boost or drain)
• Blessing/Corruption notifications to the holder
• All effects fully configurable or can be disabled

PROXIMITY DETECTION

--------------------------

• Visual and audio effects play when players approach the Grail
• Configurable detection radius
• Notification messages when players get close
• Option to hide effects when Grail is in player-owned storage

STEALING & ALERTS

--------------------------

• Alert the previous holder when their Grail is stolen
• Configurable alert radius
• Option to show or hide the thief's name
• Server-wide announcements for Grail pickups drops and steals if enabled

TEAM INTEGRATION

--------------------------

• Announce to team members when a teammate picks up the Grail
• Team-aware notifications and tracking

BOUNTY SYSTEM

--------------------------

• Bounty accumulates the longer a player holds the Grail
• Base bounty plus bonus per minute held
• Creates high-stakes gameplay and encourages PvP

MAP INTEGRATION

--------------------------

• Optional map markers showing Grail location
• Configurable marker visibility and updates
• Grid position announcements

DISCORD INTEGRATION

--------------------------

• Rich embed messages to your Discord server
• Leaderboard posts showing top holders
• Winner announcements with player stats
• Customizable webhook integration

ADMIN FEATURES

--------------------------

• Full in-game configuration UI
• Spawn settings management
• Valid container/prefab configuration
• Player statistics viewing
• Manual Grail spawning and respawning
• Kit reward configuration

REWARD SYSTEM

--------------------------

• Configure kit rewards for the wipe winner
• Custom item rewards
• Integrates with popular kit plugins

========================================

         HOW IT WORKS

========================================

1. SPAWN

   The Holy Grail spawns in a random valid container somewhere in the world (barrels, crates, etc.)

2. DISCOVERY

   Players searching loot containers may find the Grail. Proximity effects help guide nearby players.

3. CAPTURE

   When a player picks up the Grail, their hold time begins tracking. Server announcements alert everyone if enabled.

4. PROTECT

   The holder must protect the Grail from other players. They receive holder effects (buffs or debuffs based on config).

5. COMPETE

   Players can store the Grail in their base containers - time still accumulates for the container owner.

6. WIN

   At wipe end, whoever is currently holding the Grail wins and receives configured rewards the next time they log in after wipe!

========================================

           BENEFITS

========================================

INCREASED PLAYER ENGAGEMENT

• Gives players a persistent objective beyond normal gameplay
• Creates organic PvP encounters and raid incentives
• Encourages exploration and looting

EXTENDED PLAY SESSIONS

• Players stay online longer to protect their Grail
• Competition drives continued engagement throughout the wipe

COMMUNITY BUILDING

• Leaderboards create friendly competition
• Discord integration keeps players engaged even offline
• Winner announcements celebrate top players

SERVER DIFFERENTIATION

• Unique gameplay mechanic sets your server apart
• Fully configurable to match your server's style

EASY ADMINISTRATION

• No complex setup required
• In-game UI for all configuration
• Automatic tracking and announcements
• No performance impact

PERFECT FOR PVE SERVERS WITH PURGE

• Adds exciting end-of-wipe objective for PvE communities
• Encourages players to participate in purge events
• Creates a race to find and secure the Grail before wipe
• Gives PvE players a competitive goal without constant PvP
• The hunt for the Grail drives exploration during purge
• Rewards the player who successfully holds the Grail through the chaos
• Perfect finale event to end your wipe on a high note

========================================

        CONFIGURATION

========================================

Everything is configurable including:

• Grail item appearance and name
• Spawn locations and valid containers
• All holder effects (enable/disable, amounts, intervals)
• Proximity effect settings
• Stealing alert settings
• Discord webhook and message formats
• Reward kits and items
• Map marker settings
• Announcement messages
• And much more!

========================================

         PERMISSIONS

========================================

• holygrail.admin - Access to admin UI and commands

========================================

           COMMANDS

========================================

Player Commands (configurable):

• /hgstats - View your personal Grail statistics
• /hgleaderboard - View the hold time leaderboard

Admin Commands:

• /hgadmin - Open the admin configuration panel
• /findgrail - Locate the Grail's current position

========================================

      PLUGIN INTEGRATIONS

========================================

ULTIMATE LEADERBOARD

--------------------------

Track Holy Grail stats directly in Ultimate Leaderboard! Display grail captures and hold time on your server's leaderboards.

Setup Instructions:

1. Install Ultimate Leaderboard plugin

2. Open Holy Grail config or use /hgadmin

3. Navigate to Leaderboard settings

4. Enable "Ultimate Leaderboard Integration"

5. Enable "Track Grail Captures" and/or "Track Hold Time"

6. Set your event names (e.g., "GrailCapture", "GrailHoldTime")

7. In Ultimate Leaderboard config, add matching event names:

• Add "GrailCapture" event for capture tracking
• Add "GrailHoldTime" event for hold time (tracked in minutes)

8. Reload both plugins

Stats Tracked:

• Grail Captures: +1 each time a player picks up the grail
• Hold Time: Accumulated minutes holding the grail

NOTIFY PLUGIN

--------------------------

Integrate with Notify for beautiful on-screen notifications instead of chat messages.

Setup Instructions:

1. Install Notify plugin

2. Open Holy Grail config or use /hgadmin

3. Enable "Use Notify Plugin"

4. Set your preferred Notify Type (0-7 depending on Notify config)

5. All Holy Grail messages will now use Notify's display system

KITS PLUGIN

--------------------------

Reward winners with kits from the Kits plugin.

Setup Instructions:

1. Install Kits plugin and create your reward kits

2. Open /hgadmin and go to Reward Settings

3. Click "Add Kit Reward"

4. Enter the exact kit name from your Kits plugin

5. Winner will automatically receive the kit when wipe ends

CLANS PLUGIN

--------------------------

Integrate with Clans for team-based features with your clan members.

Setup Instructions:

1. Install Clans plugin

2. Open Holy Grail config or use /hgadmin

3. Navigate to Team settings

4. Enable "Use Clans Plugin"

5. Clan members will now be treated as teammates

Features When Enabled:

• Clan members notified when a clanmate picks up the grail
• Friendly fire prevention between clan members
• Clan-aware team announcements

FRIENDS PLUGIN

--------------------------

Integrate with Friends for team-based features with your friends list.

Setup Instructions:

1. Install Friends plugin

2. Open Holy Grail config or use /hgadmin

3. Navigate to Team settings

4. Enable "Use Friends Plugin"

5. Friends will now be treated as teammates

Features When Enabled:

• Friends notified when a friend picks up the grail
• Friendly fire prevention between friends
• Friend-aware team announcements

Note: You can enable both Clans AND Friends plugins together for maximum team coverage!

========================================

         DEPENDENCIES

========================================

Required:

• None! Holy Grail works standalone

Optional Integrations:

• Ultimate Leaderboard (for stat tracking on leaderboards)
• Notify (for on-screen notifications)
• Kits (for kit rewards)
• Clans (for clan-based team features)
• Friends (for friends-based team features)
• Discord Webhook (for Discord announcements)

========================================

Transform your server's gameplay with Holy Grail - where legends are made and glory awaits!