Quick Navigation

KothWars - v2.1 Live Console CONNECTING...

KothWars v2.1

Complete Documentation

The ultimate KOTH (King of the Hill) plugin for Minecraft servers. Featuring advanced GUI system, web API integration, real-time event tracking, custom rewards, scheduling, and beautiful visual effects.

Web API Integration
Smart Alert System
Head in Chat
bStats Analytics

New Features v2.1

NEW

Main Features of v2.1

Version 2.1 introduces advanced features that enhance the administration and monitoring experience.

Integrated Web API

Complete web API system for real-time server event monitoring. Allows integration with external dashboards and web applications.

  • Secure authentication with API Key
  • Real-time events
  • Complete historical log
  • RESTful endpoints

Smart Alert System

Configure minute alerts before scheduled KOTHs start. Notifies players with customizable anticipation.

  • Multiple configurable minutes
  • Broadcast alerts
  • Web event integration
  • Per-KOTH configuration

Head in Chat

Displays the player's head in chat when capturing a KOTH. Impressive visual effect that enhances the capture experience.

  • Smart skin cache
  • Online/offline support
  • Particle effects
  • ASCII art rendering

Complete Admin GUI

NEW: The GUI now includes minute alert configuration and head in chat system.

Updated Required Permissions

Main permission: kothwars.admin
Automatically includes:
• kothwars.reload - Reload configuration
• kothwars.start - Start KOTHs
• kothwars.stop - Stop KOTHs
• kothwars.remove - Remove KOTHs
• kothwars.headcache - Manage head cache
• NEW: Full access to alert system

1

Access the Admin GUI

To open the administrative graphical interface, execute:

/koth
Opens the main admin GUI menu

This command opens the main menu with enhanced options:

  • Create New KOTH - Starts creation with selection system
  • Manage KOTHs - Complete list with real-time status
  • NEW: Quick access to alert configuration

    • Minute Alert System

    1

    Configure Minute Alerts

    In each KOTH's configuration menu, you'll find the "Alert Minutes" option. Allows configuration of multiple anticipation minutes for alerts.

    Alert Configuration

    Activate/Deactivate
    Add Minute
    Current Minutes
    Delete
    2

    Configuration Examples

    Recommended configurations for different server types:

  • Competitive servers: 5, 2, 1 (alerts close to start)
  • Special events: 60, 30, 15, 5 (extended alerts)
  • 24/7 servers: 15, 5 (balance between warning and spam)
  • Fast KOTHs: 2, 1 (for fast rotation events)

    • Head in Chat System

    1

    Display on Capture

    When a player captures a KOTH, their head appears in chat in ASCII art format with enhanced visual effects. The system includes:

  • Smart cache: Stores skins for fast access
  • Offline support: Works with SkinsRestorer
  • Alternative sources: Minotar, MC-Heads, Crafatar
  • Color rendering: Uses hex codes for precision
    • 2

    Management Commands

    New commands to manage the head system:

    /koth headcache clear
    Clears the head cache
    /koth headcache stats
    Shows cache statistics

    Create a KOTH (Updated)

    IMPROVEMENT: The creation process now includes initial alert configuration and advanced options.
    1

    Enhanced Creation Process

    The process now includes initial minute alert configuration and enhanced display options.

  • Initial alert configuration (5 minutes by default)
  • Bossbar style selection from the start
  • Preconfigured glow options
  • Automatic web API integration

    • Select the KOTH Area

    Selection Tool

    When confirming creation, you'll receive a Blaze Rod with the following information:
    • KOTH Name
    • Usage instructions
    • Selected point status
    • Calculated area information

    1

    Select Point A

    Use the Blaze Rod and left click on a block to set Point A. You'll see blue/green particles and a confirmation message.

    // Messages you'll see:
    Point A set
    Point A set at X:100.5 Y:64.0 Z:200.5
    2

    Select Point B

    Use the Blaze Rod and right click on another block to set Point B. You'll see blue/light particles and a confirmation message.

    // Messages you'll see:
    Point B set
    Point B set at X:110.5 Y:70.0 Z:210.5
    3

    View the Area

    Once both points are selected, you'll see a particle effect showing the complete area with a golden outline. The system will automatically calculate:

  • World: Name of the world where the area is located
  • Dimensions: Width, Height and Length of the area
  • Volume: Total number of blocks in the area
    • 4

    Final Confirmation

    After 3 seconds of having both points selected, the system will automatically confirm the area and:

  • Play a completion sound
  • Show particle effects in the center of the area
  • Show an on-screen title confirming creation
  • Remove the selection tool from your inventory
  • Save the KOTH to the database

    • Cancel Selection

    If you need to cancel the selection at any time:
    • Hold Shift and right click in the air
    • This will remove the tool and cancel the process
    • You'll see smoke particles and a cancellation message

    Configure an Existing KOTH

    1

    Access KOTHs List

    From the main menu, click "Manage KOTHs" to see all created KOTHs. Each KOTH is displayed with:

  • Icon: Beacon representing the KOTH
  • Name: KOTH name in gold color
  • Information: World, active status, capture time
  • Action: Click to open the configuration menu
    • 2

    KOTH Configuration Menu

    When clicking on a KOTH, a complete configuration menu opens with the following options:

    Main Configuration

    Capture Time
    Scheduling
    Rewards
    Glow/Outline
    Start/Stop
    Particles

    Glow System (Outline)

    What is the Glow System?

    The glow system allows players who are capturing a KOTH to glow with a specific color. This helps quickly identify who is capturing and adds an attractive visual effect.

    1

    Glow Configuration

    In the KOTH configuration menu, click "Outline Settings" (brush icon). This will open the glow configuration menu with two main options:

    Glow Options

    Chroma
    Colors

    Configure Glow Effect

    1

    Chroma Option (Rainbow)

    The Chroma option makes the glow color change automatically creating a rainbow effect. When activated, the system cycles through all available colors.

    Important Note: The Chroma effect requires the player to be on a special team that constantly changes color.
    2

    Select Fixed Color

    If Chroma is deactivated, you can select a fixed color from the available palette:

    Each color has a corresponding hexadecimal code used in the PlaceholderAPI system.

    3

    How Glow Works Visually

    The KothWars glow system works through Minecraft's scoreboard teams system. When a player starts capturing a KOTH:

  • A special team called "kothwars_glow_color" is created
  • The player is added to this team
  • The team has a specific color assigned
  • Minecraft automatically applies the glow effect to all players on the team

    • Placeholder System

    Requirement: PlaceholderAPI

    To use KothWars placeholders, you need to have PlaceholderAPI installed. Placeholders can be used in scoreboards, chat, holograms, and any plugin that supports PlaceholderAPI.

    1

    Available Placeholders

    KothWars offers two types of placeholders: for KOTH information and for the glow system.

    KOTH Information

    Placeholders to get specific information about a KOTH

    %kothwars_capturer_NAME%
    %kothwars_capturing_NAME%
    %kothwars_progress_NAME%
    %kothwars_active_NAME%

    Glow System

    Placeholders to get player glow information

    %kothwarsglow_color%
    %kothwarsglow_hex%
    %kothwarsglow_hex_no_hash%

    Glow System Placeholders

    1

    %kothwarsglow_color%

    Returns the legacy color code (& format) of the player's current glow.

    Returned Values

    RED → &c
    GOLD → &6
    YELLOW → &e
    GREEN → &a
    DARK_GREEN → &2
    AQUA → &b
    BLUE → &9
    DARK_PURPLE → &5
    LIGHT_PURPLE → &d
    WHITE → &f
    GRAY → &7
    NONE → &f (white by default)
    2

    %kothwarsglow_hex%

    Returns the hexadecimal code of the glow color with the # symbol.

    Returned Values

    RED → #FF5555
    GOLD → #FFAA00
    YELLOW → #FFFF55
    GREEN → #55FF55
    DARK_GREEN → #00AA00
    AQUA → #55FFFF
    BLUE → #5555FF
    DARK_PURPLE → #AA00AA
    LIGHT_PURPLE → #FF55FF
    WHITE → #FFFFFF
    GRAY → #AAAAAA
    NONE → #FFFFFF (white by default)
    3

    %kothwarsglow_hex_no_hash%

    Returns the hexadecimal code of the glow color without the # symbol. Useful for plugins that don't accept the # symbol in colors.

    Example: If the glow is red (#FF5555)
    %kothwarsglow_hex% returns: #FF5555
    %kothwarsglow_hex_no_hash% returns: FF5555

    Glow Display in Tab

    IMPORTANT!
    For the glow to be visible in the player tab, you MUST use the placeholders in a tab plugin like TabList, TAB, or similar. Minecraft's glow system only shows colors in the tab if the player's name includes the color codes.
    1

    Configure Tab with Placeholders

    To display glow in the tab, you need to use a tablist plugin that supports PlaceholderAPI. Here's a configuration example:

    # Example for TabList plugin:
    playerlist:
      formats:
        default: '%kothwarsglow_color%%player%'

    # Example for TAB plugin:
    playerlist:
      %player%:
        tabprefix: '%kothwarsglow_color%'
    2

    Why does it appear white without placeholder?

    Minecraft's team system only assigns the color to the team, but for it to be visible in the tab, the player's name must contain the color code. Without the placeholder:

  • The player will have the glow effect around their character
  • The team will have the assigned color
  • But in the tab it will appear white because the name doesn't have a color code

    • Solution: Use %kothwarsglow_color% in your tab plugin so the player's name includes the corresponding color code.

    3

    Functional Example

    When everything is configured correctly:

  • Player "Player1" captures a KOTH with red glow
  • %kothwarsglow_color% returns: &c
  • Tab plugin shows: &cPlayer1
  • In the tab it appears: Player1 (in red)
  • Around the character: Visible red glow effect

    • KOTH Auto Suspension

    What is Auto Suspension?

    Auto suspension is a system that automatically stops a KOTH after an inactivity period (no players in the area).

    Purpose: Prevent KOTHs from remaining active indefinitely when no players are participating, optimizing server performance.

    1

    How the System Works

    The auto suspension system works in real time checking every second:

  • Check: Every second checks if there are players in the KOTH area
  • Counter: If there are NO players, an inactivity counter is incremented
  • Reset: If a player ENTERS the area, the counter resets to 0
  • Suspension: When the counter reaches the configured time, the KOTH stops
    • 2

    Usage Scenarios

    Auto suspension is useful in these situations:

  • Empty events: When you start a KOTH and no one comes to capture it
  • Low activity hours: During late night when there are few players
  • Forgotten KOTHs: When you forget to stop a KOTH manually
  • Optimization: To free server resources when not in use

    • Configure Auto Suspension

    1

    Configuration in GUI

    In the KOTH configuration menu, find "Auto Suspend Time" (funnel icon).

    Suspension Configuration

    +30 seconds
    -30 seconds
    Current Time

    Configuration in GUI:
    • Left click: +30 seconds to suspension time
    • Right click: -30 seconds to suspension time
    • Minimum: 30 seconds
    • Default value: 300 seconds (5 minutes)

    2

    Suspension Time Calculation

    Suspension time is calculated in seconds. Here are some examples:

  • 30 seconds: For test KOTHs or very short events
  • 60 seconds (1 minute): For KOTHs on servers with high rotation
  • 180 seconds (3 minutes): Standard time for most KOTHs
  • 300 seconds (5 minutes): Default value - good balance
  • 600 seconds (10 minutes): For KOTHs on servers with few players
  • 1800 seconds (30 minutes): For special events or permanent KOTHs
    • Recommendation: Don't configure very long times (more than 10 minutes) unless necessary, as they can affect server performance.
    3

    Suspension Process

    When a KOTH is automatically suspended, the following occurs:

  • Broadcast message: Announces to all players that the KOTH has been suspended
  • Effect cleanup: Removes all visual effects (glow, bossbar, particles)
  • Progress reset: Capture progress resets to 0
  • Inactive status: The KOTH is marked as inactive in the database
  • Resource release: All resources associated with the KOTH are released
    • // Message shown when suspended:
    KOTH 'KOTHName' suspended due to inactivity
    4

    Reactivation after Suspension

    An automatically suspended KOTH can be reactivated in several ways:

  • Manually: Using the command /koth start KOTHName
  • From GUI: In the KOTH configuration menu, click "Start"
  • Automatically: If scheduling is configured, it will start at its next schedule

    • Note: Auto suspension does not delete the KOTH, only temporarily stops it. All configurations (rewards, glow, scheduling) are maintained.

    5

    Performance Optimization

    Auto suspension significantly helps server performance:

  • Fewer checks: Inactive KOTHs don't check for players every second
  • Fewer particles: No unnecessary visual effects are generated
  • Fewer teams: Scoreboard teams are released when not used
  • Fewer bossbars: Bossbars are removed when the KOTH is inactive
  • Less memory: Memory resources associated with the active KOTH are released
    • Tip: If you have many KOTHs on your server, configure reasonable suspension times (3-5 minutes) to maintain good performance.
    6

    Special Cases

    There are situations where auto suspension behaves specially:

  • With active capturer: If someone is capturing, it does NOT suspend
  • During alerts: If alerts are being shown, it does NOT suspend
  • Newly started KOTH: Has a grace period before starting to count inactivity
  • Scheduled KOTH: If configured with scheduling, it will restart automatically

    • Summary: The auto suspension system is intelligent and only acts when there's truly no activity in the KOTH.