Feature: Add MessageUtil with sendPrefixed extension for CommandSender

Agent-Logs-Url: https://github.com/Trilleo/PaperExamplePlugin/sessions/f8d52b5d-9d4e-4e36-b9d0-e87c3ef954bd

Co-authored-by: Trilleo <133519132+Trilleo@users.noreply.github.com>

Author: Copilot

docs/UTILITY_GUIDE.md

@@ -9,6 +9,7 @@ reduce boilerplate and provide commonly needed functionality out of the box.
 | `CountdownUtil` | Per-player countdown with configurable display and sound |
 | `TeamUtil`      | Custom team management with server-data persistence      |
 | `TagUtil`       | Per-player string tag management with player-data persistence |
+| `MessageUtil`   | Prefix-decorated message sender for players and command senders |
 
 ---
 
@@ -356,3 +357,81 @@ fun onEnterVipArea(player: Player) {
 ```
 
 ---
+
+## MessageUtil
+
+`MessageUtil` sends prefix-decorated messages to players and command senders. The prefix is
+read from `config.yml` under the `message-prefix` key and supports both plain text and
+[MiniMessage](https://docs.advntr.dev/minimessage/index.html) formatting. The plugin
+initialises `MessageUtil` automatically at startup and after every `/exampleplugin reload`,
+so no manual setup is required in your own commands or listeners.
+
+### Configuration
+
+```yaml
+# config.yml
+
+# Plain text
+message-prefix: "[ExamplePlugin]"
+
+# MiniMessage (rich formatting)
+message-prefix: "<gray>[<gold>ExamplePlugin<gray>]"
+```
+
+### Usage
+
+```kotlin
+import com.example.exampleplugin.utils.sendPrefixed
+
+// Plain text
+player.sendPrefixed("Hello!")
+
+// MiniMessage
+player.sendPrefixed("<green>Operation successful!")
+player.sendPrefixed("<red>Something went wrong.")
+
+// Adventure Component
+import net.kyori.adventure.text.Component
+import net.kyori.adventure.text.format.NamedTextColor
+
+player.sendPrefixed(Component.text("Hello!", NamedTextColor.GREEN))
+
+// Works on any CommandSender (console, players, command blocks)
+sender.sendPrefixed("Configuration reloaded!")
+```
+
+### Methods
+
+| Method / Extension                      | Description                                                        |
+|:----------------------------------------|:-------------------------------------------------------------------|
+| `MessageUtil.init(prefixString)`        | Loads the prefix (plain text or MiniMessage). Called automatically at startup and on reload. |
+| `MessageUtil.sendPrefixed(sender, msg: String)` | Sends a plain-text or MiniMessage string with the prefix prepended. |
+| `MessageUtil.sendPrefixed(sender, msg: Component)` | Sends an Adventure `Component` with the prefix prepended. |
+| `CommandSender.sendPrefixed(msg: String)` | Extension shorthand for `MessageUtil.sendPrefixed(this, msg)`. |
+| `CommandSender.sendPrefixed(msg: Component)` | Extension shorthand for `MessageUtil.sendPrefixed(this, msg)`. |
+
+### Example (Command)
+
+```kotlin
+import com.example.exampleplugin.registration.PluginCommand
+import com.example.exampleplugin.utils.sendPrefixed
+import net.kyori.adventure.text.Component
+import net.kyori.adventure.text.format.NamedTextColor
+import org.bukkit.command.CommandSender
+
+class GreetCommand : PluginCommand(
+    name = "greet",
+    description = "Send a greeting"
+) {
+    override fun execute(sender: CommandSender, args: Array<out String>): Boolean {
+        // String (MiniMessage)
+        sender.sendPrefixed("<green>Welcome to the server!")
+
+        // Component
+        sender.sendPrefixed(Component.text("Hello!", NamedTextColor.GOLD))
+        return true
+    }
+}
+```
+
+---

src/main/kotlin/com/example/exampleplugin/Main.kt

@@ -4,6 +4,7 @@ import com.example.exampleplugin.config.PluginConfig
 import com.example.exampleplugin.data.PlayerDataManager
 import com.example.exampleplugin.data.ServerDataManager
 import com.example.exampleplugin.registration.*
+import com.example.exampleplugin.utils.MessageUtil
 import org.bukkit.plugin.java.JavaPlugin
 
 class Main : JavaPlugin() {
@@ -16,6 +17,7 @@ class Main : JavaPlugin() {
         // Load configuration
         logger.info("Loading configuration...")
         pluginConfig = PluginConfig(this)
+        MessageUtil.init(pluginConfig.messagePrefix)
 
         // Initialise data managers
         logger.info("Initialising data managers...")

src/main/kotlin/com/example/exampleplugin/commands/moderation/ReloadCommand.kt

@@ -2,6 +2,8 @@ package com.example.exampleplugin.commands.moderation
 
 import com.example.exampleplugin.Main
 import com.example.exampleplugin.registration.PluginCommand
+import com.example.exampleplugin.utils.MessageUtil
+import com.example.exampleplugin.utils.sendPrefixed
 import org.bukkit.command.CommandSender
 import org.bukkit.plugin.java.JavaPlugin
 
@@ -19,11 +21,12 @@ class ReloadCommand(private val plugin: JavaPlugin) : PluginCommand(
     override fun execute(sender: CommandSender, args: Array<out String>): Boolean {
         val main = plugin as? Main
         if (main == null) {
-            sender.sendMessage("Error: Plugin instance type mismatch. Unable to reload configuration.")
+            sender.sendPrefixed("<red>Error: Plugin instance type mismatch. Unable to reload configuration.")
             return true
         }
         main.pluginConfig.reload()
-        sender.sendMessage("Configuration reloaded!")
+        MessageUtil.init(main.pluginConfig.messagePrefix)
+        sender.sendPrefixed("<green>Configuration reloaded!")
         return true
     }
 }

src/main/kotlin/com/example/exampleplugin/config/PluginConfig.kt

@@ -33,6 +33,15 @@ class PluginConfig(private val plugin: JavaPlugin) {
         config = plugin.config
     }
 
+    // ── Plugin Properties ────────────────────────────────────────────────
+
+    /**
+     * The prefix shown before plugin messages. Taken from the `message-prefix`
+     * key in `config.yml`. Supports plain text and MiniMessage formatting.
+     */
+    val messagePrefix: String
+        get() = getString("message-prefix", "[ExamplePlugin]")
+
     // ── Typed Getters ───────────────────────────────────────────────────
 
     /**

src/main/kotlin/com/example/exampleplugin/registration/CommandRegistrar.kt

@@ -1,5 +1,6 @@
 package com.example.exampleplugin.registration
 
+import com.example.exampleplugin.utils.sendPrefixed
 import org.bukkit.Bukkit
 import org.bukkit.command.Command
 import org.bukkit.command.CommandMap
@@ -151,8 +152,8 @@ object CommandRegistrar {
 
     private fun executeParentCommand(sender: CommandSender, args: Array<out String>): Boolean {
         if (args.isEmpty()) {
-            sender.sendMessage("Usage: /$ROOT_COMMAND <subcommand>")
-            sender.sendMessage(
+            sender.sendPrefixed("Usage: /$ROOT_COMMAND <subcommand>")
+            sender.sendPrefixed(
                 "Available sub-commands: ${subCommands.keys.sorted().joinToString(", ")}"
             )
             return true
@@ -161,16 +162,16 @@ object CommandRegistrar {
         val subName = args[0].lowercase()
         val subCommand = subCommands[subName]
         if (subCommand == null) {
-            sender.sendMessage("Unknown sub-command: ${args[0]}")
-            sender.sendMessage(
+            sender.sendPrefixed("Unknown sub-command: ${args[0]}")
+            sender.sendPrefixed(
                 "Available sub-commands: ${subCommands.keys.sorted().joinToString(", ")}"
             )
             return true
         }
 
         subCommand.permission?.let { perm ->
             if (!sender.hasPermission(perm)) {
-                sender.sendMessage("You do not have permission to use this command.")
+                sender.sendPrefixed("You do not have permission to use this command.")
                 return true
             }
         }

src/main/kotlin/com/example/exampleplugin/utils/MessageUtil.kt

@@ -0,0 +1,88 @@
+package com.example.exampleplugin.utils
+
+import net.kyori.adventure.text.Component
+import net.kyori.adventure.text.minimessage.MiniMessage
+import org.bukkit.command.CommandSender
+
+/**
+ * Utility for sending prefix-decorated messages to players and command senders.
+ *
+ * Call [init] once during plugin startup (and again after a config reload) to
+ * load the configured prefix. The prefix string may be plain text or a
+ * MiniMessage-formatted string such as `"<gray>[<gold>ExamplePlugin<gray>]"`.
+ *
+ * ### Usage
+ *
+ * ```kotlin
+ * import com.example.exampleplugin.utils.sendPrefixed
+ *
+ * // Plain text or MiniMessage string
+ * player.sendPrefixed("Hello!")
+ * player.sendPrefixed("<green>Operation successful!")
+ *
+ * // Adventure Component
+ * player.sendPrefixed(Component.text("Hello!", NamedTextColor.GREEN))
+ * ```
+ */
+object MessageUtil {
+
+    private val mm = MiniMessage.miniMessage()
+    private var prefixComponent: Component = Component.empty()
+
+    /**
+     * Loads the prefix from [prefixString].
+     *
+     * [prefixString] may be a plain text string (e.g. `"[ExamplePlugin]"`) or
+     * a MiniMessage-formatted string (e.g. `"<gray>[<gold>ExamplePlugin<gray>]"`).
+     * Call this method during plugin startup and again whenever the configuration
+     * is reloaded.
+     *
+     * @param prefixString the prefix text to display before every message
+     */
+    fun init(prefixString: String) {
+        prefixComponent = mm.deserialize(prefixString)
+    }
+
+    /**
+     * Sends [message] to [sender] with the configured prefix prepended.
+     *
+     * [message] may be a plain text string or a MiniMessage-formatted string.
+     *
+     * @param sender  the recipient
+     * @param message the message string (plain text or MiniMessage-formatted)
+     */
+    fun sendPrefixed(sender: CommandSender, message: String) {
+        sender.sendMessage(build(mm.deserialize(message)))
+    }
+
+    /**
+     * Sends [message] to [sender] with the configured prefix prepended.
+     *
+     * @param sender  the recipient
+     * @param message the [Component] to send
+     */
+    fun sendPrefixed(sender: CommandSender, message: Component) {
+        sender.sendMessage(build(message))
+    }
+
+    private fun build(message: Component): Component =
+        prefixComponent.append(Component.space()).append(message)
+}
+
+/**
+ * Sends [message] to this sender with the plugin prefix prepended.
+ *
+ * [message] may be a plain text string or a MiniMessage-formatted string.
+ *
+ * @receiver the message recipient
+ * @param message the message string (plain text or MiniMessage-formatted)
+ */
+fun CommandSender.sendPrefixed(message: String) = MessageUtil.sendPrefixed(this, message)
+
+/**
+ * Sends [message] to this sender with the plugin prefix prepended.
+ *
+ * @receiver the message recipient
+ * @param message the [Component] to send
+ */
+fun CommandSender.sendPrefixed(message: Component) = MessageUtil.sendPrefixed(this, message)