KothCL

KothCL is a high-performance, modern, and fully modular King of the Hill (KOTH) plugin for Paper 1.21.1+ servers running Java 21.

---

✨ Features

• Triple Game Modes: Choose between SCORE (points per second), CAPTURE (uninterrupted control time), and LOS (Last One Standing - winner holds the hill at the final second).

• In-Game Visual GUI (/koth gui): Easily manage arenas, set up rewards, toggle game modes with an interactive clock icon, and tweak configurations on the fly.

• Triple Reward System:

• Item Chest: Physical items saved with NBT, lore, custom names, and enchantments.

• Vault Economy: Direct money rewards configured interactively via GUI/chat (gold ingot).

• Command Chains: Sequential console commands executed automatically upon capture (paper).

• Discord Webhook Integration: Send real-time alerts directly to your Discord server when a KOTH starts, stops, gets captured, enters a contested state, or provide live progress updates during captures (configurable via config.yml).

• Independent Per-KOTH Files: Every arena is saved in its own file under koths/ with custom names, prefixes, durations, score targets, and contested policies.

• Advanced Schedulers: Automatic event activation supporting TIME (daily execution based on time zones like America/Santiago), COUNTDOWN (interval in minutes), or OFF (manual start).

• Multi-Language Support: Fully customizable messages, BossBars, Scoreboards, and command usages supporting lan/en.yml and lan/es.yml.

• Asynchronous & Zero-Lag: SQLite statistics, disk saves, and Discord webhooks run strictly off the main thread with spatial bounding-box checks.

---

💻 Commands & Permissions

Player Commands (/koth, /kothcl)

• /koth list (kothcl.list) - View all available KOTH arenas and their status.
• /koth stats [player] (kothcl.stats) - View victories, win streaks, and control times.

Admin Commands

(Requires OP, kothcl.op, or kothcl.admin)

Command	Permission	Description
/koth / /koth gui	kothcl.admin	Open GUI menu (shows command list if no Koth exists).
/koth help	kothcl.admin	List all available commands.
/koth wand	kothcl.admin	Receive selection wand (Left-click: Pos 1, Right-click: Pos 2).
/koth create <name> [mode]	kothcl.admin	Create arena via WorldEdit/wand (SCORE, CAPTURE, LOS).
/koth delete <name>	kothcl.admin	Delete an arena and its file completely.
/koth start <name>	kothcl.admin	Manually start a KOTH event.
/koth stop <name>	kothcl.admin	Forcefully stop an active KOTH event.
/koth reload	kothcl.admin	Reload configs, languages, and arenas safely.
/koth set <name> <key> <val>	kothcl.admin	Modify any Koth setting directly.
/koth activator <name>	kothcl.activator.use	Receive the KOTH activation item.

---

⚙️ Configuration & Koth Settings (/koth set)

Every Koth in koths/<name>.yml supports independent configuration keys:

• prefix: Text with color codes (& or hex &#RRGGBB), max 48 chars.
• mode: SCORE, CAPTURE, or LOS (Last One Standing).
• capture-time: Seconds required to capture (CAPTURE).
• score-target: Points required to win instantly (SCORE).
• points: Points awarded per second.
• time-limit-seconds: Time limit in seconds (0 = no limit; LOS defaults to 300).
• contested: Policy when contested (FREEZE or PENALIZE).
• penalty: Points subtracted per second during disputes.
• reset-on-leave: true / false (resets progress if capturer leaves in CAPTURE).
• schedule: Automation mode (OFF, TIME, or COUNTDOWN).
• schedule-time: Daily execution time (HH:mm for TIME).
• schedule-countdown: Interval in minutes (max 10080 for COUNTDOWN).
• schedule-announce: Pre-start warning minutes (e.g., 5,1 or none).
• enabled, bossbar, scoreboard, broadcast, discord: true / false.
• command-delay: Ticks delay between reward command executions.
• activator-material, activator-consume, activator-cooldown: Activator item setup.

Main config.yml Highlights

• lan: Language selection (en, es, or custom lan/<code.yml>).
• **time.zone & time.format**: Timezone and date pattern formatting.
• wand.material: Item material for the selection wand.
• gui.chat-input-timeout-seconds: Timeout duration for GUI chat inputs.
• stats.top-size: Leaderboard display size limit.
• discord: Webhook URL, username, avatar URL, contested cooldown, and event toggles (start, stop, capture, contested, progress with interval settings).
• defaults: Default settings template applied to newly created Koths.

---

🔌 PlaceholderAPI Placeholders (%kothcl_...%)

[!NOTE] Make sure PlaceholderAPI is installed to use these placeholders in TAB, Scoreboards, or holograms.

• Player: %kothcl_wins%, %kothcl_streak%, %kothcl_best_streak%, %kothcl_control_time%, %kothcl_name%
• Leaderboards: %kothcl_top_<n>_name%, %kothcl_top_<n>_wins%, %kothcl_top_<n>_streak%
• Globals: %kothcl_active_count%
• Per-Koth & Schedulers:
• %kothcl_status_<koth>% — Current status of the arena.
• %kothcl_controller_<koth>% — Current player holding the hill.
• %kothcl_time_<koth>% — Remaining time.
• %kothcl_players_<koth>% — Count of players inside the arena.
• %kothcl_countdown_<koth>% — Time left until the next scheduled start (e.g., 1h 20m or 12m 30s).
• %kothcl_starttime_<koth>% — Exact time of the next automatic start in HH:mm format.

---

🌐 Language Files (lan/*.yml)

All texts, UI elements, BossBars, Scoreboards, capture progress alerts, and console logs are fully customizable via lan/en.yml and lan/es.yml using dynamic variables wrapped in curly braces (e.g., {prefix}, {arena}, {player}, {time}, {score}, {target}). Standard Minecraft color codes (&7, &5) and Hex (&#RRGGBB) are fully supported in-game.

---

📥 Requirements & Installation

• Server Software: Paper / Purpur / Folia (1.21.1 or higher)
• Java Version: Java 21+
• Dependencies: WorldEdit/FAWE, Vault, PlaceholderAPI.

1. Download KothCL-1.0.3.jar and place it in your server's plugins/ folder.
2. Restart your server.
3. Set your preferred language (lan: en or lan: es) and timezone in plugins/KothCL/config.yml.