KOTL

---

• Classic King of the Ladder Gameplay: Climb, fight, and claim the crown while other players try to knock you away from the top.
• Automatic Arena Detection: Players enter and leave games naturally by walking into or out of a configured Game Area.
• Custom King Plates: Place the crown trigger anywhere inside the arena and choose from multiple pressure plate materials.
• King Cooldowns & Knockback: Control repeated crown claims with configurable cooldowns, action bar feedback, and plate knockback.
• Interactive GUI Setup: Create and manage arenas through visual in-game menus instead of manually editing files.
• Visual Area Selection: Select arena corners with a dedicated tool and preview the complete Game Area with configurable particle outlines.
• Player Preparation: Save and restore inventories while using configurable inventory clearing, potion effect cleanup, and per-arena join game modes.
• Arena Records & Statistics: Track crown claims, kills, deaths, tours played, personal arena scores, and top kings.
• Configurable Rewards: Run console or player commands when players join, quit, become king, kill an opponent, or die, with built-in player, arena, king, target, score, and statistics placeholders.
• Scoreboards & BossBars: Keep players informed with fully configurable live game displays.
• Highly Configurable: Customize messages, sounds, menus, items, chat, cooldowns, scoreboards, boss bars, and gameplay behavior.
• PlaceholderAPI & Leaderboards: Display live player, arena, king, record, and leaderboard data on holograms, scoreboards, or other plugins.
• Flat File & MySQL Storage: Start with simple local storage or scale player data across your network with MySQL.
• Developer API: Hook into game shutdown, arena entry and exit, king changes, and statistic updates through a public event API.

---

📸 Click to view the step-by-step guide

Initialize a new arena with a unique ID.

/kotl create <arena_id>

Open the visual editor for the arena.

/kotl edit <arena_id>

Set the safe fallback location used when a player is removed from the arena, the server reloads, or an unexpected error occurs.

Use the Game Area selector to mark the two opposite corners of the complete playable area.

• Left-click: Set the first corner.
• Right-click: Set and save the second corner.
• Outline Preview: Toggle the particle visualizer to inspect the selected area.

Choose a pressure plate material, receive the setup tool, and place the plate inside the selected Game Area. This plate becomes the crown trigger.

Choose how players are prepared when they enter the arena.

• Join Gamemode: Select Survival, Creative, Adventure, or keep the player's current mode.
• Inventory & Effects: Toggle inventory clearing and potion effect removal.
• Game Displays: Enable or disable the arena scoreboard and boss bar.
• Arena Records: Review or reset the arena's king record when needed.

Click the Firework item to validate, save, register, and enable the arena.

How to Play:

• Enter: Walk into the enabled Game Area to join automatically.
• Leave: Walk outside the Game Area to leave, restore your saved inventory, and remove the arena displays.

---

• Enter the Arena: Walk into an enabled Game Area and the plugin automatically prepares your player state for the competition.
• Climb the Tower: Race up the ladder structure while keeping your position against every other challenger.
• Fight for Position: Knock opponents away from the route and stop them from reaching the top before you.
• Reach the King Plate: Step on the configured pressure plate to claim the crown and become the arena's current king.
• Earn Your Score: Every successful crown claim increases your total score, tours played, and personal score for that arena.
• Break the Record: Outscore the current record holder to become the arena's top king.
• Challenge Again: After the configurable king cooldown expires, climb back to the plate and fight for another crown.
• Leave Safely: Walk outside the Game Area when you are finished and the plugin restores your saved inventory and removes the arena displays.

---

Player Commands (Everyone)

No permissions are required for statistics. Help access is enabled for everyone by default.

• /kotl help — kotl.command.help — Display the available King of the Ladder commands.
• /kotl stats [player] — Open the in-game statistics menu for yourself or a cached online or offline player.

Arena Management Commands

Requires kotl.arena.* for full access.

• /kotl create <arena_id> — kotl.arena.create — Create a new arena with the specified unique ID.
• /kotl delete <arena_id> [--confirm] [--cancel] — kotl.arena.delete — Delete an arena after confirming the action.
• /kotl edit <arena_id> — kotl.arena.edit — Open the in-game GUI editor for arena setup and management.
• /kotl list — kotl.arena.list — Display all registered arenas together with their readiness and availability state.

Admin Commands

Requires kotl.admin for full access.

• /kotl reload — kotl.admin.reload — Stop active games and reload messages, options, items, events, command settings, game displays, and arena outlines.
• /kotl stop [arena] — kotl.admin.stop — Stop your current arena game or a specified active arena game.
• /kotl kick <player> — kotl.admin.kick — Remove a player from an active arena and send them to its end location.

Debug Commands (Advanced Users)

Requires kotl.debug for full access and debug mode must be enabled.

⚠️ Note: Debug commands are intended for testing and troubleshooting.

• /kotl debug component <message> — kotl.debug.component — Parse and preview a MiniMessage component in-game.
• /kotl debug dump — kotl.debug.dump — Generate and send an event timing report for troubleshooting performance issues.

---

---

Player Statistics Placeholders

These placeholders display statistics for the player viewing them.

%kotl_name%                           - Returns the player's name
%kotl_uuid%                           - Returns the player's unique ID
%kotl_games_played%                   - Total tours played
%kotl_score%                          - Total number of crown claims
%kotl_kills%                          - Total number of kills
%kotl_deaths%                         - Total number of deaths
%kotl_stat:arena_score:<arena_id>%    - Personal score in a specific arena

Current Game & Global Placeholders

Display the player's current arena information or global activity across the server.

Current Player Data

%kotl_is_playing%                    - Whether the player is inside an arena
%kotl_current_arena%                 - Current arena ID
%kotl_current_arena_players%         - Player count in the current arena
%kotl_current_arena_king%            - Current king of the player's arena
%kotl_current_arena_last_king%       - Last king of the player's arena
%kotl_current_arena_top_king%        - Record holder of the player's arena
%kotl_current_arena_top_king_score%  - Record score of the player's arena
%kotl_current_arena_score%           - Player's score in the current arena

Global Server Data

%kotl_arenas_total%                  - Total registered arenas
%kotl_arenas_ready%                  - Total ready arenas
%kotl_active_games%                  - Games with active players
%kotl_active_players%                - Players across all active games

Arena Status Placeholders

Fetch live data from specific arenas. Replace <id> with your arena identifier, for example arena1.

Live Game Data

%kotl_arena:<id>:players%             - Current player count
%kotl_arena:<id>:king%                - Current king
%kotl_arena:<id>:last_king%           - Last player to claim the crown
%kotl_arena:<id>:top_king%            - Arena record holder
%kotl_arena:<id>:top_king_score%      - Arena record score

Arena Settings

%kotl_arena:<id>:ready%               - Whether the arena setup is complete
%kotl_arena:<id>:enabled%             - Whether the arena is available
%kotl_arena:<id>:gamemode%            - Configured join game mode
%kotl_arena:<id>:scoreboard_enabled%  - Per-arena scoreboard setting
%kotl_arena:<id>:bossbar_enabled%     - Per-arena boss bar setting

Leaderboard Placeholders

Display your server's top-performing players on scoreboards or holograms.

%kotl_leaderboard:<statistic>:<position>:<type>%

1. Parameters

• <statistic>: The statistic to rank from the list below.
• <position>: The rank position, such as 1, 2, or 3.
• <type>: name for username, value for score, uuid, or formatted_value.

2. Available Statistics

You can use these statistics for ranking:

• score (Total crown claims)
• kill (Total kills)
• death (Total deaths)
• tours_played (Total tours played)
• arena_score_<arena_id> (Personal score in a specific arena)

3. Usage Examples

# Name of the 1st place player by total crown claims
%kotl_leaderboard:score:1:name%

# Crown claim count of the 1st place player
%kotl_leaderboard:score:1:value%

# Name of the 3rd place player by total kills
%kotl_leaderboard:kill:3:name%

# Name of the top player in a specific arena
%kotl_leaderboard:arena_score_arena1:1:name%

---

---