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

1. Download the latest VelocityUtilsPlus.jar from the Releases page
2. Copy the JAR file to your Velocity plugins folder
3. Start your Velocity server to generate the default configuration
4. Stop the server and configure plugins/velocityutilsplus/config.toml
5. If using database features, set up your database (see Database Setup section below)
6. 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:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and commit them: git commit -m 'Add some feature'
4. Push to your branch: git push origin feature/your-feature-name
5. 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