SmartBroadcast

中文

SmartBroadcast is an intelligent Minecraft LAN discovery protocol broadcaster plugin for Paper / Folia 1.20.1. It decides when to broadcast LAN server information, and what MOTD to broadcast, based on configurable expression rules.

Features

• Folia support: uses GlobalRegionScheduler and AsyncScheduler, with folia-supported: true in plugin.yml
• Minecraft LAN discovery protocol support: sends UDP multicast packets to 224.0.2.60:4445
• Multiple rules: rules are checked in order, and the first matching rule is used
• No-broadcast rules: a matched rule can set broadcast: false to suppress broadcasting
• Expression conditions: player count, whitelist status, port, MOTD, PlaceholderAPI placeholders, and more
• PlaceholderAPI support: PAPI placeholders can be used in both expressions and MOTD values
• MiniMessage support: custom MOTD values can use MiniMessage and will be converted to legacy text
• Current server MOTD support: use {server_motd} to broadcast the current Paper MOTD
• Hot reload support: /smartbroadcast reload

LAN Discovery Protocol

Minecraft clients listen for UDP multicast packets on 224.0.2.60:4445 while the multiplayer server list screen is open. The server should send a UTF-8 string in this format:

[MOTD]<server MOTD>[/MOTD][AD]<server port>[/AD]

Important: this protocol does not support Adventure rich text components. SmartBroadcast converts MiniMessage or the current server MOTD into legacy § text before broadcasting, so clients can parse it correctly.

Default Behavior

By default, the plugin broadcasts the current server MOTD only when at least one player is online:

rules:
  - name: "players-online"
    expression: "online > 0"
    broadcast: true
    motd: "{server_motd}"

If no rule matches, no LAN packet is sent.

Installation

1. Build the plugin:

./gradlew shadowJar

1. Copy the generated JAR into your server's plugins directory:

build/libs/SmartBroadcast-1.0.0.jar

1. Start your Paper / Folia 1.20.1 server.
2. Install PlaceholderAPI as well if you need PlaceholderAPI support.

Commands and Permissions

Command	Permission	Description
/smartbroadcast reload	smartbroadcast.admin	Reloads the configuration
/sbc reload	smartbroadcast.admin	Reloads the configuration
/lanbroadcast reload	smartbroadcast.admin	Reloads the configuration

Configuration

broadcast:
  enabled: true
  address: "224.0.2.60"
  port: 4445
  interval-millis: 1500
  advertised-port: -1

• enabled: whether broadcasting is enabled
• address: LAN discovery multicast address, defaults to 224.0.2.60
• port: LAN discovery multicast port, defaults to 4445
• interval-millis: broadcast interval; vanilla uses about 1500ms
• advertised-port: server port advertised to clients; -1 means the current server port

Expression Rules

Rules are checked from top to bottom. The first rule whose expression evaluates to true is used.

Boolean Operators

&&  and
||  or
!   not

Example:

expression: "online > 0 && !whitelist"

Parentheses

expression: "(online > 0 && !whitelist) || %server_tps_1% >= 18"

Comparison Operators

==  equals
!=  not equals
>   greater than
>=  greater than or equal
<   less than
<=  less than or equal

String Operators

contains  contains substring
matches   regular expression match

Examples:

expression: "motd contains 'Survival'"
expression: "%server_name% matches 'Lobby.*'"

Literals

Supported literals:

• true
• false
• numbers such as 0 and 18.5
• strings such as 'Lobby' or "Survival"

Built-in Variables

Variable	Type	Description
online	number	Current online player count
max_players	number	Maximum player count
port	number	Port advertised to clients
whitelist	boolean	Whether the whitelist is enabled
motd	string	Plain-text form of the current server MOTD

PlaceholderAPI

When PlaceholderAPI is installed, PAPI placeholders can be used directly in expressions and MOTD values:

expression: "%server_online% > 0"
expression: "%server_tps_1% >= 18"
expression: "%server_name% contains 'Lobby'"

motd: "<green>%server_online%</green><gray>/</gray><yellow>%server_max_players%</yellow>"

MOTD Rendering

Broadcast Current Server MOTD

motd: "{server_motd}"

The plugin reads the current Paper MOTD and converts it to legacy text before broadcasting.

Custom MiniMessage MOTD

motd: "<gradient:#55ff55:#00aaaa>SmartBroadcast</gradient> <gray>|</gray> <yellow>%server_online%</yellow>"

Processing pipeline:

1. Apply PlaceholderAPI
2. Parse MiniMessage
3. Convert to legacy § text
4. Send a UDP multicast packet using the LAN discovery protocol

Multiple Rules Example

rules:
  - name: "hide-when-whitelist"
    expression: "whitelist == true"
    broadcast: false

  - name: "good-tps"
    expression: "online > 0 && %server_tps_1% >= 18"
    broadcast: true
    motd: "{server_motd}"

  - name: "fallback"
    expression: "online > 0"
    broadcast: true
    motd: "<yellow>Server is online</yellow>"

Build Requirements

• Java 17+
• Gradle
• Paper API 1.20.1

Build command:

./gradlew shadowJar

If Gradle Wrapper is not available locally, use an installed Gradle distribution:

gradle shadowJar

Testing Suggestions

• Start the plugin on Folia 1.20.1 and confirm there are no console errors
• Run /smartbroadcast reload to test hot reload
• Keep at least one player online and refresh the multiplayer server list from a client on the same LAN
• Test whether broadcast: false suppresses broadcasting
• Install PlaceholderAPI and test expressions such as %server_online% and %server_tps_1%

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.