VelocityWebConsole

# VelocityWebConsole

**Control your Velocity proxy from anywhere via a web browser.** No SSH, no external web server — just drop the plugin and open a URL. Perfect for VPS setups where you don’t have direct terminal access.

**_NOTE THIS PLUGIN IS NEW AND UNDER ACTIVE DEVELOPMENT, EXPECT BUGS. PLEASE REPORT THEM TO THE PROVIDED DISCORD CHANNEL UNDER #plugin-help_**

—

## 🟢 SUPER Easy setup & use

– **No external server** — The plugin runs its own web server. No Apache, nginx, or database to install or configure.
– **Three steps** — Drop the jar in `plugins/`, restart Velocity, then open `http://YOUR_SERVER_IP:25580/` in a browser. That’s it.
– **Sensible defaults** — Port **25580**, log file auto-detected. You only need to edit `config.properties` if you want a different port or to bind to localhost.
– **First login** — Log in with **admin** / **admin**, set a new password when prompted, and you’re in. Add more users (admin/viewer) from the **Users** page if you like.

—

![VelocityWebConsole](https://i.imgur.com/izCzVrb.png)

—

## ✨ Features

– **Live console view** — See your proxy’s console output in real time, streamed straight to the browser.
– **Run commands** — Execute any Velocity console command from the web UI.
– **User management** — Create multiple users with **Admin** (full control) or **Viewer** (read-only console, no command execution) roles.
– **Secure by default** — Passwords are stored hashed (PBKDF2) in `users.json`.
– **HTTPS support** — Serve the console over TLS. Set `use_https=true` in config and provide a keystore (PKCS12 or JKS). Use a certificate from **Let’s Encrypt** (or another CA) for your domain to avoid browser “Not secure” warnings; self-signed certs work but require clicking “Advanced → Proceed” once per browser. When using HTTPS, the session cookie is `Secure` and responses send **HSTS** so browsers stick to HTTPS. Optional **HTTP redirect**: set `redirect_http_port` so users can type `http://yourserver:25580` and get redirected to `https://yourserver:25581` (see config comments).

—

## ⚙️ Configuration

Edit `plugins/velocitywebconsole/config.properties` and restart the proxy for changes to take effect.

—

## 🔒 Security tips

– **Change the default password** on first use.
– Prefer `bind_address=127.0.0.1` and use SSH port forwarding if you only need access from your own machine.
– Don’t expose the web console port to the internet without a firewall or strong passwords.

—

## 📋 Requirements

– **Velocity** 3.4.x – 3.5.x proxy, built on 3.4.x API (tested on 3.5.x)
– **Java 17+**

—

VelocityVersionBouncer

# VelocityVersionBouncer
**A simple and fully automated way to connect players to the correct server based on their game version.**

**VelocityVersionBouncer** is a plugin for the [Velocity proxy](https://papermc.io/software/velocity) (tested on version 3.4) that automatically selects the most compatible backend server for a connecting player, based on their protocol version (Minecraft game version).

—
### 🔧 How It Works
– Everytime a client connects to your proxy the plugin will check all the registered servers and compare their protocol versions (game versions).
– By default, the first server that matches will be selected (you can change that in the config).
– There is a config.toml file located in the plugins folder (`plugins/VelocityVersionBouncer/config.toml`).
– In the config itself each option is pretty well explained (nevertheless I’ll include an example config.toml at the end of this README).
– Optional features include: a fallback functionality as well as comparing versions for server list pings.
### ❓ Questions you may have:
– **Is this also triggered when changing servers via `/server`?** No, the version checking is only triggered when connecting initially (from the multiplayer server list) or when using the fallback functionality.
– **What happens if no compatible server is found?** The client will simply be disconnected with the according note/reason.
– **Does this work with modded minecraft servers?** If you’re using setups like Ambassador+ProxyCompatibleForge [(more information)](https://docs.papermc.io/velocity/server-compatibility) this plugin will route the client based purely on their protocol version (game version), not their installed mods. _Note: This setup has only been tested with PaperMC and (Neo)Forge servers._
### 📦 Installation & 🛠️ Requirements
1. Download the `.jar` file of the last stable release ([here](https://github.com/Hallo5000/VelocityVersionBouncer/blob/master/build/libs/VelocityVersionBouncer-1.5.0-release.jar)) or build it yourself (the gradle files are included).
2. Put the file in your servers `plugins/` folder (only the proxy!) and restart the server once to generate the config file.
3. When you’re finished editing the config restart the proxy once more and everything should be working.
_Note: this plugin may not work properly if you are not running on `Java 21` (or higher) and `Velocity 3.4.0` or above_
4. If you’re having problems: make sure you’re not using a snapshot (as these are expected to be unstable and this README is always explaining the latest release anyway), if there’s still a problem feel free to open an issue on the plugins GitHub repository.

## Example Config:
“`toml
# This config is used to determine how and if servers are checked for their protocol versions whenever a client tries to connect to a backend server (and optionally if they lost connection)

# ‘whitelist’ is a string array of server names to check for their protocol version when a client tries to connect.
# leaving this empty is equal to putting all registered servers in
# Example: [“server1”, “server2”]
# Note: spaces outside the strings will be ignored.
whitelist = [“lobby1”, “lobby2”, “fun-minigame”, “devServer”]

# ‘blacklist’ is an array of strings to exclude from the temporary list of servers during version comparison.
# first the whitelist is added and then all servers contained in the blacklist are removed from that temporary list.
blacklist = [“devServer”]

# If enabled this option ensures that joining players will be distributed evenly over all servers
# Options: (case-insensitive)
# “FIRST-MATCH” – players will be sent to the first matching server
# “BALANCED” – players will be evenly distributed over all matching servers
distribution = “FIRST-MATCH”

# This option if set to ‘true’ lets you override verlocity’s way of determining the server list ping response by using the try-list of the config (‘ping-passthrough’)
# instead when a client sends a server ping it will use the same algorithm to determine a matching server as in the joining/fallback process
# be carefully when also using clientbrands in the explicit routings as these can’t be used to match server pings
server-list-ping = false
# This option determines wether to use velocities ping-passthrough when no matching server was found for the ping response
# If set to true, things like the description will probably show but the client shows that the version doesn’t match,
# otherwise the client will display “Can’t connect to server”
# This option will also be ignored if ‘server-list-ping’ is set to false
default-to-ping-passthrough = true

# This defines how often all backend servers get pinged to refresh infos in the plugins ping cache
# in seconds
ping-intervall = 300

# If enabled this option ensures that whenever a client is kicked from a server (whether during login, via /kick, or for another reason),
# they will be automatically redirected (bounced) to another server instead of being disconnected. (obviously if a client disconnects explicitly via leaving the server they will not be redirected)
enable-fallback-bouncing = true
# If set to true, the server the client was kicked from will be temporarily excluded from fallback options,
# preventing the client from being sent back there during fallback-bouncing.
exclude-previous-server = false
# When there is a valid server name in ‘explicit-fallback-server’ the plugin won’t search for a new server and instead only tries the specified server.
# Leave this empty, if you’d like to disable this option (also this is disabled when enable-fallback-bouncing is set to false).
explicit-fallback-server = “lobby”

# —— explicit routing ——
# Syntax
# v1_x_x – game version
# p000 – protocol version (Protocol Versions for every release/snapshot can be found here: https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Protocol_version_numbers)
# cFORGE – Client brand (for example: vanilla, forge, fabric, Geyser (for player joining through GeyserMC), badlion, etc.
# either a game version (v) or a protocol version (p) is necessary but client brands (c) are completely optional
# when no client brand is defined the routing just takes every client joining with the defined game/protocol version
[explicit-routing]
# Example: v1_21_8cFORGE = “lobby-1”
# Example: p123 = “lobby-2”
# Example: cGeyser = “GeyserMC-server”
“`

VelocityUtilsPlus

A comprehensive Velocity proxy plugin that provides intelligent lobby balancing, premium player routing, database-backed player statistics, and advanced moderation features.

[![Java Version](https://img.shields.io/badge/Java-17+-orange.svg)](https://www.oracle.com/java/)
[![Velocity API](https://img.shields.io/badge/Velocity-3.4.0-blue.svg)](https://papermc.io/software/velocity)

**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**

“`toml
[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**

“`toml
[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**

“`toml
[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**

“`sql
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](https://github.com/JuliaKnoth/VelocityUtilPlus/blob/main/DATABASE-GUIDE.md) – Complete database setup and configuration guide
– [DATABASE-IMPLEMENTATION.md](https://github.com/JuliaKnoth/VelocityUtilPlus/blob/main/DATABASE-IMPLEMENTATION.md) – Technical implementation details

**Commands**

All commands are configurable with permissions in config.toml.

**Navigation Commands**

**Moderation Commands**

**Statistics Commands**

**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 ` (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:

“`toml
[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](https://github.com/JuliaKnoth/VelocityUtilPlus/blob/main/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](https://github.com/JuliaKnoth/VelocityUtilPlus/issues) 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](https://bstats.org/)
– Database: [HikariCP](https://github.com/brettwooldridge/HikariCP) connection pooling
– Built for: [Velocity Proxy](https://papermc.io/software/velocity)

**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

VelocityUtils

![Portada](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/portada2.png?raw=true)

VelocityUtils is a plugin designed for Velocity proxy servers that adds essential utilities for both players and server administrators. It aims to simplify network management with useful, configurable, and easy-to-use features.

![Features](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/features.png?raw=true)

[![Dependencies](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/dependencies2.png?raw=true)](https://rexi666-plugins.gitbook.io/rexi666/velocityutils/installation)

![Screenshots](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/screenshots.png?raw=true)

[![Commands and Permissions](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/commands%20and%20permissions2.png?raw=true)]([https://rexi666-plugins.gitbook.io/rexi666](https://rexi666-plugins.gitbook.io/rexi666/velocityutils/commands-and-permissions))

| [![Wiki](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/wiki.png?raw=true)](https://rexi666-plugins.gitbook.io/rexi666) | [![Discord](https://github.com/Rexi666/VelocityUtils/blob/main/Wiki/Images/plugin/discord.png?raw=true)](https://discord.com/invite/a3zkKtrjTr) |
|—|—|

VelocityTransfer

# VelocityTransfer

**VelocityTransfer** is a simple Velocity plugin that adds the `/transfer` command to velocity.

—
### Command

“`
/transfer [player | local | all]
“`

* Transfers the sender to the specified server by default.
* `player`: Transfers the specified player (requires `proxytransfer.others` permission).
* `local`: Transfers all players on the sender’s current server.
* `all`: Transfers all players on the proxy.

—
### Permissions

* `proxytransfer.others` — Required to transfer other players.

—

VelocityTools

# Available commands

– /alert
– /find
– /send
– /hub (You can change aliases in config)
– /vtools

# Available tools

– Protocol Blocker (prohibits connection from certain versions)
– Hostnames Manager (denies connection from a specific hostname, see details below)
– Brand Changer aka Brand Rewriter (changes brand in game and in ping requests)

# Permissions

– In config

VelocityTitle

# VelocityTitle

**VelocityTitle** is a title plugin designed for **Minecraft Velocity networks**.

It stores and manages player title data on the **Velocity proxy**, then synchronizes data between the proxy and backend servers through plugin messaging channels. Titles can finally be displayed on backend servers through **PlaceholderAPI**, with **GUI support planned** for future versions.

This project is mainly intended to provide an **open-source and free solution** for cross-server title systems, especially for server networks that want to share prefixes, suffixes, and title data across multiple backend servers.

## Features

– Designed for Velocity server networks
– Centralized title data management on the Velocity proxy
– Cross-server synchronization
– PlaceholderAPI support for displaying prefix and suffix
– Supports creating, editing, deleting, granting, revoking, and wearing titles
– Command confirmation system for safer management
– Open-source and free to use

## Installation

1. Download the correct plugin build for your platform
2. Install the plugin on the corresponding server
3. **Velocity installation is required**, otherwise the plugin will not work
4. Complete the configuration according to the config files
5. If you want to display titles, use these PAPI placeholders:
– `velocitytitle_prefix`
– `velocitytitle_suffix`

## Notes

– `core` is not a standalone plugin and cannot be installed directly
– `reload` is currently unstable and not recommended
– Title names should only use English letters and underscores
– You can wrap display text in double quotes to input Chinese or other spaced text

## Links

– GitHub:
– Issues:
– Releases:

VelocityTelegramBridge

# Velocity Telegram Bridge

## Features

– Forwards chat messages from Telegram to Minecraft and vice versa.
– Configurable message formats for different events such as join, leave, and server change.

## Commands and Permissions

The plugin provides the following commands:

– `/vtb reload`: Reads and reloads the plugin configuration from the `config.toml` file. Requires `vtb.reload` permission.

## Installation

1. Download the latest version of the plugin.
2. Place the downloaded jar file into your Velocity `plugins` folder.
3. Restart your Velocity proxy.
4. The plugin will generate a default `config.toml` file inside `velocity-telegram-bridge` folder. Modify this file with your Telegram API credentials and desired settings.
5. Restart your Velocity proxy or reload the plugin with `/vtb reload` command.

### Note
> ℹ️ If you want to handle death and advancement messages, you need to install [YepLib](https://github.com/unilock/YepLib) plugin on velocity and [YepTwo](https://github.com/unilock/YepTwo) mod for backend servers

## Configuration

The `config.toml` file contains the following sections:

– `Telegram`: Contains the token and chat_id for your Telegram bot.
– `Events`: Contains the message formats for different events. You can enable or disable each event and customize the message format.

This is the default configuration:

“`toml
#Telegram bot api configuration
[Telegram]
#Telegram bot api token
token = “0:ABCDEFG”
#Telegram chat id to send messages to
chat_id = 0
#Events configuration
[Events]
#Should messages from chat be sent to the chat?
message_enabled = true
#Format of the message
#Available placeholders: {player}, {message}
message_format = “{player}: {message}”
#Should messages from telegram be sent to the server?
message_from_telegram_enabled = true
#Format of the message
#Available placeholders: {author}, {message}
message_from_telegram_format = “{author}: {message}”
#Should join messages be sent to the chat?
join_enabled = true
#Format of the message
#Available placeholders: {player}
join_format = “{player} joined the server”
#Should leave messages be sent to the chat?
leave_enabled = true
#Format of the message
#Available placeholders: {player}
leave_format = “{player} left the server”
#Should server change messages be sent to the chat?
server_change_enabled = true
#Format of the message
#Available placeholders: {server}, {new_server}, {player}
server_change_format = “{player} moved from {server} to {new_server}”
#Should status messages be sent to the chat?
status_enabled = true
#Format of the message
#Available placeholders: {player_count}, {players}
status_format = “There are {player_count} players online:n{players}”
#Should death messages be sent to the chat?
#Note: This requires YepLib installed on velocity and YepTwo on backend servers
death_enabled = true
#Format of the message
#Available placeholders: {death_message}
death_format = “{death_message}”
#Should advancement messages be sent to the chat?
advancement_enabled = true
#Format of the message
#Available placeholders: {player}, {advancement_title}, and {advancement_description}
advancement_format = “{player} has made the advancement {advancement_title}n{advancement_description}”
“`

VelocitySlots

# VelocitySlots

VelocitySlots is a simple Velocity (and BungeeCord) plugin that **fakes the maximum player slots** in your server’s MOTD.

* Supports dynamic slot adjustment based on online players with an offset.
* Can also be set to a static number or an “unlimited” mode.
* Lightweight and requires **no other plugin dependencies**.

—

## Features

* **DYNAMIC mode**: Show `online players + offset` as max slots.
* **STATIC mode**: Always show a fixed maximum slot number.
* Configurable via `config.yml`.

—

## Installation

1. Place the `VelocitySlots.jar` in your `plugins/` folder.
2. Start Velocity — a default `config.yml` will be generated automatically.
3. Stop Velocity and edit `plugins/VelocitySlots/config.yml` as needed.
4. Restart Velocity to apply changes.

—

## Configuration (`config.yml`)

“`yaml
# ———————————————————-
# VelocitySlots Configuration File
# ———————————————————-
# This file allows you to control the “max slots” displayed
# in your server list (the MOTD), without affecting the real
# number of online players.
#
# You can configure static numbers and dynamic slots.
# All settings here only affect the max players shown
# to clients.
#
# Keep in mind, this is fake max slots, meaning if for
# example the max slots of your server is at 200 players,
# the limit will still work.
# ———————————————————-

# ————————
# MAX SLOTS MODE
# ————————
# Choose how the max slots should be displayed.
# Options:
# DYNAMIC -> max slots = online players + offset
# STATIC -> max slots = static-slots value
max-slots-mode: DYNAMIC

# ————————
# DYNAMIC MODE SETTINGS
# ————————
# Only used if max-slots-mode is set to DYNAMIC.
# The plugin will take the real online player count and
# add the offset. This makes the server appear fuller.
# Example: 50 players online + offset 10 => 50/60 shown
offset: 0

# ————————
# STATIC MODE SETTINGS
# ————————
# Only used if max-slots-mode is set to STATIC.
# This number will always be shown as the max slots in the
# server ping, regardless of the actual player count.
# Example: static-slots: 1 will show 20/1 if 20 are online
static-slots: 100

# ————————
# NOTES
# ————————
# 1. Only the max slots value is changed; online players
# always display the real count.
# 2. Offset is ignored in STATIC modes.
# 3. Setting max-slots-mode: DYNAMIC with offset: 0
# simply mirrors the current online count as max slots.
# 4. You can adjust these values at any time; the changes
# will take effect immediately for the next server ping.
“`

—

## Example

If you have **50 players online** and `offset: 10` in FAKE mode:

“`
MOTD: 50/60
“`

VelocityShield

# VelocityShield 🛡️

A powerful VPN detection plugin for Velocity proxy servers that helps protect your network from unwanted VPN connections.

[![License](https://img.shields.io/github/license/jackh54/velocityshield)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://www.oracle.com/java/)
[![Velocity](https://img.shields.io/badge/Velocity-3.4.0-blue.svg)](https://www.velocitypowered.com/)

## Features ✨

– **Dual VPN Detection**: Uses both proxycheck.io and ip-api.com for reliable VPN detection
– **Smart Fallback System**: Automatically switches between services if one fails
– **Efficient Caching**: Reduces API requests with configurable cache duration
– **Whitelist System**: Easily manage trusted IPs
– **Detailed Logging**: Track VPN detection events with timestamps
– **Modern Text Formatting**: Beautiful messages using Adventure’s text components
– **Permission System**: Control access to commands and bypasses
– **Configurable**: Highly customizable through config.yml

## Installation 📥

1. Download the latest release from the [Releases](https://modrinth.com/plugin/velocityshield/versions) page
2. Place the JAR file in your Velocity server’s `plugins` directory
3. Start or restart your Velocity server
4. Configure the plugin in `plugins/velocityshield/config.yml`

## Configuration ⚙️

“`yaml
# API Configuration
proxycheck-api-key: “YOUR_PROXYCHECK_API_KEY”

# VPN Detection Settings
use-proxycheck-as-primary: true
enable-fallback-service: true
allow-join-on-api-failure: true

# Cache Settings
enable-cache: true
cache-duration: 10
cache-time-unit: “SECONDS” # Options: SECONDS, MINUTES, HOURS, DAYS

# Debug Settings
enable-debug: false
“`

## Commands 🎮

### Whitelist Commands
– `/vshieldwhitelist add ` – Add an IP to the whitelist
– `/vshieldwhitelist remove ` – Remove an IP from the whitelist

## Permissions 🔑

## API Integration 🤝

VelocityShield uses two VPN detection services:

1. **proxycheck.io** (Primary)
– Requires API key
– More accurate detection
– Higher rate limits with API key

2. **ip-api.com** (Fallback)
– Free to use
– No API key required
– Lower rate limits

## Performance Optimization 🚀

– **Caching**: Reduces API requests by caching results
– **Rate Limiting**: Prevents API service overload
– **Async Processing**: Non-blocking VPN checks
– **Efficient Cleanup**: Automatic cache maintenance

## Support 💬

– Create an issue for bug reports or feature requests
– Join our [Discord server](https://discord.gg/CzJvE4G5cU) for community support

## Credits

– [Velocity](https://www.velocitypowered.com/) – The proxy server
– [proxycheck.io](https://proxycheck.io/) – Primary VPN detection service
– [ip-api.com](https://ip-api.com/) – Fallback VPN detection service
– [Adventure](https://docs.advntr.dev/) – Text formatting library

—

Made with ❤️ by [PandaDevv](https://github.com/jackh54)

*This plugin uses [bStats](https://bstats.org/plugin/velocity/VelocityShield/25843)*