VelKoth

A modern, high-performance King of the Hill (KoTH) plugin built for PaperMC 1.21+ utilizing Java 21 features.

VelKoth supports multiple capture modes (CAPTURE and SCORE), O(1) mathematical region boundary checks for supreme performance, an automated integrated scheduler, and a robust configurable database-backed reward and statistics system.

🚀 Features

• Modern Architecture: Compiled against Paper 1.21+ using Java 21, Folia-supported Regional/Entity Schedulers, and the Incendo Cloud V2 native Brigadier command framework.
• Multiple Capture Modes:
  • CAPTURE: Traditional KoTH where one player must hold the hill uninterrupted for the duration.
  • SCORE: Point-based KoTH where players accumulate capture seconds until they reach the target score.
• High Performance Regions: Both Cuboid and Cylinder regions utilise O(1) containment algorithms removing loop-based block checks for zero server TPS impact.
• Team Plugin Integrations: Fully supports team and faction capturing! Players in the same team, faction, or party can capture hills together without contesting. Supports 12+ plugins natively.
• Advanced Display Visuals: Leverages modern Paper Adventure API to push ActionBars, custom BossBars, on-screen Titles, Particle effects, and Sounds. Includes FastBoard-powered Scoreboards (with smart-overrides for plugins like TAB and SimpleScore) and native Paper TextDisplay Holograms that are fully chunk-safe.
• Robust Storage System: Fully asynchronous SQLite/MySQL HikariCP connection pooling storing player total wins, daily wins, and weekly wins.
• bStats Metrics Integration: Uses anonymous metrics tracking to keep developers informed on adoption rates and usage.
• Scheduler Integration: Define exactly when specific arenas should run via Cron-like syntax or simple time formats. Now supports Dynamic Scheduling via in-game commands.
• Dynamic Configuration: Built on Okaeri Configs for instant YAML hot-reloading. Every system message, GUI layout, and internal setting can be modified.
• Comprehensive Rewards: Execute commands, distribute ItemStacks (with overflow drop handling), or give Vault Economy money to the winners.
• Enhanced PlaceholderAPI: Comprehensive support for multi-arena events, absolute/specific next event countdowns, and human-readable time formatting.
• Developer API: Features a full suite of Bukkit Events (KothStartEvent, KothWinEvent, KothCaptureStartEvent, etc.) and a static VelKothAPI state accessor for developers.

⚙️ Dependencies

• PaperMC 1.21.x+
• Java 21
• Vault (Optional - Required for Economy rewards)
• PlaceholderAPI (Optional - Exposes extensive placeholders)
  • %koth_arena[_<id>]%, %koth_time[_formatted][_<id>]%
  • %koth_owner[_<id>]%, %koth_players[_<id>]%
  • %koth_next_arena[_<id>]%, %koth_next_time[_formatted][_<id>]%
• Supported Team Plugins (Optional - Allows team members to capture together)
  • BetterTeams, Factions (UUID/Saber), GangsPlus, Guilds, KingdomsX
  • SuperiorSkyblock2, Towny Advanced, UltimateClans, Parties, AxParties
  • LandClaimPlugin (Custom hook)

🛠️ Usage & Setup

Creating an Arena

1. Grab the KoTH Wand by typing /koth wand.
2. Left-Click one corner of your hill, and Right-Click the opposite corner.
3. Type /koth create <arenaName> to save the region.
4. Modify specific rules, timers, and rewards for this arena in the generated plugins/VelKoth/arenas.yml configuration!

Administering Events

• Start an event manually: /koth start <arenaName>
• Pause an ongoing event (maintaining times/scores): /koth pause <arenaName>
• Stop an event completely: /koth stop <arenaName>
• Configure automatic daily/weekly events in plugins/VelKoth/config.yml.

🪧 Commands

VelKoth features a robust, auto-completing Brigadier command hierarchy.

🎁 Rewards

VelKoth supports a powerful reward system that can be managed entirely in-game or via arenas.yml. Rewards are granted to the winning player (or all online members of a team/faction if team hooks are active).

Supported Reward Types

Reward Placeholders

• %player%: Name of the winner.
• %arena%: ID of the arena.

Viewing Rewards

You can see exactly what rewards are configured for an arena using: /koth reward list <arena> This will display a numbered list of rewards with human-readable descriptions (e.g., Command: give diamond 1).

📜 Permissions

• velkoth.use: Default permission granted to all players allowing them to view help and check their personal statistics.
• velkoth.admin: Default OP permission granting full administrative access to edit arenas, bypass timers, and trigger events.

📦 Building from Source

To compile the standalone shadow JAR natively (including the Cloud command libraries and Okaeri configs):

git clone https://github.com/YourName/VelKoth.git
cd VelKoth
./gradlew clean shadowJar

Your compiled plugin will be deposited in /build/libs/.