MotdGuard v1.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


MotdGuard is more than a plugin that changes two lines in the Minecraft server list.

It provides a focused control layer for your Velocity proxy by combining a professional dynamic MOTD, practical maintenance management, and protection against abusive server-list ping traffic.

Configure it in minutes, apply changes without restarting the proxy, and keep your network’s presentation consistent, predictable, and protected.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


● Dynamic MiniMessage MOTD

Create modern server-list messages using hex colors, gradients, bold text, and other MiniMessage formatting options.

● Live placeholders

Display information that updates automatically on every ping using {online}, {max}, and {version}.

● Optional maintenance MOTD

Display a dedicated server-list message while maintenance mode is enabled.

● Maintenance mode without restarts

Enable, disable, or toggle maintenance mode directly through administrative commands.

● Persistent maintenance state

The maintenance status is preserved after configuration reloads and proxy restarts.

● Staff bypass permission

Allow administrators, developers, and trusted team members to join while the network remains closed to regular players.

● Per-IP ping rate limiting

Restrict excessive status requests from individual IP addresses and reduce unnecessary traffic caused by ping spam.

● Hot configuration reload

Edit the configuration and apply supported changes through a command instead of restarting Velocity.

● Administrative command cooldown

Prevent accidental or repeated command execution.

● Detailed error logging

Startup and reload failures are written to a dedicated error log, making diagnostics easier.

● Simple TOML configuration

A clean and readable configuration structure without unnecessary complexity.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


The server list is often the first interaction a player has with your network.

MotdGuard allows you to create a clear and visually consistent MOTD using modern MiniMessage formatting.

Combine gradients, custom hex colors, and live server information to make your network stand out before the player even connects.

Supported live placeholders:

● {online} — Current number of connected players

● {max} — Configured maximum player count

● {version} — Protocol version detected during the ping

Static MOTD lines are prepared for reuse, while lines containing placeholders are rendered with updated values for every server ping.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Close your network cleanly whenever you need to deploy an update, fix an issue, or perform internal maintenance.

● Enable or disable maintenance mode through commands

● Configure a custom login rejection message

● Display an optional maintenance-specific MOTD

● Allow authorized staff members to connect

● Preserve the maintenance status after a proxy restart

You do not need to restart the proxy every time you want to open or close your network.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Minecraft clients and automated tools can repeatedly query your proxy’s status.

MotdGuard includes configurable per-IP rate limiting to control excessive server-list pings before they generate unnecessary application-level traffic.

The limiter is designed to preserve normal client behavior while restricting addresses that exceed the configured request rate.

Important: This feature protects against application-level ping spam. It is not a replacement for infrastructure-level DDoS protection provided by your hosting provider.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


● /motdguard or /mg — Display the command menu

● /motdguard reload — Reload the configuration

● /motdguard maintenance — Toggle maintenance mode

● /motdguard maintenance on — Enable maintenance mode

● /motdguard maintenance off — Disable maintenance mode

● /mg m — Toggle maintenance mode using the short command

● /mg m on — Enable maintenance mode using the short command

● /mg m off — Disable maintenance mode using the short command

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


● motdguard.admin — Grants access to MotdGuard administrative commands

● motdguard.bypass — Allows a player to join while maintenance mode is active

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


● Proxy: Velocity 3.5.0 or newer

● Java: Java 21 or newer

● Configuration format: TOML

● Text formatting: MiniMessage

MotdGuard is a Velocity proxy plugin.

It is not designed to be installed directly on Paper, Spigot, or Bukkit backend servers.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


1. Download the MotdGuard JAR file.

2. Place the file inside the plugins directory of your Velocity proxy.

3. Restart the proxy to generate the initial configuration.

4. Edit plugins/MotdGuard/config.toml.

5. Run /motdguard reload after making supported configuration changes.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


MotdGuard is designed as a focused plugin rather than a heavy and unnecessarily complex management suite.

The project uses automated builds, unit tests, static analysis, and dependency monitoring to keep the codebase maintainable, secure, and reliable.

● Automated builds with GitHub Actions

● JUnit 5 tests

● CodeQL security analysis

● SpotBugs and FindSecBugs analysis

● Dependabot dependency monitoring

● Dependencies relocated inside the final JAR

● Open-source under the MIT License

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


● One plugin for MOTD, maintenance, and ping control

● No proxy restart required for routine maintenance changes

● Modern MiniMessage formatting

● Live player-count and protocol placeholders

● Persistent maintenance status

● Straightforward TOML configuration

● Focused commands and permissions

● Transparent and open-source codebase

Install it once, configure it in minutes, and let it operate quietly as the first control layer of your Velocity network.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━