📚 SMP-Reconnect Documentation

Getting Started

SMP-Reconnect is designed to solve one critical problem: player loss during server restarts. When a backend server goes down, instead of kicking players to the lobby or disconnecting them, the plugin holds them on the proxy and automatically reconnects them when the server is back online.

Requirements

• Java 17 or higher
• Velocity Proxy 3.x+
• At least one backend server configured in Velocity

Key Benefits

• Zero player loss during scheduled restarts
• Async architecture — no proxy lag
• Smart detection — won't reconnect banned/kicked players
• Flexible routing — map servers to specific fallbacks

Installation

Step 1: Download

Download the latest SMP-Reconnect.jar from GitHub Releases or BuiltByBit.

Step 2: Install

1. Stop your Velocity proxy (recommended but not required)
2. Navigate to your Velocity plugins/ directory
3. Place the SMP-Reconnect.jar file in this directory
4. Start (or restart) your Velocity proxy

Step 3: Configure

After the first startup, SMP-Reconnect will generate a config.yml inside plugins/smp-reconnect/. Edit this file to customize the plugin behavior for your network.

Configuration Guide

The configuration file is located at plugins/smp-reconnect/config.yml. Below is a breakdown of every option:

Blacklisted Servers

Servers listed here will never trigger the reconnect logic. Use this for lobby servers, login servers, or any server where you want standard Velocity disconnect behavior.

# Servers that should NEVER trigger reconnect logic
blacklisted_servers:
  - lobby
  - login
  - auth

Fallback Server Map

Define where players should wait while their original server restarts. If a player was on a server listed as a key, they will be sent to the corresponding fallback server to wait.

# Map source servers to specific fallback destinations
fallback_servers_map:
  survival: lobby
  skyblock: skyblock_lobby
  creative: lobby

Example: If a player is on survival and it crashes, they will be sent to lobby and automatically reconnected to survival once it's back online.

Ping Settings

Controls how frequently the plugin checks if a downed server is accepting connections again.

# Frequency (in seconds) to check if a server is back online
ping_delay_seconds: 5

Recommendation: 5 seconds is a good default. Lower values mean faster reconnection but slightly more network activity. Higher values reduce overhead but delay reconnection.

Reconnecting Message

The message displayed to players while they are waiting to be reconnected. Supports Minecraft color codes including hex colors.

# What do the players see while waiting?
reconnecting_message: "&aThe server is still starting up! You will be connected shortly..."

Full Example Config

# SMP-Reconnect Configuration
# Plugin by ajdnikov

# Servers that should NEVER trigger reconnect logic
blacklisted_servers:
  - lobby
  - login

# Map source servers to specific fallback destinations
# Format: source_server: fallback_server
fallback_servers_map:
  survival: lobby
  skyblock: skyblock_lobby

# Frequency (in seconds) to check if a server is back online
ping_delay_seconds: 5

# What do the players see while waiting?
reconnecting_message: "&aThe server is still starting up! You will be connected shortly..."

How It Works

Understanding the reconnect flow helps you configure the plugin optimally:

Reconnect Flow

1. Server goes down — A backend server crashes or restarts
2. Player detection — The plugin detects all players who were on that server
3. Kick analysis — Checks if the disconnect was a ban/kick (these players are NOT reconnected)
4. Fallback routing — Players are sent to their mapped fallback server (or stay on proxy)
5. Async pinging — The plugin begins pinging the downed server at the configured interval
6. Notification — Players see the reconnecting message while waiting
7. Reconnection — Once the server responds to pings, all waiting players are automatically sent back

Fail-Safe Protection

The plugin intelligently distinguishes between different types of disconnections:

• Server crash/restart: Player IS reconnected ✅
• Player kicked by admin: Player is NOT reconnected ❌
• Player banned: Player is NOT reconnected ❌
• Server on blacklist: Normal Velocity behavior, no reconnect ❌

Commands

Permissions

Fallback Mapping Guide

The fallback mapping system is the core of SMP-Reconnect's routing logic. Here are some common network setups:

Simple Network (1 Lobby)

# All servers fall back to the single lobby
fallback_servers_map:
  survival: lobby
  skyblock: lobby
  creative: lobby
  prison: lobby

Multi-Lobby Network

# Each gamemode has its own lobby
fallback_servers_map:
  survival: survival_lobby
  survival_nether: survival_lobby
  survival_end: survival_lobby
  skyblock: skyblock_lobby
  skyblock_nether: skyblock_lobby

Hub Network

# Everything falls back to the hub
fallback_servers_map:
  smp1: hub
  smp2: hub
  minigames: hub

# Don't reconnect from the hub itself
blacklisted_servers:
  - hub

Important: Make sure your fallback servers are listed in blacklisted_servers so they don't trigger their own reconnect chains!

Troubleshooting

Q: Players are not being reconnected

A: Check the following:

• Ensure the server is NOT in the blacklisted_servers list
• Verify the server has a fallback mapping in fallback_servers_map
• Enable debug mode with /reconnectdebug and check the console logs
• Make sure the server is actually accepting connections (check firewall, port binding)

Q: Players get reconnected even when kicked

A: This should not happen — the plugin has built-in kick/ban detection. If it does, enable debug mode and report the issue on our Discord with the console logs.

Q: Reconnect takes too long

A: Lower the ping_delay_seconds value in your config. The default is 5 seconds, but you can set it to 2-3 for faster detection.

Q: Config changes aren't applying

A: Use /reconnectreload to reload the config without restarting the proxy. Check for YAML syntax errors in your config file.

Q: Need more help?

A: Join our Discord server for support and bug reports, or open an issue on GitHub.