Nexal Maintenance

A maintenance mode plugin for Minecraft servers: lock the server with one command or schedule it with a countdown, show a custom MOTD and icon in the server list, and let staff, whitelisted players and a bypass list in. Everything is managed from an admin menu, including the settings, and the state is stored in JSON or in a MySQL/MariaDB database.

Features

1. Toggle Maintenance Mode - Turn maintenance on or off with a command or from the admin menu
2. Scheduled Maintenance - Start maintenance after a delay, by command or from presets in the admin menu
3. Optional End Time - Maintenance can end on its own after a set duration
4. Countdown Warnings - Broadcast warnings at configurable intervals before scheduled maintenance starts
5. Player Kick with Countdown - Warn players who cannot bypass, then kick them when maintenance starts
6. Bypass Permission - Staff with nexalmaintenance.bypass stay online and can join during maintenance
7. Whitelist Integration - Players on the server whitelist can join, while the whitelist is on
8. Bypass List - Permanent bypasses, and temporary ones that clear when maintenance ends
9. Custom MOTD - A maintenance MOTD in the server list, with or without the reason
10. Custom Server Icon - A maintenance icon in the server list (if present in the plugin folder)
11. Max Players Override - Show 0/0 or another player limit during maintenance
12. Custom Kick Messages - Kick and refusal messages with or without the reason
13. Default Reason - A reason used when maintenance starts without one
14. Admin Menu - Toggle, schedule, manage the bypass list, edit the settings, export and import
15. In-Game Settings - MOTD, max players, icon, kick settings, countdown warnings and default reason edited in a GUI
16. JSON or SQL Storage - data.json or MySQL/MariaDB, with export and import to move between them
17. Persistent State - Maintenance, schedules and end times survive restarts; a schedule that passed while the server was offline starts on startup
18. PlaceholderAPI Integration - Placeholders for status, reason, countdowns and bypass
19. Configurable Messages - Every message customizable with sounds and titles

Technologies

• Paper API 1.20.1+ - Minecraft server API (Spigot compatible)
• Utilizer - Configuration, messages, items, tasks, GUIs
• ACF - Command framework
• nexal-core - JSON and SQL persistence (MariaDB/MySQL), help menu
• PlaceholderAPI - Placeholder integration (optional)

Commands

Player Commands

Command	Description	Permission
/maintenance help	Show help	nexalmaintenance.use
/maintenance status	Check maintenance status	nexalmaintenance.use

Aliases: /mt, /maint.

Admin Commands

Command	Description	Permission
/maintenance admin	Open the admin menu (console: list the admin commands)	nexalmaintenance.admin
/maintenance admin help [page]	List the admin commands	nexalmaintenance.admin
/maintenance admin on [reason]	Enable maintenance mode	nexalmaintenance.admin
/maintenance admin off	Disable maintenance mode, or cancel the schedule if it has not started	nexalmaintenance.admin
/maintenance admin toggle	Toggle maintenance mode	nexalmaintenance.admin
/maintenance admin schedule \<time> [duration] [reason]	Schedule maintenance (refused while it is active)	nexalmaintenance.admin
/maintenance admin cancel	Cancel scheduled maintenance	nexalmaintenance.admin
/maintenance admin bypass add \<player>	Add a permanent bypass	nexalmaintenance.admin
/maintenance admin bypass addtemp \<player>	Add a temporary bypass (until maintenance ends)	nexalmaintenance.admin
/maintenance admin bypass remove \<player>	Remove a bypass	nexalmaintenance.admin
/maintenance admin bypass list	List bypassed players	nexalmaintenance.admin
/maintenance admin export	Export the state and bypass list to export/maintenance.json	nexalmaintenance.admin
/maintenance admin import	Import export/maintenance.json into the current storage	nexalmaintenance.admin
/maintenance admin reload	Reload config.yml and messages.yml (and switch storage if its settings changed)	nexalmaintenance.admin

Times are written like 30s, 10m, 1h, 1d or combined (1h30m); a bare number means minutes.

Command Examples

# Enable maintenance with a reason
/maintenance admin on Server update in progress

# Schedule maintenance in 10 minutes
/maintenance admin schedule 10m

# Schedule maintenance in 10 minutes, lasting 1 hour, with a reason
/maintenance admin schedule 10m 1h Server update

# Add a temporary bypass (until maintenance ends)
/maintenance admin bypass addtemp Notch

Admin Menu

/maintenance admin opens:

• Current Status - Active, scheduled or inactive, with time left and reason
• Maintenance toggle - Green when on, red when off, yellow while scheduled (click cancels the schedule)
• Schedule Maintenance - Pick a start (1m, 5m, 10m, 30m, 1h) and a length (no end, 30m, 1h, 2h, 6h), then confirm. The reason is the default reason; use the command for another
• Bypass List - Every bypassed player. Add Player asks for a name in chat: left click adds a permanent bypass, right click a temporary one (until maintenance ends), the same as bypass add and bypass addtemp. Shift right click on a head removes that player
• Configuration - The settings screen: MOTD lines, max players shown, custom icon, kick on enable, kick countdown, countdown warnings and default reason. Text settings are typed in chat (cancel keeps the old value)
• Export Data / Import Data - The same as the commands; import takes a shift left click

Permissions

Permission	Description	Default
nexalmaintenance.admin	All admin commands and the admin menu (includes bypass and use)	op
nexalmaintenance.bypass	Stay online and join during maintenance	op
nexalmaintenance.use	Basic commands (status, help)	true

Placeholders

Requires PlaceholderAPI.

Placeholder	Description
%maintenance_active%	"true" or "false"
%maintenance_status%	"Active", "Scheduled", or "Inactive"
%maintenance_reason%	Current maintenance reason
%maintenance_scheduled%	"true" or "false"
%maintenance_countdown%	Time until scheduled maintenance
%maintenance_ends_in%	Time remaining until maintenance ends
%maintenance_bypass_count%	Number of players on the bypass list
%maintenance_can_bypass%	"true" if the player can bypass

Configuration

config.yml

# Storage settings
storage:
  type: json  # json or sql
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

maintenance:
  # Reason used when maintenance starts or is scheduled without one (empty for none)
  default-reason: ""

  # Custom MOTD during maintenance (MiniMessage)
  motd:
    no-reason:
      line1: "<gradient:#E67E22:#EB984E>\<bold>MAINTENANCE\</bold>\</gradient>"
      line2: "\<gray>The server is currently under maintenance\</gray>"
    with-reason:
      line1: "<gradient:#E67E22:#EB984E>\<bold>MAINTENANCE\</bold>\</gradient>"
      line2: "\<gray>%reason%\</gray>"

  # Max players shown during maintenance (0 shows 0/0)
  max-players-override: 0

  # Use a custom server icon (place server-icon-maintenance.png, 64x64, in the plugin folder)
  custom-icon: true

  kick:
    on-enable: true   # kick players who cannot bypass when maintenance starts
    countdown: 10     # seconds of warning before the kick, 0 kicks at once

# Seconds before scheduled maintenance at which a warning is broadcast
countdown:
  intervals: [600, 300, 60, 30, 10, 5, 4, 3, 2, 1]

Everything except storage can also be changed in game from Configuration in the admin menu.

messages.yml

All messages are fully customizable with MiniMessage colors, sounds and titles, including the kick messages, the countdown warnings and the bypass list output. A message missing from your file (for example one added in an update) uses the bundled text; your file is not rewritten.

Storage

storage.type: json keeps everything in data.json in the plugin folder. storage.type: sql uses MySQL/MariaDB; servers that share a database share the maintenance state and bypass list, loaded when each server starts or switches storage.

To move between them:

1. /maintenance admin export
2. Change storage.type (and storage.sql) in config.yml
3. /maintenance admin reload
4. /maintenance admin import

If the SQL database cannot be reached, the plugin logs an error and falls back to data.json.

Upgrading from 1.0.2 or earlier: the old state.json is moved into the configured storage on the first start and renamed to state.json.migrated (an empty one is only renamed; one that is not valid JSON is logged and renamed to state.json.invalid).

Database Schema

When using SQL storage, the plugin creates the following tables:

maintenance_state

Column	Type	Key	Description
id	VARCHAR(32)	PK	Always global (one row)
active	BOOLEAN		Whether maintenance is on
reason	TEXT		Current or scheduled reason
started_at	BIGINT		When maintenance started (epoch ms)
scheduled_for	BIGINT		Scheduled start (epoch ms), 0 if none
ends_at	BIGINT		End time (epoch ms), 0 if none

maintenance_bypass

Column	Type	Key	Description
id	VARCHAR(36)	PK	Player UUID
player_name	VARCHAR(16)		Name when added
temporary	BOOLEAN		Cleared when maintenance ends
added_at	BIGINT		When the player was added (epoch ms)

Key Legend: PK = Primary Key

Bypass

A player can stay online and join during maintenance if any of these apply:

1. Permission - nexalmaintenance.bypass (operators have it by default)
2. Server Whitelist - The player is whitelisted and the server whitelist is on (/whitelist on)
3. Permanent Bypass - Added with /maintenance admin bypass add
4. Temporary Bypass - Added with /maintenance admin bypass addtemp; cleared when maintenance ends

Custom Server Icon

1. Create a 64x64 PNG image
2. Name it server-icon-maintenance.png
3. Place it in the plugin folder (plugins/NexalMaintenance/)
4. Run /maintenance admin reload

Installation

1. Download the plugin JAR
2. Place in /plugins folder
3. Start/restart server
4. Configure config.yml and messages.yml, or use Configuration in /maintenance admin
5. Optionally add server-icon-maintenance.png
6. Reload with /maintenance admin reload