BetterMOTD

Lightweight Paper plugin for server-list MOTD, icons, formatting and player-count display.

Requirements

• Java 21+
• Paper and Minecraft: 1.21 through 1.21.11, 26.1 through 26.1.2, or 26.2

The plugin uses Paper ping APIs for component MOTD, fake online count, hidden player count and hover control. Bukkit fallback is kept for basic MOTD text, but production use should be Paper.

Features

• MiniMessage, legacy color codes, JSON components and &#RRGGBB hex colors
• Multiple presets with weights
• Random, sticky-per-IP, hashed-per-IP and rotating preset selection
• Per-preset server icons from plugins/BetterMOTD/icons/
• Placeholders: %online%, %max%, %version%, %profile%, %preset%, %motd_frame%, %time%
• Player-count options: fake players, fixed max players, "online + X", hidden count, disabled hover list
• Custom hover/sample player lines
• Maintenance profile and join gate with bypass permission
• Preset conditions by hostname, protocol and online player count
• Random icons per preset through icons: [...]
• Optional PlaceholderAPI expansion
• MiniMOTD config import command
• /bettermotd reload without server restart

Installation

1. Download BetterMOTD-<version>.jar.
2. Use the jar matching your server version and put it into plugins/.
3. Start the server once.
4. Edit plugins/BetterMOTD/config.yml.
5. Run /bettermotd reload.

Supported builds

Server versions	Artifact
1.21 - 1.21.11	BetterMOTD-<pluginVersion>-mc-1.21.x.jar
26.1 - 26.1.2	BetterMOTD-<pluginVersion>-mc-26.1-26.1.2.jar
26.2	BetterMOTD-<pluginVersion>-mc-26.2.jar

Build Artifacts

Build both supported Minecraft targets:

mvn clean package

Artifacts are written to target/:

• BetterMOTD-<pluginVersion>-mc-1.21.x.jar
• BetterMOTD-<pluginVersion>-mc-26.1-26.1.2.jar
• BetterMOTD-<pluginVersion>-mc-26.2.jar

To copy both jars into target/dist/:

The same command creates both jars; scripts/build-all.ps1 is available for Windows users who want copies in target/dist/.

Commands

All commands require bettermotd.admin permission.

• /bettermotd help
• /bettermotd reload or /bm r
• /bettermotd profile [profileId] or /bm p [profileId]
• /bettermotd preview <profileId|presetId>
• /bettermotd diagnostics or /bm d
• /bettermotd import minimotd [path]

Command aliases: /bm, /bmotd, /motd.

MiniMOTD import reads common line1/line2 or motd-first-line/motd-second-line pairs and creates profile imported.

Quick configuration

Default config path:

plugins/BetterMOTD/config.yml

The generated config is ready to use. To change the server-list text, edit only these two lines:

profiles:
  default:
    presets:
      - id: "main"
        motd:
          - "<green><bold>My Server</bold></green>"
          - "<gray>Online: <white>%online%</white>/<white>%max%</white></gray>"

colorFormat defaults to AUTO, and placeholders are enabled automatically. Supported placeholders are %online%, %max%, %version%, %profile%, %preset%, %motd_frame%, and %time%.

Optional configuration

Add these settings only when you need them. All omitted values use safe defaults.

profiles:
  default:
    # RANDOM, STICKY_PER_IP (default), HASHED_PER_IP, or ROTATE
    selectionMode: "STICKY_PER_IP"
    presets:
      - id: "weekend"
        weight: 2
        icon: "default.png"
        icons: ["default.png", "weekend.png"]
        conditions:
          hostnames: ["play.example.net"]
          minOnline: 1
        motd:
          - "<gold>Weekend event!</gold>"
          - "<gray>Online: %online%/%max%</gray>"
    playerCount:
      hidePlayerCount: false
      hoverLines: ["<green>Welcome!</green>"]
      fakePlayers:
        enabled: true
        mode: "random"
        value: "2:8"

For text containing literal < or >, set colorFormat: "AUTO_STRICT". Enable PlaceholderAPI only when that plugin is installed:

placeholderAPI:
  enabled: true

Icons must be PNG files inside:

plugins/BetterMOTD/icons/

Simple names like default.png are resolved as icons/default.png. Absolute paths, parent-directory paths and non-PNG files are rejected.

Maintenance mode:

maintenance:
  enabled: true
  profile: "maintenance"
  bypassPermission: "bettermotd.maintenance.bypass"
  kickMessage: "<red>Server is in maintenance mode.</red>"

Conditional preset example:

conditions:
  hostnames: ["play.example.net"]
  minProtocol: 767
  maxOnline: 100

Production Notes

• Keep debug.selfTest and debug.verbose disabled unless diagnosing a config issue.
• Prefer AUTO_STRICT if your MOTD contains literal < or > symbols.
• Use STICKY_PER_IP for random presets to avoid flickering on repeated refreshes.
• Keep icon files 64x64 PNG.

Competitor-Inspired Ideas

Useful future features seen in MiniMOTD, AdvancedServerList, ServerListMOTD and similar plugins:

• Maintenance MOTD with optional join blocking for non-whitelisted users
• Custom hover/sample player lines instead of only disabling hover
• Conditions by hostname, protocol version, player count or permission source
• Multiple random icons independent from MOTD presets
• PlaceholderAPI integration
• Velocity/BungeeCord support for network setups
• Import command for MiniMOTD-style configs

Build

mvn verify

License

MIT