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 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 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..conditions: min-online: or "%max%" max-online: 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: (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..entries:

• line1: "..." line2: "..." icon: "icons/default.png" weight: 1 chance: 1.0

Rotation config: modes..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..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..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:#RRGGBBText

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

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.