BanTools: Advanced Player Management for Minecraft Velocity Servers
Running a Minecraft Velocity proxy network comes with its own set of challenges, especially when it comes to maintaining order across multiple backend servers. Server administrators need reliable tools to handle problematic players efficiently without constantly restarting the proxy or manually editing configuration files. BanTools steps into this space as a purpose-built solution that streamlines the entire ban management process, offering flexibility that traditional vanilla commands simply cannot match.
What Makes BanTools Stand Out
BanTools is not just another ban plugin. It is a comprehensive player management system designed specifically for the Velocity proxy environment. The plugin supports banning players through three distinct identifiers: UUID, IP address, or username. This multi-layered approach means that even if a player attempts to evade a ban by changing their username or connecting from a different account, the system can still recognize and block them based on their unique UUID or network address.
The plugin stores all ban records in a human-readable configuration file, making manual edits straightforward for administrators who prefer direct file access. At the same time, the dynamic configuration reload feature allows changes to take effect without any server downtime. A simple command refreshes the ban list, and the updates synchronize across all downstream servers in real time.
Core Features of BanTools
BanTools brings a robust set of capabilities to Velocity proxy management. The plugin handles both permanent and temporary bans with equal ease, automatically lifting restrictions when a specified duration expires. Here is what administrators can expect:
- Flexible Ban Types: Issue bans based on UUID, IP address, or player name, with support for permanent and time-limited durations.
- Automatic Kicking: When a ban is applied, any currently online player matching the criteria is immediately removed from the network.
- Unban Functionality: Remove bans without deleting records, preserving the history while restoring player access.
- Manual Kick Command: Forcefully disconnect a player with a customizable reason message.
- Automatic Expiry: Time-limited bans expire automatically, requiring no manual intervention from staff.
- Multi-Condition Login Checks: Every login attempt is verified against UUID, IP, and username records simultaneously.
- Dynamic Reloading: Apply configuration changes instantly without restarting the Velocity proxy.
- Real-Time Synchronization: All ban, unban, and kick operations propagate immediately across connected servers.
Installation and Setup
Getting BanTools up and running on a Velocity proxy is a straightforward process. First, download the latest BanTools.jar file from the official GitHub repository or trusted distribution channels. Place the JAR file into the plugins directory of your Velocity server installation, then start or restart the proxy. Upon first launch, BanTools automatically generates a default configuration file at plugins/BanTools/config.conf, complete with sensible default values for ban and kick reasons.
For those who prefer a more streamlined approach to plugin management, BanTools can be easily installed via the foxygame.net launcher, a convenient and modern Minecraft launcher that lets you browse and download mods and plugins directly from its built-in menu without the hassle of manual file transfers. This makes keeping your server tools updated remarkably simple, especially when managing multiple plugins across different server instances.
Configuration File Structure
The configuration file uses a clean, hierarchical format that is easy to read and modify. The defaults section allows administrators to set global ban and kick reason messages that apply when no custom reason is provided. The bans section stores individual ban records, each containing the player's name, UUID, IP address, reason for the ban, start time as a Unix timestamp, an optional end time for temporary bans, and a state flag indicating whether the ban is currently active.
Setting an end time to null designates a permanent ban, while specifying a future timestamp creates a temporary restriction that will automatically lift when the time arrives. The state field toggles between true and false, allowing administrators to deactivate a ban without removing the record entirely. This preserves the disciplinary history for future reference while granting the player access once again.
Command Reference and Permissions
BanTools operates through a clean set of commands, each tied to a specific permission node for granular access control. The reload command refreshes the configuration without restarting the proxy, making it ideal for quick adjustments during active server hours. The ban command accepts a type parameter followed by the target value, with an optional reason appended at the end. The unban command simply requires the player name and marks the corresponding record as inactive. The kick command immediately disconnects a player, using either a custom reason or the default configured message.
Here is a quick overview of the available commands:
- /bantools reload — Permission: bantools.command.reload — Reloads the configuration file dynamically.
- /bantools ban <type> <value> [reason] — Permission: bantools.command.ban — Applies a ban to the specified player.
- /bantools unban <player> — Permission: bantools.command.unban — Removes an active ban from a player.
- /bantools kick <player> [reason] — Permission: bantools.command.kick — Forcefully disconnects a player from the network.
Practical Usage Examples
Consider a scenario where a player named Bianpao_xiaohai is causing disruption across multiple servers behind your Velocity proxy. With BanTools, a single command permanently bans the player and immediately removes them from the network. If the offense warrants only a temporary suspension, adding a duration parameter such as 7d restricts access for exactly one week, after which the ban lifts automatically. For less severe situations, the kick command provides a quick way to remove a troublesome player without applying a lasting ban, while the unban command restores access for players who have served their suspension period.
Technical Foundation and Licensing
BanTools is built on a solid technical foundation, leveraging the Velocity API for seamless proxy integration, Typesafe Config for robust configuration management, and the Adventure API for modern chat formatting. The plugin is distributed under the GNU General Public License v3.0, granting server administrators the freedom to use, modify, and redistribute the software as needed. As an AI-developed tool, BanTools represents the growing intersection of automated development and practical server administration, delivering efficient solutions for the Minecraft community.
Server administrators looking to enhance their Velocity proxy with reliable ban management will find BanTools to be a valuable addition. Its combination of flexible banning options, automatic enforcement, and real-time synchronization addresses the core needs of multi-server networks without introducing unnecessary complexity. Whether dealing with persistent griefers or managing temporary suspensions, BanTools provides the control and efficiency that modern Minecraft networks demand.