VelocityUtilsPlus

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:

DATABASE-GUIDE.md - Complete database setup and configuration guide
DATABASE-IMPLEMENTATION.md - Technical implementation details

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

Metrics: Powered by bStats
Database: HikariCP connection pooling
Built for: Velocity Proxy

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

Configuration

Совместимость

Minecraft: Java Edition

Платформы

Поддерживаемые окружения

Ссылки

Создатели

Детали