A comprehensive Velocity proxy plugin that provides intelligent lobby balancing, premium player routing, database-backed player statistics, and advanced moderation features.<\/p>\n
\n<\/p>\n
**Features**<\/p>\n
**Smart Lobby Management**
\n– Intelligent Load Balancing: Automatically distributes players across multiple lobby servers based on current player counts
\n– Premium Player Routing: Dedicated lobby and challenge servers for premium\/creator players
\n– Offline Server Detection: Automatically detects and avoids offline servers when balancing
\n– Server Status Caching: Efficient server status checking to minimize performance impact<\/p>\n
**Database Integration**
\n– Player Playtime Tracking: Track total playtime and per-server statistics
\n– Custom Statistics: Track challenges completed and other custom player achievements
\n– Database-Backed Bans: Offline ban support with MySQL\/MariaDB backend
\n– Connection Pool Management: Efficient HikariCP connection pooling<\/p>\n
**Moderation Features**
\n– Database Bans: Ban players even when they’re offline
\n– Ban Management Commands: Easy-to-use commands for banning, unbanning, and viewing bans
\n– Configurable Permissions: Fine-grained permission system for all commands<\/p>\n
**Player Statistics**
\n– Leaderboards: View top players by playtime
\n– Personal Stats: Players can check their own statistics
\n– Challenge Tracking: Track and record challenge completions<\/p>\n
**Metrics and Monitoring**
\n– bStats Integration: Anonymous usage statistics
\n– Comprehensive Logging: Detailed logging for debugging and monitoring<\/p>\n
**Requirements**<\/p>\n
– Velocity proxy server version 3.4.0 or higher
\n– Java 17 or higher
\n– MySQL 8.0+ or MariaDB 10.5+ (optional, required for database features)<\/p>\n
**Installation**<\/p>\n
1. Download the latest VelocityUtilsPlus.jar from the Releases page
\n2. Copy the JAR file to your Velocity plugins folder
\n3. Start your Velocity server to generate the default configuration
\n4. Stop the server and configure `plugins\/velocityutilsplus\/config.toml`
\n5. If using database features, set up your database (see Database Setup section below)
\n6. Restart your Velocity server<\/p>\n
## Configuration<\/p>\n
The plugin will generate a config.toml file in `plugins\/velocityutilsplus\/`. Key configuration sections include:<\/p>\n
**Lobby Configuration**<\/p>\n
“`toml
\n[lobbies]
\n# List your regular lobby servers (must match names in velocity.toml)
\nregular_lobbies = [“Lobby 1”, “Lobby 2”, “Lobby 3”, “Lobby 4”]<\/p>\n
# Premium player servers
\npremium_lobby = “Creator Lobby”
\npremium_challenge = “Creator Challenge”
\n“`<\/p>\n
**Database Configuration**<\/p>\n
“`toml
\n[database]
\n# Enable database integration
\nenabled = true
\ntype = “mysql” # or “mariadb”
\naddress = “127.0.0.1:3306”
\ndatabase = “vup”
\nusername = “vup_user”
\npassword = “your_secure_password”<\/p>\n
# Connection pool settings
\nmax_pool_size = 10
\nmin_idle = 2
\nconnection_timeout = 30000<\/p>\n
[database.features]
\nplaytime_tracking = true
\nstatistics_tracking = true
\nfriends_system = false # Not yet implemented
\ndatabase_bans = true
\n“`<\/p>\n
**Permissions Configuration**<\/p>\n
“`toml
\n[permissions]
\n# Define which permissions are required for each command
\n# Set to empty string “” to allow everyone to use the command
\ngban = “vup.admin”
\ngunban = “vup.admin”
\nbanlist = “vup.moderator”
\nstats = “” # Everyone can use \/stats
\nstats_others = “vup.moderator” # Permission to view other players’ stats
\nleaderboard = “” # Everyone can use \/leaderboard
\nvup = “vup.admin”
\nlobby = “” # Everyone can use \/lobby
\ncreator = “vup.premium” # Premium players only
\ninvite = “” # Everyone can invite
\naccept = “” # Everyone can accept invites
\n“`<\/p>\n
See `config.toml.example` for a complete configuration template.<\/p>\n
**Database Setup**<\/p>\n
If you want to use database features, you need to set up a MySQL or MariaDB database.<\/p>\n
**Step 1: Create Database and User**<\/p>\n
“`sql
\nCREATE DATABASE vup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
\nCREATE USER ‘vup_user’@’localhost’ IDENTIFIED BY ‘your_secure_password’;
\nGRANT ALL PRIVILEGES ON vup.* TO ‘vup_user’@’localhost’;
\nFLUSH PRIVILEGES;
\n“`<\/p>\n
**Step 2: Configure Plugin**<\/p>\n
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.<\/p>\n
**Step 3: Optional Manual Schema Import**<\/p>\n
If you prefer to create the schema manually, you can import `database-setup.sql`.<\/p>\n
For more details, see:
\n– DATABASE-GUIDE.md – Complete database setup and configuration guide
\n– DATABASE-IMPLEMENTATION.md – Technical implementation details<\/p>\n
**Commands**<\/p>\n
All commands are configurable with permissions in config.toml.<\/p>\n
**Navigation Commands**<\/p>\n
| Command | Aliases | Description | Default Permission | **Moderation Commands**<\/p>\n | Command | Description | Default Permission | Notes | **Statistics Commands**<\/p>\n | Command | Aliases | Description | Default Permission | Requires Database | **Admin Commands**<\/p>\n | Command | Description | Default Permission | **Statistics Command Details**<\/p>\n **`\/stats [player]`** **`\/leaderboard [limit]`** **Permissions**<\/p>\n The plugin uses a flexible permission system where all permissions can be customized in config.toml.<\/p>\n **Default Permission Nodes**<\/p>\n *Navigation Permissions* *Moderation Permissions* *Statistics Permissions* *Admin Permissions* **Configuring Permissions**<\/p>\n Edit the `[permissions]` section in config.toml to customize permission nodes:<\/p>\n “`toml **Using with LuckPerms**<\/p>\n Example LuckPerms commands:<\/p>\n “` # Grant moderator permissions # Grant premium player access # Allow all players to use stats For detailed permission setup with LuckPerms, see the permissions guide.<\/p>\n **Common Issues**<\/p>\n *Database Connection Failures* *Players Not Being Balanced* *Commands Not Working* *Statistics Not Tracking* For more detailed troubleshooting steps, see TROUBLESHOOTING.md.<\/p>\n **Contributing**<\/p>\n Contributions are welcome! To contribute to this project:<\/p>\n 1. Fork the repository Please ensure your code follows the existing code style and includes appropriate documentation.<\/p>\n **Support**<\/p>\n If you encounter any issues or have questions: When reporting issues, please include: **License**<\/p>\n This project is licensed under the MIT License.<\/p>\n **Credits**<\/p>\n – Metrics: Powered by bStats **Changelog**<\/p>\n **Alpha-0.1 (Current Release)** **Planned Features** —<\/p>\n Made with \u2764\ufe0f for the Minecraft community<\/p>\n","protected":false},"excerpt":{"rendered":" Utils that improve Velocity like load balancing, invites and improved perms. Including premium \/ priority balancing!<\/p>\n","protected":false},"featured_media":165638,"template":"","meta":{"_minecraft_slug":"velocityutilsplus","_minecraft_project_id":"Y9Wr5X3I","_minecraft_author":"link_1503","_minecraft_license":"MIT","_minecraft_downloads":46,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"velocityutilsplus.zip","_minecraft_size_bytes":18773340,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-15T21:19:43.389304Z","_minecraft_date_created":"2026-01-29T21:53:25.621785Z","_minecraft_date_modified":"2026-01-26T16:20:42.462786Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/velocityutilsplus","_minecraft_icon_attachment_id":165638,"_minecraft_imported_at":"2026-06-09T17:55:41+00:00","_minecraft_import_hash":"445da27c6041d7fe62c83b48d710a41a","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,867,123,92,985],"mod_loader":[986],"minecraft_version":[449,110,111,112,113,114,115,116,117,118,119,120,46,47,48,49,50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-165637","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-social","mod_category-technology","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-13-2","minecraft_version-1-14","minecraft_version-1-14-1","minecraft_version-1-14-2","minecraft_version-1-14-3","minecraft_version-1-14-4","minecraft_version-1-15","minecraft_version-1-15-1","minecraft_version-1-15-2","minecraft_version-1-16","minecraft_version-1-16-1","minecraft_version-1-16-2","minecraft_version-1-16-3","minecraft_version-1-16-4","minecraft_version-1-16-5","minecraft_version-1-17","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n|———|———|————-|——————-|
\n| `\/lobby` | None | Connect to a balanced lobby server | None (everyone) |
\n| `\/creator` | None | Connect to the creator\/premium lobby | `vup.premium` |
\n| `\/invite
\n| `\/accept` | None | Accept a pending server invite | None (everyone) |<\/p>\n
\n|———|————-|——————-|——-|
\n| `\/gban
\n| `\/gunban
\n| `\/banlist [page]` | View all active bans | `vup.moderator` | Paginated list |<\/p>\n
\n|———|———|————-|——————-|——————|
\n| `\/stats [player]` | None | View playtime statistics | None (everyone) | Yes |
\n| `\/leaderboard [limit]` | `\/lb`, `\/top` | View playtime leaderboard | None (everyone) | Yes |<\/p>\n
\n|———|————-|——————-|
\n| `\/vup` | Plugin information and management | `vup.admin` |<\/p>\n
\n– Without arguments: View your own statistics
\n– With player name: View another player’s statistics (requires `vup.moderator` permission by default)
\n– Displays: Total playtime, per-server playtime, challenges completed<\/p>\n
\n– Without arguments: Shows top 10 players
\n– With number: Shows top N players (maximum 50)
\n– Displays players ranked by total playtime<\/p>\n
\n– No permission required for `\/lobby` (configurable via `permissions.lobby`)
\n– `vup.premium` for `\/creator` (configurable via `permissions.creator`)
\n– No permission required for `\/invite` (configurable via `permissions.invite`)
\n– No permission required for `\/accept` (configurable via `permissions.accept`)<\/p>\n
\n– `vup.admin` for `\/gban` (configurable via `permissions.gban`)
\n– `vup.admin` for `\/gunban` (configurable via `permissions.gunban`)
\n– `vup.moderator` for `\/banlist` (configurable via `permissions.banlist`)<\/p>\n
\n– No permission required for `\/stats` (view own stats) (configurable via `permissions.stats`)
\n– `vup.moderator` for `\/stats
\n– No permission required for `\/leaderboard` (configurable via `permissions.leaderboard`)<\/p>\n
\n– `vup.admin` for `\/vup` (configurable via `permissions.vup`)<\/p>\n
\n[permissions]
\ngban = “myserver.admin.ban” # Custom permission for \/gban
\nstats = “myserver.stats.view” # Require permission for \/stats
\nlobby = “” # Empty string = no permission required
\n“`<\/p>\n
\n# Grant admin permissions
\n\/lp group admin permission set vup.admin true<\/p>\n
\n\/lp group moderator permission set vup.moderator true<\/p>\n
\n\/lp user PlayerName permission set vup.premium true<\/p>\n
\n\/lp group default permission set vup.stats true
\n“`<\/p>\n
\n– Verify database credentials in config.toml are correct
\n– Ensure the database server is running and accessible
\n– Check firewall settings to allow connections on the database port (default 3306)
\n– Confirm the database and user have been created<\/p>\n
\n– Verify lobby server names in config.toml match exactly with names in velocity.toml (case-sensitive)
\n– Confirm that lobby servers are online and responding
\n– Check the Velocity proxy logs for connection errors or warnings<\/p>\n
\n– Verify the player has the required permission (check config.toml permissions section)
\n– For database commands (\/stats, \/leaderboard), ensure database is enabled and connected
\n– For ban commands, check if database_bans feature is enabled in config.toml<\/p>\n
\n– Ensure database.enabled is set to true in config.toml
\n– Verify database.features.playtime_tracking is enabled
\n– Check database connection is working
\n– Review logs for any database errors<\/p>\n
\n2. Create a feature branch: `git checkout -b feature\/your-feature-name`
\n3. Make your changes and commit them: `git commit -m ‘Add some feature’`
\n4. Push to your branch: `git push origin feature\/your-feature-name`
\n5. Open a Pull Request<\/p>\n
\n– Check the documentation files in the repository
\n– Open an Issue on GitHub with detailed information about your problem<\/p>\n
\n– Plugin version
\n– Velocity version
\n– Java version
\n– Relevant log excerpts
\n– Steps to reproduce the issue<\/p>\n
\n– Database: HikariCP connection pooling
\n– Built for: Velocity Proxy<\/p>\n
\n– Database integration with MySQL\/MariaDB support
\n– Player playtime tracking with per-server statistics
\n– Global ban system with offline support via database
\n– Statistics tracking for custom achievements
\n– Leaderboard system for playtime rankings
\n– Smart lobby balancing with offline detection
\n– Premium player routing to dedicated servers
\n– Configurable permission system
\n– Server invite system
\n– bStats metrics integration<\/p>\n
\n– Friends system (database structure ready)
\n– Additional statistics tracking options
\n– Enhanced admin tools<\/p>\n