VelarisKoths
— Professional King of the Hill for Paper 1.21.1 —
[ Gameplay ] [ GUI ] [ Minigame ] [ Multi-Language ] [ Zero-Lag ]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Most KOTH plugins give you a zone, a timer, and not much else. VelarisKoths is different.
Built from the ground up for Paper 1.21.1, it delivers three distinct capture mechanics, a fully GUI-driven administration workflow, native hologram provider auto-detection, a dual-zone combat system, a weekly event scheduler configurable without touching a single file, tiered reward tables, a season & ELO ranking system, achievements, power-ups, spectator mode, per-player kit distribution, animated holograms with hex-color gradient support, Discord integration — and a performance architecture purpose-built to be invisible to your TPS.
Everything is configured through GUIs. No YAML archaeology. No server restarts to apply changes. One wand, one command, and your first arena is live in under five minutes.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚔ THE THREE CAPTURE MODES
⚔ THE THREE CAPTURE MODES
VelarisKoths ships with three fundamentally different win conditions. Each one creates a completely different combat dynamic and can be selected per-arena from the GUI.
The original KOTH formula. Two or more players in the capture zone means nobody advances. The progress bar freezes. The zone becomes a no-man's-land until one side eliminates everyone else.
This mode rewards raw PvP skill above all else. There are no shortcuts — you either dominate the zone or you don't capture it. Ideal for competitive Factions and KitPVP environments where every second of capture feels earned.
Mechanical details:
- Progress halts the moment a second player enters the zone
- Optional decay rate: progress erodes over time when the zone is empty
- Optional reset-on-leave: progress resets entirely when the captor exits
- Contested state broadcasts to all online players with configurable messages
The captor keeps progressing even when challengers are present. Challengers cannot stop the capture by standing in zone — they must physically eliminate the captor to halt progress.
This mode creates asymmetric, high-stakes combat. The captor fights defensively; challengers must coordinate aggression. King Mode (strength/resistance buffs for the captor) pairs perfectly with Dominance to amplify the asymmetry.
Mechanical details:
- Captor advances regardless of how many opponents are in zone
- Challengers receive an ActionBar instruction: "Eliminate [player] to stop the capture!"
- If the captor is killed, the next player in zone immediately takes over
- King Mode can be layered on top: the captor glows and receives combat buffs
A completely different win condition. Every player in zone earns 1 point per second, simultaneously. Nobody is blocked. Nobody is contested. When the event timer reaches zero, the player with the most accumulated points wins.
This mode rewards sustained presence over raw eliminations. A player who holds the zone for 60 seconds straight beats a player who holds it for 30 seconds in two separate bursts. The live leaderboard scrolling across the ActionBar makes every second feel competitive.
Mechanical details:
- All players in zone accumulate points concurrently — no single "captor"
- ActionBar displays a live top-3 leaderboard every second: ① Player1:92 ② Player2:74 ③ Player3:41
- BossBar (purple) shows the current point leader and their score
- Winner is determined at time=0 by highest point total
- Scoreboard shows live {points_top} placeholder
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🖱 GUI-DRIVEN ADMINISTRATION
🖱 GUI-DRIVEN ADMINISTRATION
The entire plugin is administered through a layered GUI system. No file editing required for any feature.
Opened with /koth. Shows all arenas with their live status (active, inactive, on cooldown), quick-start and quick-stop buttons, and navigation to every sub-menu.
Each arena has a dedicated 5-page editor:
Page 1 — Display & Timers: Enable/disable the arena, toggle BossBar / ActionBar / Title / Scoreboard / Hologram, configure Duration, Capture Time, Grace Period, Cooldown, Decay Rate, Ambient sound interval.
Page 2 — Capture & Modes: Select capture mode (CONTESTED / DOMINANCE / POINTS), toggle Reset-on-Leave, Overtime, Sudden Death, King Mode, King Glow, Min-Player requirements, Spawn conditions.
Page 3 — Rewards & Economy: Navigate to Reward editor, Kit editor, Vault economy rewards, LuckPerms rank grants, MVP commands, Win commands. Configure tiered reward tables.
Page 4 — Visual & Particles: Choose from 40+ particle types, set particle color with hex picker, adjust size and density, configure hologram appearance including animated hex-gradient colors and speed.
Page 5 — Advanced: Random spawn configuration, respawn settings, ELO settings, season points, Discord webhook, proximity alert radius, blocked commands, combat tag settings.
A 7-column calendar grid (Monday through Sunday). Each day supports up to 4 scheduled start times. Times are entered via chat input. The timezone is configurable directly from the GUI — type any valid zone ID (e.g. America/New_York, Europe/Madrid, Asia/Tokyo) and it applies immediately.
Displays up to 45 reward slots. Add items three ways: hold in hand and click the add button, or simply click any item in your own inventory while the GUI is open. Shift-click any slot to remove it. Separate "Clear All" button with confirmation.
Create multiple reward tiers keyed to player count. Example: 1-10 players online → Tier A rewards; 11-30 players → Tier B rewards; 30+ players → Tier C rewards. Each tier has its own item table and win commands. The active tier is determined at event-end based on online player count at that moment.
Configure per-arena item kits distributed to players who enter or win the event. Add items by clicking them in your inventory — no need to hold them. Toggle kit-enabled and save-inventory separately. Supports up to 36 items per kit.
Define a separate, larger outer zone for kill tracking and MVP calculation. The inner zone remains the capture point. The outer zone is set with the wand or auto-expanded from the GUI (click = +10 blocks per side, Shift+click = +20 blocks). Full coordinate display with both zones shown simultaneously.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DUAL-ZONE SYSTEM
DUAL-ZONE SYSTEM
VelarisKoths supports two independent zones per arena:
Inner Zone (Capture Zone):
The traditional KOTH zone. Players inside this zone are tracked for capture progress, Points accumulation, and zone-based rules (no-fly, blocked commands, combat tag).
Outer Zone (Combat / MVP Zone):
A larger zone surrounding the inner zone. Kill tracking, MVP determination, and kill streak detection happen here. A player hunting the captor from 20 blocks away still contributes to the MVP calculation — as it should be.
Both zones are configured with the same wand. The outer zone can also be auto-generated from the GUI as a proportional expansion of the inner zone. If no outer zone is configured, all tracking defaults to the inner zone bounds (fully backward compatible).
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✦ HOLOGRAM SYSTEM
✦ HOLOGRAM SYSTEM
VelarisKoths auto-detects and uses the best hologram plugin available on your server:
Priority 1 — DecentHolograms (if installed)
Priority 2 — FancyHolograms (if installed)
Priority 3 — Vanilla TextDisplay (always available, no dependency needed)
No manual configuration. Just install whichever hologram plugin you prefer and VelarisKoths will use it automatically on next reload.
Animated holograms are fully supported across all providers. Configure a list of hex colors (e.g. &#FF4444,&#FF8800,&#FFCC00) and an animation speed in seconds. The hologram title cycles through the gradient. A dirty-flag system ensures hologram entities are only updated when their content actually changes — zero overhead on stable lines.
Available placeholders in hologram lines:
{koth} {time} {capturer} {clan_tag} {clan_prefix} {clan_name}
{players_in_zone} {capture_progress} {bar} {status} {event_status}
{points_leader} {points_top} {next_event} {last_winner} {anim_color}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎖 EVENTS, REWARDS & PROGRESSION
🎖 EVENTS, REWARDS & PROGRESSION
At the end of every event, a formatted summary is broadcast to all online players:
- Winner name and clan tag
- Kills leaderboard for the session
- MVP (most kills in the outer zone during the event)
- Time elapsed, zone, capture mode used
- Configurable via Discord webhook for automatic match logging
VelarisKoths includes a full season progression system:
- Season Points: Awarded on event win. Amount is configurable per arena.
- ELO: Win gain and loss penalty are configurable. All event participants are included in ELO calculations.
- Season Leaderboard: Accessible via /koth stats and the Player GUI.
- Season Reset: Manual reset via command (velariskoths.season.reset permission required).
Automatically granted and broadcast on notable milestones:
- First Win, 5 Wins, 20 Wins, 100 Wins
- First Kill, 10 Kills in a single session
- Kill Streak × 5
- Overtime Hero (win during overtime)
- Blackout (win with under 10 seconds remaining)
- Speed Capture (win in under 30 seconds elapsed)
Each achievement displays a title screen and plays a sound for the recipient.
Kill streaks are tracked per player per session. A configurable threshold (default: 3x) triggers a broadcast and visual effect. First blood (first kill of the event) triggers a separate, distinct broadcast and effect chain.
Configurable power-up spawns appear at random positions inside the arena during events. Players who walk over them collect them automatically. Type, effects, spawn rate, and maximum simultaneous power-ups are all configurable per arena.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛡 SECURITY & ZONE ENFORCEMENT
🛡 SECURITY & ZONE ENFORCEMENT
- No-Fly Enforcement: Flight is disabled for players inside the zone. Bypass permission available for admins.
- Command Blocking: A configurable list of commands is blocked while inside the zone (e.g. /home, /spawn, /tpa). Fully configurable.
- Ender Pearl / Chorus Fruit Blocking: Prevent instant teleport mechanics inside the zone, configurable per arena.
- Teleport-Out Blocking: Prevents plugin-triggered teleports out of the zone during an event.
- Combat Tag: Players who take or deal damage are tagged for a configurable duration. Tagged players cannot log out without consequence.
- Combat Logout Punishment: Configurable: KILL (instant death on logout while tagged) or REMOVE_PROGRESS (resets capture progress if the captor logs).
- Firework Safety: Win-celebration fireworks are tagged with a Persistent Data Container key to prevent them from dealing damage.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PERFORMANCE ARCHITECTURE
PERFORMANCE ARCHITECTURE
VelarisKoths was designed to leave no footprint on your server's performance. Every hot path has been reviewed for unnecessary work.
- World-scoped player lookups: All zone checks use world.getPlayers() instead of Bukkit.getOnlinePlayers(). Only players in the same world as the arena are ever iterated.
- Spectators excluded from zone logic: Players in SPECTATOR game mode are filtered out before zone detection runs.
- Hologram dirty-flag: Hologram entities (TextDisplay or third-party) are only updated when the rendered content actually changes between ticks. A stable hologram generates zero update calls.
- Scoreboard dirty-flag: The sidebar is not reconstructed if its lines are byte-for-byte identical to the previous tick. No ObjectiveDump → ObjectiveSet churn.
- Phase-rotated particle rendering: The four walls of the zone border are drawn one-per-tick in rotation, not all four simultaneously. The entire task skips if no player is within 64 blocks of the zone center.
- Distance-squared proximity checks: The ProximityTask uses distanceSquared() exclusively. Math.sqrt() is never called in any hot loop.
- State-change-only title packets: Title screens (CONTESTED, DOMINANCE, POINTS) are sent once on state transitions, not every game tick.
- Kill tracking world filter: The EntityDamageByEntityEvent handler skips immediately if neither the attacker nor the victim is in the same world as any active arena.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MULTI-LANGUAGE SYSTEM
MULTI-LANGUAGE SYSTEM
VelarisKoths ships with three complete translations out of the box:
English (en_US.yml) · Spanish — México (es_MX.yml) · Portuguese — Brazil (pt_BR.yml)
All three are extracted to plugins/VelarisKoths/lang/ on first server start. The active language is set in config.yml with a single line: language: "es_MX"
Adding a custom translation:
- Copy en_US.yml → rename to your locale code (e.g. fr_FR.yml)
- Translate the messages — every key is documented inline
- Set language: "fr_FR" in config.yml
- Run /koth reload — no restart required
Missing keys fall back to English automatically. Partial translations are fully supported — you can translate only the messages your players see most often and the rest will fall back gracefully.
You can also change the language live from the command line:
/koth lang en_US → switches to English immediately
/koth lang → lists all available language files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INTEGRATIONS
INTEGRATIONS| Plugin | What it enables |
|---|---|
| PlaceholderAPI | %vk_...% placeholders in any PAPI-compatible plugin |
| UltimateClans / UltraClans | Clan tags in holograms, scoreboard & MVP display |
| Vault | Economy money rewards to the winner |
| LuckPerms | Temporary rank grant to the winner |
| DecentHolograms | Hologram provider — auto-detected, priority 1 |
| FancyHolograms | Hologram provider — auto-detected, priority 2 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMMANDS & PERMISSIONS
COMMANDS & PERMISSIONS�
| Command | Description | Permission |
|---|---|---|
| /koth | Open main admin GUI | velariskoths.admin |
| /koth create <name> | Create a new arena | velariskoths.create |
| /koth delete <arena> | Delete an arena | velariskoths.delete |
| /koth start <arena> | Manually start an event | velariskoths.start |
| /koth stop <arena> | Stop an active event | velariskoths.stop |
| /koth wand | Get the zone-selection wand | velariskoths.wand |
| /koth tp <arena> | Teleport to arena center | velariskoths.tp |
| /koth spec <arena> | Spectate a live event | velariskoths.spectate |
| /koth pause <arena> | Pause / resume an event | velariskoths.pause |
| /koth forcewin <arena> <player> | Force a player to win | velariskoths.forcewin |
| /koth cleanup | Remove orphaned holograms | velariskoths.cleanup |
| /koth lang
Code:
|
