SmartMotd

SmartMOTD - Full Usage Guide #

What it does

SmartMOTD is a dynamic server-list MOTD system. It renders a 2-line MOTD (plus optional server icon) based on: - Mode priority (normal/maintenance/event/failover/full/busy/empty/seasonal/custom) - Built-in flags (maintenance/event/failover) and optional conditions - Placeholders (online/max/tps/mood/countdown/etc.) - Optional formatting (legacy colors, hex colors, gradients) - Optional web editor for normal mode entry 0

Installation

1) Put the plugin jar into /plugins. 2) Start the server once to generate config.yml. 3) Edit plugins/SmartMOTD/config.yml. 4) Reload with: /motd reload

Commands

/motd reload Reloads config and restarts MOTD rendering. Permission: smartmotd.reload

/motd maintenance [on|off|toggle] Toggles flags.maintenance (can trigger the maintenance mode). Permission: smartmotd.toggle

/motd event [on|off|toggle] Toggles flags.event (switches between event and event-live based on the configured target time). Permission: smartmotd.toggle

/motd failover [on|off|toggle] Toggles flags.failover (can trigger the failover mode). Permission: smartmotd.toggle

/motd mode set <mode> Forces a specific mode (ignores priority until cleared). Permission: smartmotd.toggle

/motd mode clear Clears forced mode. Permission: smartmotd.toggle

/motd mode status Shows current forced mode value. Permission: smartmotd.toggle

/motd preset list Lists built-in preset config packs. Permission: smartmotd.preset

/motd preset apply <name> Applies a built-in preset to plugins/SmartMOTD/config.yml (backs up existing config first). Then reloads SmartMOTD. Permission: smartmotd.preset

/motd preview [mode] Prints a preview of the rendered MOTD for a mode in chat. If no mode is provided, it uses the currently forced mode value (if any). Permission: smartmotd.preview

/motd debug [on|off|toggle] Toggles config debug flag. Permission: smartmotd.debug

/motd web Creates a one-time access link to the Web Editor (if enabled). In-game only. Permission: smartmotd.web

Permissions

smartmotd.admin - Full access (command root permission in plugin.yml) smartmotd.reload - /motd reload smartmotd.toggle - /motd maintenance|event|failover|mode smartmotd.preset - /motd preset smartmotd.preview - /motd preview smartmotd.debug - /motd debug smartmotd.web - /motd web

How mode selection works

1) If state.forced-mode is set (via /motd mode set), that mode is used. 2) Otherwise SmartMOTD checks modes in the "priority:" list in order. 3) The first matching mode is used. 4) The normal mode is always used as the fallback if nothing else matches.

Built-in matches: - maintenance: when flags.maintenance is true - failover: when flags.failover is true - event / event-live: when flags.event is true - event-live is used when the event target time has been reached - event is used before the target time - empty: when online == 0 - full: when online >= max - busy: when online >= busy.threshold

Custom mode conditions can also be used (see "Mode conditions" below).

Mode conditions

Under a mode, you can add: modes.<mode>.conditions: min-online: <number> or "%max%" max-online: <number> months: [1..12] mood: <calm|active|overloaded> (or moods: [..]) time-of-day: <morning|afternoon|evening|night> (or times: [..]) day-of-week: <monday..sunday> (or days: [..]) geo: <countryCode> (or geos: [..])

Notes: - min-online: "%max%" means "only match when server is full". - geo matching uses upper-case country codes like "US", "DE", "FR" (requires geo.enabled).

Multiple entries per mode (rotation + weights)

Each mode has entries: modes.<mode>.entries: - line1: "..." line2: "..." icon: "icons/default.png" weight: 1 chance: 1.0

Rotation config: modes.<mode>.rotation: type: sticky | random | sequential | weighted interval-seconds: 30 random-seed: "smartmotd"

How it behaves: - sequential: goes through eligible entries in order - random/sticky: deterministic random selection that changes each interval - weighted: deterministic weighted selection using the entry weights - chance (0.0..1.0): makes an entry eligible only some of the time

Animation frames (optional)

You can animate an entry by adding frames: modes.<mode>.entries: - line1: "Base" line2: "Base" frames: - line1: "Frame 1" line2: "Frame 1" - line1: "Frame 2" line2: "Frame 2" frame-interval-seconds: 1

There is also a per-mode animation section: modes.<mode>.animation: enabled: true interval-seconds: 1 frames: - line1: "..." line2: "..."

If performance-guard switches to safe mode, animations are disabled automatically.

Formatting (colors + gradients)

Legacy colors: &0..&f

Formatting: &l bold &o italic &n underline &m strikethrough &r reset

Hex colors: &#RRGGBB

Gradients: <gradient:#RRGGBB:#RRGGBB>Text</gradient>

Config switches: format.legacy-ampersand: true/false format.hex: true/false format.gradients: true/false

If performance-guard switches to safe mode, hex and gradients are disabled automatically.

Built-in placeholders

- %online% Online players - %max% Max players - %mode% Current mode name - %date% Server date (yyyy-MM-dd) - %time% Server time (HH:mm:ss) - %uptime% Plugin uptime (rough) - %tps% Server TPS (best effort) - %mspt% Server MSPT (best effort, "N/A" if unavailable) - %perf_mode% "normal" or "safe" - %mood% "calm" | "active" | "overloaded" - %countdown% Countdown to event target (dd hh mm) - %promo% Current promo string (from promotions pool) - %tip% Current tip string (from tips pool) - %time_of_day% Time of day name (same as %tod%) - %day_of_week% Day of week name (same as %dow%) - %tod% Time of day name - %dow% Day of week name - %weather% Current weather string (from weather service) - %geo% Country code (only when geo is enabled; used in icon paths and can be used in MOTD text)

PlaceholderAPI: - If PlaceholderAPI is installed, SmartMOTD will also apply PlaceholderAPI placeholders.

Web Editor

The Web Editor edits ONLY the normal mode entry 0: modes.normal.entries.0.line1 modes.normal.entries.0.line2 modes.normal.entries.0.icon

Enable in config.yml: web-editor: enabled: true bind: "0.0.0.0" port: 8765 public-host: "YOUR_SERVER_IP_OR_DOMAIN"

Important: - bind is where the HTTP server listens (0.0.0.0 to allow other devices). - public-host is used to generate the clickable link. Do not set public-host to 0.0.0.0.

Open it: 1) Run: /motd web 2) Click the link (it includes a token).

Presets

Built-in presets: - survival - smp - lifesteal - minigames

Apply: /motd preset apply <name>

It overwrites plugins/SmartMOTD/config.yml and creates a backup in: plugins/SmartMOTD/config-backups/

Optional services

Performance Guard: - Watches pings-per-second + TPS + MSPT. - Switches to "safe" mode under load (disables animations/hex/gradients and makes weather/geo return fallbacks).

Event: - event.target: ISO-8601 timestamp (example: 2026-01-01T00:00:00Z) - event.live-mode: which mode name to use when live (default: event-live) - Use %countdown% in event mode.

Promotions / Tips pools: - promotions.enabled / tips.enabled - mode: daily or rotating - pool: list of strings - Use %promo% and %tip% placeholders.

Easter eggs: - easter-eggs.enabled - easter-eggs.chance - easter-eggs.entries: temporary MOTD overrides (can include placeholders)

Weather: - weather.enabled - weather.url and weather.extract-regex (extracts first capture group) - %weather% placeholder

Geo: - geo.enabled - geo.url and geo.extract-regex (extracts first capture group, e.g., countryCode) - Used for %geo% in MOTD and icon paths and for geo-based conditions - Includes caching, rate-limiting, and failure backoff

Failover TCP check: - failover.tcp-check.enabled: true - Checks host:port periodically - If auto-enable is true, it can automatically set flags.failover based on reachability

Troubleshooting

- Web editor link opens localhost/127.0.0.1: Set web-editor.public-host to your server IP/domain. - Hex/gradients not working: Ensure format.hex / format.gradients are enabled and server is not in safe mode (%perf_mode%). - Geo always empty: Enable geo.enabled, set a working geo.url + geo.extract-regex, and ensure safe mode is not active.