一个全面的 Velocity 代理插件,提供智能大厅平衡、高级玩家路由、基于数据库的玩家统计以及高级管理功能。
功能特性
智能大厅管理
- 智能负载均衡:根据当前玩家数量自动将玩家分配到多个大厅服务器
- 高级玩家路由:为高级/创作者玩家提供专用大厅和挑战服务器
- 离线服务器检测:在平衡时自动检测并避开离线服务器
- 服务器状态缓存:高效的服务器状态检查以最小化性能影响
数据库集成
- 玩家游戏时间追踪:追踪总游戏时间和各服务器的统计数据
- 自定义统计:追踪完成挑战和其他自定义玩家成就
- 基于数据库的封禁:支持 MySQL/MariaDB 后端的离线封禁
- 连接池管理:高效的 HikariCP 连接池
管理功能
- 数据库封禁:即使玩家离线也能执行封禁
- 封禁管理命令:易于使用的命令用于封禁、解封和查看封禁列表
- 可配置权限:针对所有命令的细粒度权限系统
玩家统计
- 排行榜:按游戏时间查看顶级玩家
- 个人统计:玩家可以查看自己的统计数据
- 挑战追踪:记录和追踪挑战完成情况
指标与监控
- bStats 集成:匿名使用统计
- 全面日志记录:详细的日志记录用于调试和监控
要求
- Velocity 代理服务器版本 3.4.0 或更高
- Java 17 或更高
- MySQL 8.0+ 或 MariaDB 10.5+(可选,数据库功能必需)
安装
- 从 Releases 页面下载最新的 VelocityUtilsPlus.jar
- 将 JAR 文件复制到您的 Velocity plugins 文件夹
- 启动您的 Velocity 服务器以生成默认配置
- 停止服务器并配置
plugins/velocityutilsplus/config.toml
- 如果使用数据库功能,请设置您的数据库(见下方的数据库设置部分)
- 重启您的 Velocity 服务器
配置
插件将在 plugins/velocityutilsplus/ 中生成一个 config.toml 文件。关键配置部分包括:
大厅配置
[lobbies]
# 列出您的常规大厅服务器(必须与 velocity.toml 中的名称匹配)
regular_lobbies = ["Lobby 1", "Lobby 2", "Lobby 3", "Lobby 4"]
# 高级玩家服务器
premium_lobby = "Creator Lobby"
premium_challenge = "Creator Challenge"
数据库配置
[database]
# 启用数据库集成
enabled = true
type = "mysql" # 或 "mariadb"
address = "127.0.0.1:3306"
database = "vup"
username = "vup_user"
password = "your_secure_password"
# 连接池设置
max_pool_size = 10
min_idle = 2
connection_timeout = 30000
[database.features]
playtime_tracking = true
statistics_tracking = true
friends_system = false # 尚未实现
database_bans = true
权限配置
[permissions]
# 定义每个命令所需的权限
# 设置为空字符串 "" 以允许所有人使用该命令
gban = "vup.admin"
gunban = "vup.admin"
banlist = "vup.moderator"
stats = "" # 所有人都可以使用 /stats
stats_others = "vup.moderator" # 查看其他玩家统计数据的权限
leaderboard = "" # 所有人都可以使用 /leaderboard
vup = "vup.admin"
lobby = "" # 所有人都可以使用 /lobby
creator = "vup.premium" # 仅限高级玩家
invite = "" # 任何人都可以邀请
accept = "" # 任何人都可以接受邀请
有关完整的配置模板,请参阅 config.toml.example。
数据库设置
如果您想使用数据库功能,您需要设置一个 MySQL 或 MariaDB 数据库。
步骤 1:创建数据库和用户
CREATE DATABASE vup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'vup_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON vup.* TO 'vup_user'@'localhost';
FLUSH PRIVILEGES;
步骤 2:配置插件
使用您的凭据更新 config.toml 中的数据库部分。当数据库启用时,插件将在首次启动时自动创建所有必需的表。
步骤 3:可选的手动模式导入
如果您更喜欢手动创建模式,您可以导入 database-setup.sql。
更多详细信息,请参阅:
命令
所有命令都可以在 config.toml 中配置权限。
导航命令
| 命令 |
别名 |
描述 |
默认权限 |
/lobby |
无 |
连接到平衡的大厅服务器 |
无(所有人) |
/creator |
无 |
连接到创作者/高级大厅 |
vup.premium |
/invite <player> |
无 |
邀请玩家加入您当前所在的服务器 |
无(所有人) |
/accept |
无 |
接受待处理的服务器邀请 |
无(所有人) |
管理命令
| 命令 |
描述 |
默认权限 |
备注 |
/gban <player> <reason> |
全局封禁一名玩家 |
vup.admin |
如果启用了数据库封禁,则支持离线操作 |
/gunban <player> |
全局解封一名玩家 |
vup.admin |
如果启用了数据库封禁,则支持离线操作 |
/banlist [page] |
查看所有活动封禁 |
vup.moderator |
分页列表 |
统计命令
| 命令 |
别名 |
描述 |
默认权限 |
需要数据库 |
/stats [player] |
无 |
查看游戏时长统计 |
无(所有人) |
是 |
/leaderboard [limit] |
/lb, /top |
查看游戏时长排行榜 |
无(所有人) |
是 |
管理员命令
| 命令 |
描述 |
默认权限 |
/vup |
插件信息与管理工作 |
vup.admin |
统计命令详情
/stats [player]
- 不带参数:查看自己的统计数据
- 带玩家名称:查看其他玩家的统计数据(默认需要
vup.moderator 权限)
- 显示内容:总游戏时长、各服务器游戏时长、已完成的挑战
/leaderboard [limit]
- 不带参数:显示前 10 名玩家
- 带数字:显示前 N 名玩家(最多 50 名)
- 按总游戏时长对玩家进行排名
权限
该插件使用灵活的权限系统,所有权限均可在 config.toml 中自定义。
默认权限节点
导航权限
/lobby 无需任何权限(可通过 permissions.lobby 配置)
/creator 需要 vup.premium(可通过 permissions.creator 配置)
/invite 无需任何权限(可通过 permissions.invite 配置)
/accept 无需任何权限(可通过 permissions.accept 配置)
管理权限
/gban 需要 vup.admin(可通过 permissions.gban 配置)
/gunban 需要 vup.admin(可通过 permissions.gunban 配置)
/banlist 需要 vup.moderator(可通过 permissions.banlist 配置)
统计权限
/stats(查看自身数据)无需任何权限(可通过 permissions.stats 配置)
/stats <player>(查看他人数据)需要 vup.moderator(可通过 permissions.stats_others 配置)
/leaderboard 无需任何权限(可通过 permissions.leaderboard 配置)
管理员权限
/vup 需要 vup.admin(可通过 permissions.vup 配置)
配置权限
编辑 config.toml 中的 [permissions] 部分以自定义权限节点:
[permissions]
gban = "myserver.admin.ban" # /gban 的自定义权限
stats = "myserver.stats.view" # /stats 所需的权限
lobby = "" # 空字符串 = 无需权限
与 LuckPerms 配合使用
LuckPerms 命令示例:
# 授予管理员权限
/lp group admin permission set vup.admin true
# 授予管理权限
/lp group moderator permission set vup.moderator true
# 授予高级玩家访问权限
/lp user PlayerName permission set vup.premium true
# 允许所有玩家使用统计功能
/lp group default permission set vup.stats true
有关 LuckPerms 的详细权限设置指南,请参阅权限指南。
常见问题
数据库连接失败
- 验证
config.toml 中的数据库凭据是否正确
- 确保数据库服务器正在运行且可访问
- 检查防火墙设置,允许数据库端口(默认 3306)的连接
- 确认数据库和用户已创建
玩家未均衡分配
- 验证
config.toml 中的大厅服务器名称是否与 velocity.toml 中的名称完全匹配(区分大小写)
- 确认大厅服务器处于在线状态并正常响应
- 检查 Velocity 代理日志中的连接错误或警告
命令无效
- 验证玩家是否拥有所需权限(检查
config.toml 中的权限部分)
- 对于数据库命令(
/stats, /leaderboard),确保数据库已启用并连接
- 对于封禁命令,检查
config.toml 中是否启用了 database_bans 功能
统计数据未记录
- 确保
config.toml 中设置了 database.enabled 为 true
- 验证
database.features.playtime_tracking 已启用
- 检查数据库连接是否正常工作
- 查看日志以排查任何数据库错误
如需更多详细的故障排除步骤,请参阅 TROUBLESHOOTING.md。
贡献代码
欢迎贡献!若要为本项目做出贡献:
- Fork 本仓库
- 创建功能分支:
git checkout -b feature/your-feature-name
- 进行修改并提交:
git commit -m 'Add some feature'
- 推送到你的分支:
git push origin feature/your-feature-name
- 提交 Pull Request
请确保你的代码遵循现有的代码风格,并包含适当的文档。
支持
如果遇到任何问题或有疑问:
- 查看仓库中的文档文件
- 在 GitHub 上提交一个包含详细问题信息的 Issue
报告问题时,请包括:
- 插件版本
- Velocity 版本
- Java 版本
- 相关日志片段
- 重现问题的步骤
许可证
本项目采用 MIT License 授权。
致谢
更新日志
Alpha-0.1 (当前版本)
- 集成 MySQL/MariaDB 数据库支持
- 玩家游戏时长追踪及分服务器统计
- 基于数据库的全局封禁系统(支持离线操作)
- 自定义成就的统计追踪
- 游戏时长排行榜系统
- 智能大厅均衡分配(支持离线检测)
- 高级玩家路由至专用服务器
- 可配置的权限系统
- 服务器邀请系统
- bStats 指标集成
计划中的功能
- 好友系统(数据库结构已就绪)
- 额外的统计追踪选项
- 增强的管理员工具
用 ❤️ 为 Minecraft 社区打造
A comprehensive Velocity proxy plugin that provides intelligent lobby balancing, premium player routing, database-backed player statistics, and advanced moderation features.
Features
Smart Lobby Management
- Intelligent Load Balancing: Automatically distributes players across multiple lobby servers based on current player counts
- Premium Player Routing: Dedicated lobby and challenge servers for premium/creator players
- Offline Server Detection: Automatically detects and avoids offline servers when balancing
- Server Status Caching: Efficient server status checking to minimize performance impact
Database Integration
- Player Playtime Tracking: Track total playtime and per-server statistics
- Custom Statistics: Track challenges completed and other custom player achievements
- Database-Backed Bans: Offline ban support with MySQL/MariaDB backend
- Connection Pool Management: Efficient HikariCP connection pooling
Moderation Features
- Database Bans: Ban players even when they're offline
- Ban Management Commands: Easy-to-use commands for banning, unbanning, and viewing bans
- Configurable Permissions: Fine-grained permission system for all commands
Player Statistics
- Leaderboards: View top players by playtime
- Personal Stats: Players can check their own statistics
- Challenge Tracking: Track and record challenge completions
Metrics and Monitoring
- bStats Integration: Anonymous usage statistics
- Comprehensive Logging: Detailed logging for debugging and monitoring
Requirements
- Velocity proxy server version 3.4.0 or higher
- Java 17 or higher
- MySQL 8.0+ or MariaDB 10.5+ (optional, required for database features)
Installation
- Download the latest VelocityUtilsPlus.jar from the Releases page
- Copy the JAR file to your Velocity plugins folder
- Start your Velocity server to generate the default configuration
- Stop the server and configure
plugins/velocityutilsplus/config.toml
- If using database features, set up your database (see Database Setup section below)
- Restart your Velocity server
Configuration
The plugin will generate a config.toml file in plugins/velocityutilsplus/. Key configuration sections include:
Lobby Configuration
[lobbies]
# List your regular lobby servers (must match names in velocity.toml)
regular_lobbies = ["Lobby 1", "Lobby 2", "Lobby 3", "Lobby 4"]
# Premium player servers
premium_lobby = "Creator Lobby"
premium_challenge = "Creator Challenge"
Database Configuration
[database]
# Enable database integration
enabled = true
type = "mysql" # or "mariadb"
address = "127.0.0.1:3306"
database = "vup"
username = "vup_user"
password = "your_secure_password"
# Connection pool settings
max_pool_size = 10
min_idle = 2
connection_timeout = 30000
[database.features]
playtime_tracking = true
statistics_tracking = true
friends_system = false # Not yet implemented
database_bans = true
Permissions Configuration
[permissions]
# Define which permissions are required for each command
# Set to empty string "" to allow everyone to use the command
gban = "vup.admin"
gunban = "vup.admin"
banlist = "vup.moderator"
stats = "" # Everyone can use /stats
stats_others = "vup.moderator" # Permission to view other players' stats
leaderboard = "" # Everyone can use /leaderboard
vup = "vup.admin"
lobby = "" # Everyone can use /lobby
creator = "vup.premium" # Premium players only
invite = "" # Everyone can invite
accept = "" # Everyone can accept invites
See config.toml.example for a complete configuration template.
Database Setup
If you want to use database features, you need to set up a MySQL or MariaDB database.
Step 1: Create Database and User
CREATE DATABASE vup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'vup_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON vup.* TO 'vup_user'@'localhost';
FLUSH PRIVILEGES;
Step 2: Configure Plugin
Update the database section in config.toml with your credentials. The plugin will automatically create all required tables on first startup when database is enabled.
Step 3: Optional Manual Schema Import
If you prefer to create the schema manually, you can import database-setup.sql.
For more details, see:
Commands
All commands are configurable with permissions in config.toml.
Navigation Commands
| Command |
Aliases |
Description |
Default Permission |
/lobby |
None |
Connect to a balanced lobby server |
None (everyone) |
/creator |
None |
Connect to the creator/premium lobby |
vup.premium |
/invite <player> |
None |
Invite a player to your current server |
None (everyone) |
/accept |
None |
Accept a pending server invite |
None (everyone) |
Moderation Commands
| Command |
Description |
Default Permission |
Notes |
/gban <player> <reason> |
Ban a player globally |
vup.admin |
Works offline if database bans enabled |
/gunban <player> |
Unban a player globally |
vup.admin |
Works offline if database bans enabled |
/banlist [page] |
View all active bans |
vup.moderator |
Paginated list |
Statistics Commands
| Command |
Aliases |
Description |
Default Permission |
Requires Database |
/stats [player] |
None |
View playtime statistics |
None (everyone) |
Yes |
/leaderboard [limit] |
/lb, /top |
View playtime leaderboard |
None (everyone) |
Yes |
Admin Commands
| Command |
Description |
Default Permission |
/vup |
Plugin information and management |
vup.admin |
Statistics Command Details
/stats [player]
- Without arguments: View your own statistics
- With player name: View another player's statistics (requires
vup.moderator permission by default)
- Displays: Total playtime, per-server playtime, challenges completed
/leaderboard [limit]
- Without arguments: Shows top 10 players
- With number: Shows top N players (maximum 50)
- Displays players ranked by total playtime
Permissions
The plugin uses a flexible permission system where all permissions can be customized in config.toml.
Default Permission Nodes
Navigation Permissions
- No permission required for
/lobby (configurable via permissions.lobby)
vup.premium for /creator (configurable via permissions.creator)
- No permission required for
/invite (configurable via permissions.invite)
- No permission required for
/accept (configurable via permissions.accept)
Moderation Permissions
vup.admin for /gban (configurable via permissions.gban)
vup.admin for /gunban (configurable via permissions.gunban)
vup.moderator for /banlist (configurable via permissions.banlist)
Statistics Permissions
- No permission required for
/stats (view own stats) (configurable via permissions.stats)
vup.moderator for /stats <player> (view others' stats) (configurable via permissions.stats_others)
- No permission required for
/leaderboard (configurable via permissions.leaderboard)
Admin Permissions
vup.admin for /vup (configurable via permissions.vup)
Configuring Permissions
Edit the [permissions] section in config.toml to customize permission nodes:
[permissions]
gban = "myserver.admin.ban" # Custom permission for /gban
stats = "myserver.stats.view" # Require permission for /stats
lobby = "" # Empty string = no permission required
Using with LuckPerms
Example LuckPerms commands:
# Grant admin permissions
/lp group admin permission set vup.admin true
# Grant moderator permissions
/lp group moderator permission set vup.moderator true
# Grant premium player access
/lp user PlayerName permission set vup.premium true
# Allow all players to use stats
/lp group default permission set vup.stats true
For detailed permission setup with LuckPerms, see the permissions guide.
Common Issues
Database Connection Failures
- Verify database credentials in config.toml are correct
- Ensure the database server is running and accessible
- Check firewall settings to allow connections on the database port (default 3306)
- Confirm the database and user have been created
Players Not Being Balanced
- Verify lobby server names in config.toml match exactly with names in velocity.toml (case-sensitive)
- Confirm that lobby servers are online and responding
- Check the Velocity proxy logs for connection errors or warnings
Commands Not Working
- Verify the player has the required permission (check config.toml permissions section)
- For database commands (/stats, /leaderboard), ensure database is enabled and connected
- For ban commands, check if database_bans feature is enabled in config.toml
Statistics Not Tracking
- Ensure database.enabled is set to true in config.toml
- Verify database.features.playtime_tracking is enabled
- Check database connection is working
- Review logs for any database errors
For more detailed troubleshooting steps, see TROUBLESHOOTING.md.
Contributing
Contributions are welcome! To contribute to this project:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature-name
- Make your changes and commit them:
git commit -m 'Add some feature'
- Push to your branch:
git push origin feature/your-feature-name
- Open a Pull Request
Please ensure your code follows the existing code style and includes appropriate documentation.
Support
If you encounter any issues or have questions:
- Check the documentation files in the repository
- Open an Issue on GitHub with detailed information about your problem
When reporting issues, please include:
- Plugin version
- Velocity version
- Java version
- Relevant log excerpts
- Steps to reproduce the issue
License
This project is licensed under the MIT License.
Credits
Changelog
Alpha-0.1 (Current Release)
- Database integration with MySQL/MariaDB support
- Player playtime tracking with per-server statistics
- Global ban system with offline support via database
- Statistics tracking for custom achievements
- Leaderboard system for playtime rankings
- Smart lobby balancing with offline detection
- Premium player routing to dedicated servers
- Configurable permission system
- Server invite system
- bStats metrics integration
Planned Features
- Friends system (database structure ready)
- Additional statistics tracking options
- Enhanced admin tools
Made with ❤️ for the Minecraft community
评论 0
登录后参与评分
还没有评论,来抢沙发吧