AstroCustomMOTD Documentation

Requirements: Paper, Purpur, or Folia server running Minecraft 1.20+. Java 21+.

Simple two-line rotation

Classic two-line MOTD with a small rotation.

motds:
  - "&6Welcome to &fAstroworld\n&7Economy survival. Claim, trade, build."
  - "&6Welcome to &fAstroworld\n&7%online% players online right now"
  - "&6Welcome to &fAstroworld\n&7Join our Discord for events"
maintenance:
  enabled: false
  message: "&cMaintenance &7| Back in 30 min"
  bypass-permission: "astromotd.bypass"

Event-mode with gradient

Hex gradient for limited-time event promotion.

motds:
  - "&#FFD700Halloween Event &#FF8C00→ &fGet the Pumpkin Crate!\n&7Limited until Oct 31"
  - "&#FFD700Halloween Event &#FF8C00→ &fNew bosses + cosmetics\n&7%online% online"
maintenance:
  enabled: false

Maintenance window

Flip this on before a big update push, off after.

motds:
  - "&7Normal operation"
maintenance:
  enabled: true
  message: "&c[Maintenance] &7Scheduled until 22:00 UTC\n&7Staff can still join"
  bypass-permission: "astromotd.bypass"
  kick-message: "&cServer is in maintenance. Try again later."

Network hub style (BungeeCord)

Per-server MOTD on a BungeeCord network where each backend is a different game.

motds:
  - "&6&lASTROWORLD\n&7Survival → &a/server smp"
  - "&6&lASTROWORLD\n&7Skyblock → &a/server sky"
  - "&6&lASTROWORLD\n&7Creative → &a/server creative"
maintenance:
  enabled: false

Config location

Maintenance mode before a major update

Scenario: You are about to roll out a 1.20 → 1.21 update with plugin changes. You need to stop new players from joining mid-update but keep staff access.

1. Edit config.yml: set maintenance.enabled to true.
2. Set maintenance.kick-message to something like '&cWe are updating to 1.21. Back in 20 min.'
3. Run /astromotd reload.
4. Give yourself astromotd.bypass via LuckPerms: /lp user <yourself> permission set astromotd.bypass true.
5. Run your update steps.
6. Set maintenance.enabled to false. Run /astromotd reload.

Limited-time event promotion

Scenario: Halloween event runs for one week. You want the server list to advertise it during that window only.

1. Add Halloween-themed MOTDs to the rotation in config.yml.
2. Schedule a server-side cron job (system crontab) to swap config.yml at the event start and again at the end.
3. Reload via console: `astromotd reload` (or restart).
4. Mention the event prominently in the maintenance message if you also disable joins during a window.

A/B test which MOTD converts better

Scenario: You want to know if 'Economy survival' or 'PvP, ranks, claims' brings more joins from server-list browsers.

1. Add both variants to your motds rotation.
2. Look at your join logs (per session) and timestamp-match to the random rotation in the plugin.
3. Since the plugin does not log which MOTD was shown, manually swap motds list weekly and compare joins/week.
4. On the roadmap: per-MOTD impression and click-through tracking.

Tip: Use LuckPerms to manage permissions per player or group.

BungeeCord / Velocity

On a Bungee setup, the proxy controls the MOTD shown to client server list pings, not the backend Paper server. Run AstroCustomMOTD on the backend, but know it only affects direct-connect pings. For proxy MOTDs use a Velocity plugin or Bungee's bungee.yml motd field.

PlaceholderAPI

%online% is built-in. For other placeholders (uptime, current weather, etc) we use PAPI when present. Install PlaceholderAPI and use %papi:player_count%, %papi:server_uptime% etc directly in MOTDs.

LuckPerms

Set astromotd.bypass on your staff group so they can connect during maintenance mode.

/lp group staff permission set astromotd.bypass true

Geyser-MCBE

Bedrock clients (via Geyser) see the MOTD, but only the first line. Multi-line gradients render correctly on Java; Bedrock truncates after the first '\n'.

MOTD shows the default Bukkit text, not my custom one

Cause: Plugin failed to register the ServerListPingEvent listener, often because another plugin (Maintenance, ServerMOTD) is hogging it.

Fix:

• Check console for warnings about AstroCustomMOTD failing to register.
• Disable any other MOTD plugin and restart.
• Verify /astromotd reload says 'Reloaded' and shows the motds count.
• Check that 'enable-status' is true in server.properties (some hosts disable status pings).

Hex colors render as &#FF1F00 literally instead of red

Cause: Old Paper version without hex color support.

Fix:

• Make sure you are on Paper 1.16.5 or higher (hex colors added in 1.16).
• Use legacy ChatColor codes (&c for red) on 1.15 or lower.

Gradients break or show as garbled hex codes

Cause: Gradient syntax not supported by base Paper. AstroCustomMOTD relies on MiniMessage if Paper version is 1.18+, falls back otherwise.

Fix:

• On Paper 1.18+ use MiniMessage syntax: '<gradient:#FFD700:#FF8C00>Event</gradient>'.
• On older versions use solid hex colors per character.

Maintenance bypass not working for staff

Cause: Permission node not granted or staff is not OP and never logged in to get cached permissions.

Fix:

• Run /lp user <staff> permission check astromotd.bypass to verify.
• If using a different perms plugin, double-check node spelling: astromotd.bypass (singular).

Can the MOTD use the player's name like 'Welcome back %player%'?

No — the MOTD is shown before a player connects, so we do not know who they are. The only player-aware placeholder we can use is %online% (current count). For per-player join messages use AstroJoinLeave.

How often does the MOTD rotate?

Every server-list ping is a fresh random pick from the rotation. There is no time-based scheduling; if you ping the server twice in one second you may see two different MOTDs. This matches how Hypixel and most large networks do it.

Does this work with BungeeCord / Velocity proxies?

Partially. On a proxied network, players ping the proxy and never see the backend Paper MOTD. For proxy MOTDs you need a Velocity or Bungee plugin. AstroCustomMOTD on the backend only affects direct-connect pings (when someone uses the backend's port).

Will the player count placeholder count Vanish'd players?

Yes by default — %online% comes from Bukkit's getOnlinePlayers().size(), which includes vanish'd. If you want to hide vanish'd players, use PlaceholderAPI with SuperVanish: '%supervanish_visible%'.

Can I have different MOTDs for different IPs (e.g., one for Bedrock, one for Java)?

Not in this version. The plugin treats every ping the same. A workaround: detect the protocol version in the ping event (Bedrock and Java are different) — that is on the roadmap but not yet implemented.

Why does my MOTD render fine in the in-game test but cut off in the actual server list?

The Minecraft server list truncates MOTDs at 64 characters per line, 2 lines max. Hex color codes count as characters even though they are invisible. Keep visible text under ~45 chars per line if you use colors.

Can I show a different MOTD on weekdays vs weekends?

Not natively, but you can drive it externally: write two config.yml files (config-weekday.yml, config-weekend.yml), use a cron job to symlink the active one, then run /astromotd reload via console at the swap moment.

Does AstroCustomMOTD interfere with anti-bot plugins that check server-list pings?

No. We only modify the MOTD field of the ping response. The protocol version, online count, and ping responses are untouched. Anti-bot plugins continue to function.

What is the order of MOTDs — sequential or random?

Random. Each ping picks one uniformly at random. If you want sequential rotation (round-robin), open a feature request.

v1.0.02026-05-13

• Initial public release
• Multiple MOTDs with random rotation
• Hex color support
• Gradient via MiniMessage on Paper 1.18+
• %online% placeholder for player count
• Maintenance mode with bypass permission
• /astromotd reload and /astromotd maintenance commands