# SmartMOTD – Full Usage Guide #
\n===========================<\/p>\n
**What it does**
\n————
\nSmartMOTD is a dynamic server-list MOTD system. It renders a 2-line MOTD (plus optional server icon)
\nbased on:
\n– Mode priority (normal\/maintenance\/event\/failover\/full\/busy\/empty\/seasonal\/custom)
\n– Built-in flags (maintenance\/event\/failover) and optional conditions
\n– Placeholders (online\/max\/tps\/mood\/countdown\/etc.)
\n– Optional formatting (legacy colors, hex colors, gradients)
\n– Optional web editor for normal mode entry 0<\/p>\n
**Installation**
\n————
\n1) Put the plugin jar into \/plugins.
\n2) Start the server once to generate config.yml.
\n3) Edit plugins\/SmartMOTD\/config.yml.
\n4) Reload with: \/motd reload<\/p>\n
**Commands**
\n——–
\n\/motd reload
\n Reloads config and restarts MOTD rendering.
\n Permission: smartmotd.reload<\/p>\n
\/motd maintenance [on|off|toggle]
\n Toggles flags.maintenance (can trigger the maintenance mode).
\n Permission: smartmotd.toggle<\/p>\n
\/motd event [on|off|toggle]
\n Toggles flags.event (switches between event and event-live based on the configured target time).
\n Permission: smartmotd.toggle<\/p>\n
\/motd failover [on|off|toggle]
\n Toggles flags.failover (can trigger the failover mode).
\n Permission: smartmotd.toggle<\/p>\n
\/motd mode set \/motd mode clear \/motd mode status \/motd preset list \/motd preset apply \/motd preview [mode] \/motd debug [on|off|toggle] \/motd web **Permissions** **How mode selection works** Built-in matches: Custom mode conditions can also be used (see “Mode conditions” below).<\/p>\n **Mode conditions** Notes: **Multiple entries per mode (rotation + weights)** Rotation config: **How it behaves:** **Animation frames (optional)** There is also a per-mode animation section: If performance-guard switches to safe mode, animations are disabled automatically.<\/p>\n **Formatting (colors + gradients)** Formatting: Hex colors: Gradients: Config switches: If performance-guard switches to safe mode, hex and gradients are disabled automatically.<\/p>\n **Built-in placeholders** PlaceholderAPI: **Web Editor** Enable in config.yml: Important: Open it: <\/p>\n **Presets** Apply: It overwrites plugins\/SmartMOTD\/config.yml and creates a backup in: **Optional services** Event: Promotions \/ Tips pools: Easter eggs: Weather: Geo: Failover TCP check: **Troubleshooting** SmartMotd the Next Motd Plugin for your Server<\/p>\n","protected":false},"featured_media":143801,"template":"","meta":{"_minecraft_slug":"smartmotd","_minecraft_project_id":"j6JQGasJ","_minecraft_author":"Funkel","_minecraft_license":"MIT","_minecraft_downloads":37,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"smartmotd.zip","_minecraft_size_bytes":197581,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-15T21:52:23.850072Z","_minecraft_date_created":"2026-01-13T21:36:32.879019Z","_minecraft_date_modified":"2025-12-25T22:29:59.951376Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/smartmotd","_minecraft_icon_attachment_id":143801,"_minecraft_imported_at":"2026-06-08T13:59:29+00:00","_minecraft_import_hash":"1e6490f990d1190f1d875999504c63b0","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,126,127,867,129,123,92],"mod_loader":[130,132,134],"minecraft_version":[40],"class_list":["post-143800","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-management","mod_category-paper","mod_category-social","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-spigot","minecraft_version-1-21-10"],"yoast_head":"\n
\n Forces a specific mode (ignores priority until cleared).
\n Permission: smartmotd.toggle<\/p>\n
\n Clears forced mode.
\n Permission: smartmotd.toggle<\/p>\n
\n Shows current forced mode value.
\n Permission: smartmotd.toggle<\/p>\n
\n Lists built-in preset config packs.
\n Permission: smartmotd.preset<\/p>\n
\n Applies a built-in preset to plugins\/SmartMOTD\/config.yml (backs up existing config first).
\n Then reloads SmartMOTD.
\n Permission: smartmotd.preset<\/p>\n
\n Prints a preview of the rendered MOTD for a mode in chat.
\n If no mode is provided, it uses the currently forced mode value (if any).
\n Permission: smartmotd.preview<\/p>\n
\n Toggles config debug flag.
\n Permission: smartmotd.debug<\/p>\n
\n Creates a one-time access link to the Web Editor (if enabled).
\n In-game only.
\n Permission: smartmotd.web<\/p>\n
\n———–
\nsmartmotd.admin – Full access (command root permission in plugin.yml)
\nsmartmotd.reload – \/motd reload
\nsmartmotd.toggle – \/motd maintenance|event|failover|mode
\nsmartmotd.preset – \/motd preset
\nsmartmotd.preview – \/motd preview
\nsmartmotd.debug – \/motd debug
\nsmartmotd.web – \/motd web<\/p>\n
\n————————
\n1) If state.forced-mode is set (via \/motd mode set), that mode is used.
\n2) Otherwise SmartMOTD checks modes in the “priority:” list in order.
\n3) The first matching mode is used.
\n4) The normal mode is always used as the fallback if nothing else matches.<\/p>\n
\n– maintenance: when flags.maintenance is true
\n– failover: when flags.failover is true
\n– event \/ event-live: when flags.event is true
\n – event-live is used when the event target time has been reached
\n – event is used before the target time
\n– empty: when online == 0
\n– full: when online >= max
\n– busy: when online >= busy.threshold<\/p>\n
\n—————
\nUnder a mode, you can add:
\nmodes.
\n min-online:
\n max-online:
\n months: [1..12]
\n mood:
\n time-of-day:
\n day-of-week:
\n geo:
\n– min-online: “%max%” means “only match when server is full”.
\n– geo matching uses upper-case country codes like “US”, “DE”, “FR” (requires geo.enabled).<\/p>\n
\n———————————————-
\nEach mode has entries:
\nmodes.
\n – line1: “…”
\n line2: “…”
\n icon: “icons\/default.png”
\n weight: 1
\n chance: 1.0<\/p>\n
\nmodes.
\n type: sticky | random | sequential | weighted
\n interval-seconds: 30
\n random-seed: “smartmotd”<\/p>\n
\n– sequential: goes through eligible entries in order
\n– random\/sticky: deterministic random selection that changes each interval
\n– weighted: deterministic weighted selection using the entry weights
\n– chance (0.0..1.0): makes an entry eligible only some of the time<\/p>\n
\n—————————
\nYou can animate an entry by adding frames:
\nmodes.
\n – line1: “Base”
\n line2: “Base”
\n frames:
\n – line1: “Frame 1”
\n line2: “Frame 1”
\n – line1: “Frame 2”
\n line2: “Frame 2”
\n frame-interval-seconds: 1<\/p>\n
\nmodes.
\n enabled: true
\n interval-seconds: 1
\n frames:
\n – line1: “…”
\n line2: “…”<\/p>\n
\n——————————-
\nLegacy colors:
\n &0..&f<\/p>\n
\n &l bold
\n &o italic
\n &n underline
\n &m strikethrough
\n &r reset<\/p>\n
\n &#RRGGBB<\/p>\n
\n
\nformat.legacy-ampersand: true\/false
\nformat.hex: true\/false
\nformat.gradients: true\/false<\/p>\n
\n– ———————
\n– %online% Online players
\n– %max% Max players
\n– %mode% Current mode name
\n– %date% Server date (yyyy-MM-dd)
\n– %time% Server time (HH:mm:ss)
\n– %uptime% Plugin uptime (rough)
\n– %tps% Server TPS (best effort)
\n– %mspt% Server MSPT (best effort, “N\/A” if unavailable)
\n– %perf_mode% “normal” or “safe”
\n– %mood% “calm” | “active” | “overloaded”
\n– %countdown% Countdown to event target (dd hh mm)
\n– %promo% Current promo string (from promotions pool)
\n– %tip% Current tip string (from tips pool)
\n– %time_of_day% Time of day name (same as %tod%)
\n– %day_of_week% Day of week name (same as %dow%)
\n– %tod% Time of day name
\n– %dow% Day of week name
\n– %weather% Current weather string (from weather service)
\n– %geo% Country code (only when geo is enabled; used in icon paths and can be used in MOTD text)<\/p>\n
\n– If PlaceholderAPI is installed, SmartMOTD will also apply PlaceholderAPI placeholders.<\/p>\n
\n———-
\nThe Web Editor edits ONLY the normal mode entry 0:
\n modes.normal.entries.0.line1
\n modes.normal.entries.0.line2
\n modes.normal.entries.0.icon<\/p>\n
\nweb-editor:
\n enabled: true
\n bind: “0.0.0.0”
\n port: 8765
\n public-host: “YOUR_SERVER_IP_OR_DOMAIN”<\/p>\n
\n– bind is where the HTTP server listens (0.0.0.0 to allow other devices).
\n– public-host is used to generate the clickable link.
\n Do not set public-host to 0.0.0.0.<\/p>\n
\n1) Run: \/motd web
\n2) Click the link (it includes a token).<\/p>\n
\n——-
\nBuilt-in presets:
\n– survival
\n– smp
\n– lifesteal
\n– minigames<\/p>\n
\n \/motd preset apply
\n plugins\/SmartMOTD\/config-backups\/<\/p>\n
\n—————–
\nPerformance Guard:
\n– Watches pings-per-second + TPS + MSPT.
\n– Switches to “safe” mode under load (disables animations\/hex\/gradients and makes weather\/geo return fallbacks).<\/p>\n
\n– event.target: ISO-8601 timestamp (example: 2026-01-01T00:00:00Z)
\n– event.live-mode: which mode name to use when live (default: event-live)
\n– Use %countdown% in event mode.<\/p>\n
\n– promotions.enabled \/ tips.enabled
\n– mode: daily or rotating
\n– pool: list of strings
\n– Use %promo% and %tip% placeholders.<\/p>\n
\n– easter-eggs.enabled
\n– easter-eggs.chance
\n– easter-eggs.entries: temporary MOTD overrides (can include placeholders)<\/p>\n
\n– weather.enabled
\n– weather.url and weather.extract-regex (extracts first capture group)
\n– %weather% placeholder<\/p>\n
\n– geo.enabled
\n– geo.url and geo.extract-regex (extracts first capture group, e.g., countryCode)
\n– Used for %geo% in MOTD and icon paths and for geo-based conditions
\n– Includes caching, rate-limiting, and failure backoff<\/p>\n
\n– failover.tcp-check.enabled: true
\n– Checks host:port periodically
\n– If auto-enable is true, it can automatically set flags.failover based on reachability<\/p>\n
\n—————
\n– Web editor link opens localhost\/127.0.0.1:
\n Set web-editor.public-host to your server IP\/domain.
\n– Hex\/gradients not working:
\n Ensure format.hex \/ format.gradients are enabled and server is not in safe mode (%perf_mode%).
\n– Geo always empty:
\n Enable geo.enabled, set a working geo.url + geo.extract-regex, and ensure safe mode is not active.<\/p>\n","protected":false},"excerpt":{"rendered":"