⚔️ LonelyKOTH — The Ultimate King of the Hill Plugin

Developed by Lonely Studios
A high-performance, feature-packed King of the Hill (KOTH) plugin engineered for modern Paper & Spigot servers (1.20 – 1.21.x).

---

!Minecraft !Platform !Vault !PlaceholderAPI !License-red?style=for-the-badge)

---

🌟 Overview

LonelyKOTH redefines the King of the Hill experience on Minecraft servers. Designed from the ground up for modern Paper 1.20+ servers, it replaces legacy armor-stand holograms with high-performance 3D Display Entities (TextDisplay & ItemDisplay), provides full CustomModelData & NBT lossless reward serialization (perfect for PhoenixCrates, Oraxen, ItemsAdder, and custom key plugins), and offers effortless in-game region selection with a WorldEdit-style Selection Wand.

Whether you run a Factions, Lifesteal, Anarchy, Skyblock, or Towny server, LonelyKOTH delivers smooth, lag-free capture events with stunning visual effects and deep configuration options.

---

🔒 Terms & License Notice

• Owner & Developer: Lonely Studios
• License Type: All Rights Reserved / Proprietary Custom License
• Usage Rights: Free to download, install, and use on any Minecraft server.
• Restrictions: Reselling, redistributing, decompiling, claiming ownership, or modifying for commercial sale is strictly prohibited without prior written consent from Lonely Studios.

---

🔥 Key Features

💎 Modern 3D Display Entity Holograms

• Floating 3D Item Displays: Renders 3D rotating items (e.g. Netherite Sword, Gold Ingot, Custom Models) floating seamlessly above the capture hill.
• Vanilla Text Displays: Crisp text rendering with native text shadows, customizable background transparency, billboard modes (CENTER, HORIZONTAL, VERTICAL), and configurable height offsets.

🎒 Lossless Reward System (NBT & Custom Model Data)

• Base64 Serialized Rewards: Losslessly saves item NBT, CustomModelData, PDC (Persistent Data Container) tags, enchantments, and lore.
• PhoenixCrates & Key Support: Add custom crate keys directly from your inventory into KOTH rewards without losing key metadata!
• Overflow Protection: If a winner's inventory is full when claiming rewards, excess items are automatically dropped at their feet naturally.
• Command Rewards: Execute console commands upon capture (e.g. /eco give %player% 5000, /crate give %player% rare 1).

🪄 WorldEdit-Style Selection Wand

• Use /koth wand to obtain the official LonelyKOTH Selection Wand.
• Left-Click Block: Set Position 1.
• Right-Click Block: Set Position 2.
• Enforces strict validation: players cannot create a KOTH without first setting valid selection points!

✨ Hex RGB Particle Border Enclosures

• Animated particle perimeter surrounding the capture zone boundary.
• Supports RGB Hex colors (&#FF00E7), custom particle types (REDSTONE, FLAME, END_ROD, SPELL_WITCH, VILLAGER_HAPPY), size, spacing, and view distance.
• Active-Only Toggle: Configurable render-only-when-active: true setting ensures zero visual clutter or performance hit when events aren't running.

🖥️ In-Game Interactive GUI Editor

• /koth gui: Manage registered KOTH arenas, trigger manual starts/stops, teleport to arenas, and edit configurations directly in-game.
• /koth rewards <name>: View, add, and clear rewards visually through an interactive GUI.

📊 BossBar & Real-Time Countdown Timers

• Real-time BossBar tracking active captures, contestant interference (CONTESTED), and event countdowns.
• Configurable progress bar display ([████████░░] 80%) with toggleable enabled: true/false.

🔌 Economy & PlaceholderAPI Integration

• Vault Economy Support: Award money directly to capturing players.
• PlaceholderAPI Parsing: Parse any PAPI placeholder in broadcasts, BossBars, and holograms.

---

📜 Commands & Permissions

Command	Description	Permission
/koth help	Displays the interactive help menu	lonelykoth.use
/koth list	Lists all registered KOTH arenas	lonelykoth.use
/koth wand	Gives the WorldEdit-style Selection Wand	lonelykoth.admin
/koth pos1	Sets Position 1 at target block/location	lonelykoth.admin
/koth pos2	Sets Position 2 at target block/location	lonelykoth.admin
/koth setspawn <name>	Sets the spawn/teleport location for a KOTH	lonelykoth.admin
/koth create <name>	Creates a new KOTH arena from current selection	lonelykoth.admin
/koth delete <name>	Deletes an existing KOTH arena	lonelykoth.admin
/koth start <name>	Manually starts a KOTH capture event	lonelykoth.admin
/koth stop <name>	Stops an active KOTH capture event	lonelykoth.admin
/koth gui	Opens the main interactive KOTH Editor GUI	lonelykoth.admin
/koth rewards <name>	Opens the Reward Management GUI for a KOTH	lonelykoth.admin
/koth addinv <name>	Adds all items in inventory to KOTH rewards	lonelykoth.admin
/koth addcmd <name> <cmd>	Adds a console command reward	lonelykoth.admin
/koth clearrewards <name>	Clears all rewards for a KOTH arena	lonelykoth.admin
/koth reload	Reloads config.yml and messages.yml live	lonelykoth.admin

---

🧩 Placeholders

LonelyKOTH supports internal & PlaceholderAPI placeholders:

Placeholder	Description	Example Output
%koth% / %koth_name%	Name of the active KOTH arena	Nether
%capper% / %player%	Current capturing player's name	Notch
%time%	Remaining capture or countdown time (mm:ss)	00:30
%seconds%	Remaining capture time in raw seconds	30
%percentage%	Capture progress percentage	80
%bar%	Visual progress bar	████████░░
%status%	Current status of the KOTH arena	Active / Idle

---

⚙️ Configuration File (config.yml)

# ==============================================================================
#                            LONELYKOTH
#                         by Lonely Studios
# ==============================================================================

# Branding Prefix (Hex Color Format: &#RRGGBB)
prefix: "&#FF00E7&lL&#E109E1&lo&#C312DA&ln&#A61BD4&le&#8824CD&ll&#7524D0&ly&#6E1BDC&lK&#6712E7&lO&#6009F3&lT&#5900ff&lH &7>> "

settings:
  check-updates: true
  debug-mode: false
  allow-simultaneous-koths: false

# WorldEdit-style Selection Wand Configuration
selection-wand:
  item: "GOLDEN_AXE"
  name: "&#A855F7✦ KOTH Selection Wand ✦"
  lore:
    - "&#94A3B8Left-Click Block: &#EC4899Set Position 1"
    - "&#94A3B8Right-Click Block: &#EC4899Set Position 2"
    - ""
    - "&#A855F7Lonely Studios — Region Tool"

# 3D Display Entity Holograms (TextDisplay & ItemDisplay above hill)
holograms:
  enabled: true
  height-offset: 2.5
  item-height-offset: 1.8
  item-material: "NETHERITE_SWORD"
  text-shadow: true
  see-through: false
  default-background: false
  billboard: "CENTER"
  update-interval-ticks: 5
  lines:
    - "&#A855F7✦ KING OF THE HILL ✦"
    - "&#94A3B8Arena: &#EC4899%koth%"
    - "&#94A3B8King: &#22C55E%capper%"
    - "&#94A3B8Progress: &#FBBF24[%bar%] %percentage%%"
    - "&#94A3B8Time Remaining: &#38BDF8%time%"

# Progress Bar Styling
progress-bar:
  enabled: true
  total-blocks: 10
  completed-symbol: "█"
  remaining-symbol: "░"
  completed-color: "&#22C55E"
  remaining-color: "&#94A3B8"

# Particle Border Effects around Capture Zone
particles:
  enabled: true
  type: "REDSTONE" # Supported: REDSTONE, FLAME, END_ROD, SPELL_WITCH, VILLAGER_HAPPY
  density: 0.5
  update-interval-ticks: 10
  render-only-when-active: true

# Default Capture Time (seconds)
defaults:
  capture-time-seconds: 30
  active-time-seconds: 600
  start-countdown-seconds: 10
  reset-on-leave: true

---

📦 Installation & Quick Start

1. Download: Place LonelyKOTH.jar into your server's /plugins/ directory.
2. Dependencies (Optional): Install Vault for economy support and PlaceholderAPI for external placeholders.
3. Start Server: Boot your server to generate configuration files.
4. Create Arena:
   • Execute /koth wand to obtain the selection tool.
   • Left-click corner 1, right-click corner 2.
   • Run /koth create <arena_name>.
   • Stand where players should spawn/teleport and execute /koth setspawn <arena_name>.
5. Set Rewards:
   • Put rewards in your inventory and run /koth addinv <arena_name> or use the /koth rewards <arena_name> GUI.
   • Add command rewards via /koth addcmd <arena_name> eco give %player% 1000.
6. Start Event: Run /koth start <arena_name>!

---

💬 Community & Support

This is my very first plugin that I've released! Please do report bugs and ask questions in the Discord.