Velocity

The Maintenance plugin supports Velocity, the modern, high-performance Minecraft proxy from PaperMC.

Requirements

Velocity 3.0 or higher
Java 17 or higher

Installation

Download the latest version from Hangar
Place the JAR file in your Velocity plugins/ directory
Restart your proxy
Configure the plugin in plugins/maintenance/config.yml

Why Velocity?

Velocity offers several advantages over BungeeCord:

Better performance - More efficient packet handling and threading
Modern API - Built on contemporary Java practices
Native Adventure support - Full rich text formatting
Active development - Regular updates from the Paper team

Maintenance takes full advantage of Velocity’s modern architecture.

Proxy Features

Velocity installation provides the same advanced features as BungeeCord:

Global Maintenance

Enable maintenance for your entire network:

/maintenance on

Prevents all players (without bypass permission) from connecting.

Per-Server Maintenance

Enable maintenance for individual backend servers:

/maintenance on <server>
/maintenance off <server>

Players connecting to a server under maintenance will be:

Redirected to a fallback server (if configured)
Disconnected with a custom message (if no fallback)

Fallback Server Configuration

Configure fallback servers in config.yml:

fallback:
  enabled: true
  fallback-list:
    survival: lobby
    creative: hub
    skyblock: lobby

When a player tries to join a maintenance server, they’re automatically sent to the fallback.

Waiting Server

Direct all players to a waiting lobby during global maintenance:

waiting-server:
  enabled: true
  server: waiting

Instead of kicking players, they’ll be sent to your waiting lobby.

Redis Integration

Sync maintenance status across multiple Velocity proxies:

redis:
  enabled: true
  host: localhost
  port: 6379
  password: ""
  channel: maintenance

Essential for multi-proxy networks to keep maintenance status synchronized.

Plugin Integrations

ServerListPlus

Optional dependency - Automatically detected. Enhances server list customization during maintenance mode. Maintenance will automatically disable ServerListPlus when maintenance is enabled.

LuckPerms

Optional dependency - Context support. Maintenance registers maintenance contexts with LuckPerms, allowing you to create conditional permissions.

Velocity-Specific Features

Native Adventure Components

Velocity has native support for Adventure text components. All messages in Maintenance use Adventure’s Component API:

Full RGB color support
Hover events
Click events
Rich formatting options

Configure messages using MiniMessage format:

kick-message: "<red><bold>Server is under maintenance!<br><gray>Check back soon."

Async Event Handling

Velocity’s event system is fully asynchronous. Maintenance leverages this for optimal performance:

Non-blocking player connection checks
Efficient server switching
Better scalability

Config Reload Support

Velocity supports native plugin reloading:

/maintenance reload

Or use Velocity’s native reload:

/velocity reload

Maintenance will automatically reload its configuration.

Configuration

Velocity configuration is similar to BungeeCord with some differences:

# Global maintenance
maintenance: false

# Per-server maintenance
proxied-maintenance-servers:
  lobby: false
  survival: false

# Fallback configuration
fallback:
  enabled: true
  fallback-list:
    survival: lobby

# Waiting server
waiting-server:
  enabled: false
  server: waiting

# Redis for multi-proxy setups
redis:
  enabled: false
  host: localhost
  port: 6379
  password: ""
  channel: maintenance

# Server list customization
playercountmessage: "Maintenance Mode"
enable-timerspecific-playercountmessage: false
timer-playercountmessage: "Back in %TIMER%"

Permissions

Permission	Description
`maintenance.command`	Access to `/maintenance` command
`maintenance.bypass`	Join during maintenance
`maintenance.admin`	Full administrative access
`maintenance.joinnotification`	Receive join attempt notifications

Configure permissions using your Velocity-compatible permissions plugin (e.g., LuckPerms).

Commands

All commands are available under /maintenance or /mt:

# Global maintenance
/maintenance on                    # Enable global maintenance
/maintenance off                   # Disable global maintenance

# Per-server maintenance
/maintenance on <server>           # Enable for specific server
/maintenance off <server>          # Disable for specific server

# Whitelist
/maintenance add <player>          # Add to whitelist
/maintenance remove <player>       # Remove from whitelist

# Timers
/maintenance start <time>          # Schedule start (e.g., 1h, 30m)
/maintenance end <time>            # Schedule end

# Management
/maintenance reload                # Reload configuration

Server List Customization

Custom MOTD

Use MiniMessage format for rich text:

motd:
  maintenance:
    - "<gradient:red:gold>Server Maintenance</gradient>"
    - "<gray>We'll be back soon!"

Custom Icon

Place your maintenance icon at plugins/maintenance/maintenance-icon.png:

64x64 pixels
PNG format

Player Count Message

playercountmessage: "Under Maintenance"

With timer:

enable-timerspecific-playercountmessage: true
timer-playercountmessage: "Restarting: %TIMER%"

Migration from BungeeCord

Migrating from BungeeCord to Velocity is straightforward:

Install Velocity and configure your servers
Copy your Maintenance config from BungeeCord
Update server names if they changed
Restart Velocity

All configuration options are compatible between platforms.

Multi-Proxy Setup

For networks with multiple Velocity proxies:

Deploy Redis server
Configure Redis on all proxies:

redis:
  enabled: true
  host: redis.example.com
  port: 6379
  password: "secure-password"
  channel: maintenance-network

Reload all proxies

Maintenance status will now sync across all proxies in real-time.

API Usage

For Velocity plugin developers:

import eu.kennytv.maintenance.api.proxy.MaintenanceProxy;
import eu.kennytv.maintenance.api.MaintenanceProvider;
import com.velocitypowered.api.plugin.Plugin;
import com.google.inject.Inject;

@Plugin(id = "yourplugin")
public class YourPlugin {
    private MaintenanceProxy maintenance;

    @Inject
    public YourPlugin() {
        // Get Maintenance API
        maintenance = (MaintenanceProxy) MaintenanceProvider.get();
        
        // Check global maintenance
        if (maintenance.isMaintenance()) {
            // Handle maintenance mode
        }
        
        // Check server-specific maintenance
        if (maintenance.isMaintenance("survival")) {
            // Survival server is in maintenance
        }
    }
}

See the API documentation for complete reference.

Troubleshooting

Plugin not loading

Check:

You’re running Velocity 3.0 or higher
Java 17+ is installed
JAR file is in the plugins/ directory
Check Velocity console for errors

Fallback not working

Ensure:

Fallback server exists in Velocity’s velocity.toml
Fallback server is not in maintenance
Player has permission to access fallback server
Fallback is correctly configured in maintenance config

Redis not syncing

Verify:

Redis server is accessible from all proxies
Same Redis credentials on all proxies
Same channel name on all proxies
Check logs for connection errors
Test Redis connection independently

Messages not displaying correctly

Velocity uses MiniMessage format:

Use <red> not §c
Use <br> for line breaks
See MiniMessage docs for formatting

Get Started

Configuration

Platform Guides

Features

Commands & Permissions

Requirements

Installation

Why Velocity?

Proxy Features

Global Maintenance

Per-Server Maintenance

Fallback Server Configuration

Waiting Server

Redis Integration

Plugin Integrations

ServerListPlus

LuckPerms

Velocity-Specific Features

Native Adventure Components

Async Event Handling

Config Reload Support

Configuration

Permissions

Commands

Server List Customization

Custom MOTD

Custom Icon

Player Count Message

Migration from BungeeCord

Multi-Proxy Setup

API Usage

Troubleshooting

Plugin not loading

Fallback not working

Redis not syncing

Messages not displaying correctly

​Requirements

​Installation

​Why Velocity?

​Proxy Features

​Global Maintenance

​Per-Server Maintenance

​Fallback Server Configuration

​Waiting Server

​Redis Integration

​Plugin Integrations

​ServerListPlus

​LuckPerms

​Velocity-Specific Features

​Native Adventure Components

​Async Event Handling

​Config Reload Support

​Configuration

​Permissions

​Commands

​Server List Customization

​Custom MOTD

​Custom Icon

​Player Count Message

​Migration from BungeeCord

​Multi-Proxy Setup

​API Usage

​Troubleshooting

​Plugin not loading

​Fallback not working

​Redis not syncing

​Messages not displaying correctly

Requirements

Installation

Why Velocity?

Proxy Features

Global Maintenance

Per-Server Maintenance

Fallback Server Configuration

Waiting Server

Redis Integration

Plugin Integrations

ServerListPlus

LuckPerms

Velocity-Specific Features

Native Adventure Components

Async Event Handling

Config Reload Support

Configuration

Permissions

Commands

Server List Customization

Custom MOTD

Custom Icon

Player Count Message

Migration from BungeeCord

Multi-Proxy Setup

API Usage

Troubleshooting

Plugin not loading

Fallback not working

Redis not syncing

Messages not displaying correctly