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.