josantonius / minecraft-messaging

Easily send messages to players on a Minecraft server running PaperMC, Bukkit, or Spigot

Minecraft Messaging Library

Easily send messages to players on a Minecraft server running PurPur, Paper, Bukkit, or Spigot.

It supports sending messages and titles to individual players, all players and console.

The messages are stored in a YAML file and can be easily formatted with placeholders.

---

• Requirements
• Installation
• Available Classes
  • Message Class
  • Title Class
• Usage
• Using Clickable Tags
• Using Color Codes
• TODO
• Changelog
• Contribution
• Sponsor
• License

---

Requirements

• Java 17
• Purpur server 1.19.3 or Paper/Bukkit/Spigot server compatible with the Purpur API version used.

Installation

First, add the repository containing the minecraft-messaging library to your project's build.gradle file:

repositories {
    maven { url 'https://jitpack.io' }
}

Then, add the minecraft-messaging library as a dependency to your project's build.gradle file:

dependencies {
    implementation 'dev.josantonius:minecraft-messaging:v1.0.9'
}

Available Classes

Message Class

dev.josantonius.minecraft.messaging.Message

Set the prefix for console messages:

/**
 * @param prefix The prefix to use for console messages.
 */
fun setConsolePrefix(prefix: String)

Set the prefix for chat messages:

/**
 * @param prefix The prefix to use for chat messages.
 */
fun setChatPrefix(prefix: String)

Sends a message with the given key and optional parameters to all online players on the server:

/**
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun sendToPlayers(key: String, vararg params: String)

Sends a message with the given key and optional parameters to a specific player:

/**
 * @param player The Player object to send the message to.
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun sendToPlayer(player: Player, key: String, vararg params: String)

Sends a message with the given key and optional parameters to all online players on the server:

/**
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun sendToPlayers(key: String, vararg params: String)

Sends a system message to the console:

/**
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun sendToConsole(key: String, vararg params: String)

Sends a message with the given key and optional parameters to online players and the console:

/**
 * @param key The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun broadcast(key: String, vararg params: String)

Retrieves associated with the given key, replaces placeholders and returns a string:

/**
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun getString(key: String, vararg params: String): String

Retrieves associated with the given key, replaces placeholders and returns a Component:

/**
 * @param key    The key associated with the message in the message file.
 * @param params Optional parameters to replace placeholders in the message.
 */
fun getComponent(key: String, vararg params: String): Component

Title Class

dev.josantonius.minecraft.messaging.Title

Creates a new Title object with the given message file and optional Title.Times:

/**
 * Represents a title message with optional custom times.
 *
 * @property file  The file from which the message is read.
 * @property times The Title.Times object containing fadeIn, stay, and fadeOut durations.
 *
 * @throws IllegalArgumentException if there is an error loading the file.
 */
class Title(private val file: File, private val times: AdventureTitle.Times? = null)

Shows a title and subtitle with the given keys and optional parameters to all online players:

/**
 * @param titleKey    The key associated with the title message in the message file.
 * @param subtitleKey The key associated with the subtitle message in the message file.
 * @param params      Optional parameters to replace placeholders in the messages.
 */
fun showToPlayers(titleKey: String, subtitleKey: String, vararg params: String)

Shows a title and subtitle with the given keys and optional parameters to a specific player:

/**
 * @param player      The Player object to show the title to.
 * @param titleKey    The key associated with the title message in the message file.
 * @param subtitleKey The key associated with the subtitle message in the message file.
 * @param params      Optional parameters to replace placeholders in the messages.
 */
fun showToPlayer(player: Player, titleKey: String, subtitleKey: String, vararg params: String)

Using Clickable Tags

With MiniMessage, you can create interactive messages by adding clickable tags such as hover and click events. Here are some examples of using clickable tags in your messages:

Example usage in YAML files:

welcome_message: "<click:open_url:https://example.com>Visit our website</click>"
info_message: "<click:run_command:/rules>Click here to view rules</click>"
warning_message: "<click:suggest_command:/report >Report a user</click>"

Using Color Codes

This library utilizes MiniMessage to parse and handle color codes and text formatting in messages. You can use MiniMessage's syntax in your message strings to apply colors, formatting, and other features. Here are some examples of MiniMessage syntax:

Example usage in YAML files:

welcome_message: "<green>Welcome to our server!</green>"
info_message: "<blue><bold>Info:</bold></blue> Remember to follow the server rules!"
warning_message: "<red><bold>Warning:</bold></red> Fly is not allowed "

Usage

Creating new instance of Message

Main.kt

import java.io.File
import org.bukkit.plugin.java.JavaPlugin
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"), JavaPlugin())

Creating new instance of Title

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Title

Title(File("path/to/titles.yml"))

Creating new instance of Title with custom times

Main.kt

import java.io.File
import java.time.Duration
import dev.josantonius.minecraft.messaging.Title

val stay    = Duration.ofSeconds(5)
val fadeIn  = Duration.ofSeconds(1)
val fadeOut = Duration.ofMillis(1000)

val times = Title.Times.of(fadeIn, stay, fadeOut)

Title(File("path/to/titles.yml"), times)

Set console prefix for messages

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.setConsolePrefix("[MyPlugin]")

Set chat prefix for messages

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.setChatPrefix("<red>[MyPlugin]<white>")

Send message to all online players on the server

messages.yml

welcome:
  message: "Welcome to this server!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.sendToPlayers("welcome.message")

Send message to all online players on the server with parameters

messages.yml

game:
  start: "Game '{1}' started. Good luck, {2}!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.sendToPlayers(
    key = "game.start",
    params = arrayOf("CaptureTheFlag", "everyone")
)

Send message to a specific player

messages.yml

player:
  teleport: "You have been teleported to The End."

Main.kt

import java.io.File
import org.bukkit.entity.Player
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))
val targetPlayer: Player = //...

message.sendToPlayer(
    player = targetPlayer, 
    key = "player.teleport"
)

Send message to a specific player with parameters

messages.yml

player:
  points: "You have earned {1} points, {2}!"

Main.kt

import java.io.File
import org.bukkit.entity.Player
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))
val targetPlayer: Player = //...

message.sendToPlayer(
    player = targetPlayer,
    key = "player.points",
    params = arrayOf("100", targetPlayer.name)
)

Sends a system message to the console

messages.yml

warnings:
  wrong_input: "Warning: it is not a valid input."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.sendToConsole(
    key = "warnings.wrong_input"
)

Sends a system message to the console with parameters

messages.yml

info:
  wrong_input: "Info: {} is not a valid input."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))


message.sendToConsole(
    key = "info.wrong_input",
    params = arrayOf("command")
)

Sends a message to all online players and the console

messages.yml

warning:
  restart: "Warning: The server will restart."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.broadcast(
    key = "warning.restart"
)

Sends a message to all online players and the console with parameters

messages.yml

warning:
  restart: "Warning: The server will in {1} minutes."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))


message.broadcast(
    key = "warning.restart"
    params = arrayOf("10")
)

Retrieves the message associated with the given key

messages.yml

player:
  win: "Congratulations, you won the game!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.getString(
    key = "player.win"
)

Retrieves the message associated with the given key with parameters

messages.yml

command:
  cancel: "Run <command>/cancel</command> to cancel the challenge."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.getString(
    key = "command.cancel",
    params = arrayOf("first")
)

Retrieves the component associated with the given key

messages.yml

see:
  rules: "See our <link>https://mc.com</link> before accepting challenges."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.getComponent(
    key = "see.rules"
)

Retrieves the component associated with the given key with parameters

messages.yml

player:
  win: "Congratulations, you won the {1} game!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Message

val message = Message(File("path/to/messages.yml"))

message.getComponent(
    key = "player.win",
    params = arrayOf("first")
)

Show title and subtitle to a specific player

titles.yml

title:
  welcome: "Welcome!"
  subtitle: "Enjoy your time on our server!"

Main.kt

import java.io.File
import org.bukkit.entity.Player
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))
val targetPlayer: Player = //...

title.showToPlayer(
    player = targetPlayer,
    titleKey = "title.welcome",
    subtitleKey = "title.subtitle"
)

Show title without subtitle to a specific player

titles.yml

title:
  warning: "Warning!"

Main.kt

import java.io.File
import org.bukkit.entity.Player
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))
val targetPlayer: Player = //...

title.showToPlayer(
    player = targetPlayer,
    titleKey = "title.warning",
    subtitleKey = ""
)

Show title without subtitle and with parameters to a specific player

titles.yml

title:
  congrats: "Congratulations, {1}!"

Main.kt

import java.io.File
import org.bukkit.entity.Player
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))
val targetPlayer: Player = //...

title.showToPlayer(
    player = targetPlayer,
    titleKey = "title.congrats",
    subtitleKey = "",
    params = arrayOf(targetPlayer.name)
)

Show title and subtitle to all online players on the server

titles.yml

welcome:
  title: "Welcome to our Server!"
  subtitle: "Enjoy your stay."

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))

title.showToPlayers("welcome.title", "welcome.subtitle")

Show title without subtitle to all online players on the server

titles.yml

event:
  title: "Special Event Starting Soon!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))

title.showToPlayers("event.title", "")

Show title without subtitle and with parameters to all online players on the server

titles.yml

game:
  title: "Game '{1}' Starting in {2} minutes!"

Main.kt

import java.io.File
import dev.josantonius.minecraft.messaging.Title

val title = Title(File("path/to/titles.yml"))

title.showToPlayers(
    titleKey = "game.title",
    subtitleKey = "",
    params = arrayOf("CaptureTheFlag", "5")
)

TODO

• Add new feature
• Add tests
• Improve documentation

Changelog

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2023-present, Josantonius