BanTools

BanTools is an advanced ban management plugin designed for Minecraft Velocity servers. It supports banning players by UUID, IP address, or username, and provides dynamic configuration reloading and real-time kicking of online players.

Загрузки: 963
Подписчики: 3
Обновлён: 20 января 2026 г.
Лицензия: GPL-3.0-only

Опубликован 21 апреля 2025 г.

Исходный код Сообщить об ошибке

BanTools - Velocity Ban Management Plugin

BanTools is an advanced ban management plugin designed for Minecraft Velocity servers. It supports banning players by UUID, IP address, or username, and provides dynamic configuration reloading and real-time kicking of online players.

Note: This plugin is AI-developed to help server administrators manage player bans more efficiently.

Features

Ban Functionality:
- Supports banning by UUID, IP address, or player name.
- Default ban duration is permanent (if no duration is specified).
- Supports specifying ban duration (e.g., 7d for 7 days, 2024/1/10-2025/01/10 for a custom date range).
- Automatically kicks banned online players.
Unban Functionality:
- Supports unbanning a player using the /bantools unban command.
- Unbanning does not delete the ban record but marks the ban status as invalid.
Kick Functionality:
- Supports immediately kicking a player using the /bantools kick command.
- A custom kick reason can be specified (default uses the configured reason in the config file).
Automatic Unban Mechanism:
- If a ban duration is specified, the ban will automatically expire when the time ends.
Multi-Condition Matching:
- On login, checks if UUID, IP address, or player name matches any ban records.
- If any condition matches, the player is considered banned.
Configuration File Support:
- All ban records are stored in the config.conf file, which supports manual editing.
- The configuration file allows setting default ban and kick reasons.
Dynamic Configuration Reload:
- Supports dynamically reloading the configuration file via the /bantools reload command without restarting the server.
Real-Time Synchronization:
- All ban, unban, and kick operations are synchronized in real-time across all downstream servers.

Installation

1. Download the Plugin

Download the latest version of BanTools.jar from GitHub or other distribution channels.

2. Install the Plugin

Place the downloaded BanTools.jar file into the plugins/ directory of your Velocity server.

3. Start the Server

Start the Velocity server. The plugin will automatically generate a default configuration file at plugins/BanTools/config.conf.

Configuration（`config.conf`）

defaults {
  ban_reason = "违反服务器规则"
  kick_reason = "管理员强制踢出"
}

bans {
  "Player1": {
    name: "Player1"
    uuid: "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    ip: "192.168.1.100"
    reason: "作弊行为"
    start_time: 1698765432
    end_time: null  # 永久封禁
    state: true     # 封禁状态（true：生效，false：解除）
  }
}

defaults.ban_reason: Default ban reason.
defaults.kick_reason: Default kick reason.
bans: Stores all ban records, each entry contains the following fields:
- name: Player name.
- uuid: Player UUID.
- ip: Player IP address.
- reason: Ban reason.
- start_time: Ban start time (Unix timestamp).
- end_time: Ban end time (Unix timestamp), set to null for permanent bans.
- state: Ban status (true for active, false for unban).

Usage

Commands

Command	Permission Node	Description
`/bantools reload`	`bantools.command.reload`	Reloads the plugin configuration file.
`/bantools ban <type> <value>`	`bantools.command.ban`	Bans the specified player.
`/bantools unban <player>`	`bantools.command.unban`	Unbans the specified player.
`/bantools kick <player>`	`bantools.command.kick`	Kicks the specified player.

Examples

Ban a player named Bianpao_xiaohai: /bantools ban Bianpao_xiaohai (default ban duration is permanent; a reason can be added afterward).
Unban a player named Steve: /bantools unban Steve.
Kick a player named Steve: /bantools kick Steve.

Support & Feedback

If you encounter issues or have suggestions, please contact us via:

GitHub Issues: Submit an Issue

License & Disclaimer

Development Notice: This plugin is AI-developed to provide efficient ban management tools for the Minecraft Velocity community.
License: Distributed under the GNU General Public License v3.0. You may use, modify, and distribute it under the license terms.
Disclaimer: The developer is not responsible for any issues arising from the use of this plugin.

Acknowledgments

Special thanks to the following technologies and tools:

Ченджлог

1.4.2Релиз1.21.9, 1.21.10, 1.21.11 · 20 января 2026 г.

🔧 版本更新日志

v1.4.2 (最新版本)

新增功能：

🆕 可配置日志输出：新增 fakeban.log_loading_info 配置项，控制是否输出"加载了 X 个活跃的临时封禁记录"信息
🆕 可配置清理间隔：新增 fakeban.cleanup_interval_minutes 配置项，自定义过期记录检查间隔（默认1分钟）

配置优化：

管理员可以通过设置 log_loading_info = false 来关闭临时封禁加载日志
可以调整清理间隔来平衡性能和及时性（建议1-5分钟）

v1.4.1

重要修复：

🔧 修复空指针异常：解决了当封禁记录中UUID为null时导致的NullPointerException
🔧 改进离线玩家处理：完善了对离线封禁玩家的UUID和IP检查逻辑
🔧 增强稳定性：修复了临时封禁系统中的null值处理问题
🔧 登录拦截修复：确保离线封禁的玩家能够被正确拦截

技术改进：

在所有UUID和IP比较前添加null检查
优化了封禁匹配算法的安全性
改进了错误处理机制

1.4.0Релиз1.21.8, 1.21.9, 1.21.10 · 12 октября 2025 г.

🔧 Version update log

###V1.4.0 (latest version) Major new features:

🆕 ** FakeBan: A brand new temporary ban feature that supports automatic expiration and secondary confirmation mechanisms
🆕 ** Whitelist Protection System * *: protects designated players from bans, kicks, and temporary bans, preventing administrators from being maliciously banned
🆕 ** Intelligent Tab Completion * *: Comprehensive command completion support to improve operational efficiency and accuracy
🆕 ** Double confirmation mechanism * *: Fakeban operation requires executing the same command again within the specified time to take effect
🆕 ** Automatic expiration cleaning * *: The temporary ban will be automatically lifted after it expires, without the need for manual intervention

User experience improvement:

🆕 ** Intelligent Tab Completion System * *: Comprehensive command completion support, greatly improving operational efficiency
🆕 ** Permission aware completion * *: intelligently display available commands based on user permissions
🆕 ** Intelligent player filtering * *: automatically excludes players protected by whitelist to avoid misoperation
🆕 ** Quick completion of common options * *: Quick selection of commonly used parameters such as ban reason and duration
🆕 ** State awareness completion * *: unban displays banned players, unfakeban displays temporarily banned players

New command: -Bantools Fakeban[Reason] - Temporary ban on player (requires secondary confirmation) -/batools unfakeban- Lift temporary ban

User experience improvement: -Intelligent Tab Completion: Display available commands based on permissions, automatically complete player names and common parameters -Player name filtering: Automatically exclude players from the whitelist protection during Tab completion -Common options: Provide quick selection of common reasons and duration of bans -State awareness: The unban and unfakeban commands only display players in their corresponding states

Configuration enhancement: -Unified configuration file: All configurations are centralized in the main configuration file, including whitelist settings -Added 'fakeban' configuration section, supporting custom temporary ban duration and confirmation message -Support customizing default reasons for temporary bans and confirming timeout periods

Technical improvements: -Optimized command processing architecture, supporting dynamic completion -Improved player list acquisition mechanism -Enhanced unified management of configuration files

Security improvement: -All operations (ban, kick, fakeban) support whitelist protection -Prevent administrators from being maliciously banned due to permission leakage -Temporary ban and regular ban are completely independent and do not affect each other

1.3Релиз1.21.6, 1.21.7, 1.21.8 · 31 августа 2025 г.

Fixed some bugs

1.2Релиз1.21.3, 1.21.4, 1.21.5 · 23 апреля 2025 г.

BanTools | v1.2 Features

Ban Functionality:
- Supports banning by UUID, IP address, or player name.
- Default ban duration is permanent (if no duration is specified).
- Supports specifying ban duration (e.g., 7d for 7 days, 2024/1/10-2025/01/10 for a custom date range).
- Automatically kicks banned online players.
Unban Functionality:
- Supports unbanning a player using the /bantools unban command.
- Unbanning does not delete the ban record but marks the ban status as invalid.
Kick Functionality:
- Supports immediately kicking a player using the /bantools kick command.
- A custom kick reason can be specified (default uses the configured reason in the config file).
Automatic Unban Mechanism:
- If a ban duration is specified, the ban will automatically expire when the time ends.
Multi-Condition Matching:
- On login, checks if UUID, IP address, or player name matches any ban records.
- If any condition matches, the player is considered banned.
Configuration File Support:
- All ban records are stored in the config.conf file, which supports manual editing.
- The configuration file allows setting default ban and kick reasons.
Dynamic Configuration Reload:
- Supports dynamically reloading the configuration file via the /bantools reload command without restarting the server.
Real-Time Synchronization:
- All ban, unban, and kick operations are synchronized in real-time across all downstream servers.

1.1-SNAPSHOTРелиз1.21.3, 1.21.4, 1.21.5 · 21 апреля 2025 г.

更新日志：优化了部分代码结构删除了一些冗余代码更新了英文版README.md

如果有bug，欢迎提交Issues！

1.0Релиз1.21.3, 1.21.4, 1.21.5 · 21 апреля 2025 г.

BanTools - Velocity Ban Management Plugin

Note: This plugin is AI-developed to help server administrators manage player bans more efficiently.

Features

Multi-Dimensional Bans:
- Supports banning players by UUID, IP address, or username.
- Ban priority: UUID > IP > Username.
Dynamic Ban Management:
- Use /ban uuid <uuid>, /ban ip <ip>, and /ban name <name> to dynamically add bans.
- Bans are instantly written to the configuration file (config.conf).
Online Player Handling:
- Banned players currently online are kicked immediately.
Configuration Reload:
- Use /bantools reload to reload the configuration file without restarting the server.
User-Friendly:
- Configuration files use HOCON format for easy maintenance and scalability.

BanTools

BanTools - Velocity Ban Management Plugin

Features

Installation

1. Download the Plugin

2. Install the Plugin

3. Start the Server

Configuration（`config.conf`）

Usage

Commands

Examples

Support & Feedback

License & Disclaimer

Acknowledgments

Ченджлог

🔧 版本更新日志

v1.4.2 (最新版本)

v1.4.1

🔧 Version update log

BanTools | v1.2 Features

BanTools - Velocity Ban Management Plugin

Features

Комментарии

Открытый код

BanTools - Velocity Ban Management Plugin

Features

Installation

1. Download the Plugin

2. Install the Plugin

3. Start the Server

Configuration（config.conf）

Usage

Commands

Examples

Support & Feedback

License & Disclaimer

Acknowledgments

Ченджлог

🔧 版本更新日志

v1.4.2 (最新版本)

v1.4.1

🔧 Version update log

BanTools | v1.2 Features

BanTools - Velocity Ban Management Plugin

Features

Комментарии

Открытый код

Configuration（`config.conf`）