Explaination: MessageSystem

The MessageSystem

The MessageSystem is one of the build-in features delivered by the Core. This System allows you to access a central Database of Messages in various Languages and send them to the Players. You can use the MessageAPI to access the MessageSystem from your Core / API. This MessageAPI allows you to get Access to the MiniMessages that can be displayed to the Player. To learn how to send a Message (classic way - Chat Message) please look at the "Introduction: API" Page.

How does the MessageSystem work?

The MessageSystem is powered by the SQL Database provided by the core. This Database is configured via the database.properties file located in the config folder of your master. The MessageSystem will create some tables in the given Database that are used for the management of replacements, messages, and locales. The primary Table is the "messages" Table that has one entry for every "MessageKey" and "locale" the message entered here will be displayed for the messageKey. The Locale is the Language of the Message, the core has the ability to detect the locale of the players automatically if you use the right MessageReciepents. If a specific Locale or Dialect is not available the System can fall back to the "next best" Language or if that is not available then the System will show the Message in the default "EN_US"

So to sum it up: The MessageSystem works by assigning MessageKeys and Locales to MiniMessages.

What is a MiniMesssage

The System uses the MiniMessage format to color and decorate the messages. If you want more information on how these Messages are formatted, then please look at the MiniMessage Documentation.

Replacers in the MessageSystem

The Core uses a custom System for the replacers that could be divided into two, several systems. The first system uses MiniMessage tags and the other uses patterns.

The System that works with the Tags is controlled exclusively by the Database and is designed for permanent replacements over messages. This could be colors, hovers, and of course your prefix.

The MessageSystem that works with patterns is designed to insert data (like player names or values) within the process of sending a Message. A Pattern is built this way:{n} That means that the following patterns are valid: {0} {1} {3} {20} {305} And the following are not; {-3} {-0} {00} {03} {5,6} {da} {three} The replacers are "in order" which means that they start with 0 and go into positive numbers. If a replacer is not filled, it will be displayed as a pattern to the recipient.

MessageReciepent

The MessageSystem is compatible with multiple platforms, which means that you can't send a Message to a Player or CommandSender directly. To send a Message to something, you need to use a MessageRecipeint. The Paper and VelocityCore provide inbuild MessageReciepents to you.

Alternatively, you can use the getMessage(...) methods to get a Message as an Object. This gives you the opportunity to extract the MiniMessage as is and use it for different purposes than sending via chat. With this, you can display them in a Book or as a Name of an Item. But be aware that if the Message is once sent (or extracted), the language cant be changed. So if you translate an Item Name and the item is given to another player, the Name will not change!

Convert a MiniMessage to a Component using AdventureAPI

The AdventureAPI is a Module provided by the core to handle MiniMessage conversion to Components. Please make sure that your Core is capable of AdventureAPI (which means the Core executes and maintains the AdventureCore).

The following example will show you a conversion of a message with the key "lobby.messages.welcome.1" to a Component:

        Message message = API.get().getMessageApi().getMessage("lobby.welcome.1", "EN_US");
        Component component = AdventureAPI.get().getAdventureTagManager().resolve(message);

This component can be used now.

How to operate the MessageAPI?

If you are new to MessageSystems or if you are just new to MessageSystems that work the way the MessageAPI works, you should read this carefully! The first thing (and most important) question to ask is: "How to access the MessageAPI". First, you need to make sure that your Core is running (so on Paper for example, you need to make sure the PaperCore Plugin is loaded and enabled). If you are sure the Core is running, you can access the API and use it to access the MessageAPI as a part of it:

MessageApi messageApi = API.get().getMessageApi();

I suggest always "getting" the MessageAPI from scratch and not storing it. This ensures the availability of the API and protects you from corrupted data or unwanted nulls or exceptions.

Before you are able to send Messages (or text in general) to the Player (or similar) you need to make sure your message is present within the MessageSystem in the "default_locale". I would never trust other plugins using the core with the process of registering the messages. You need to keep in mind, that you can register your Messages always as a precaution because the registerMessage method will never override exiting data! So in the case that you depend on a message that is registered by a third-party plugin, you can register the message in your plugin anyways without bad consequences. I suggest always registering all messages used by your plugin within the enable process of it, I would dedicate a simple method to it. So now we are ready to register or message into the message system.

    public final void registerMessages() {
        MessageApi messageApi = API.get().getMessageApi();
        messageApi.registerMessage("here.goes.your.message.key","<red>And here goes <rainbow>your own message</rainbow>!");
        messageApi.registerMessage("here.goes.your.second.key","<blue>You should always register your default <bold>message</bold> in english language!");
    }

You can also use three types of "replacements and replacers" within your messages. Lets take a look at them:

DBReplacements

This type of replacement is meant for "global" use over the entire network (or parts of it), they are managed by the database. If you want to use a replacement like this by default in your plugin, you should always make sure the appropriate entry exists in the database! Because of the centralized nature of these replacements, there is currently no 100% implemented API method for adding/registering a replacer for the DB, but you can use the JDBI API to add your own replacement:

        ReplacementBean bean = new ReplacementBean();
        bean.setTag("teamchat_prefix");
        bean.setValue("<gray>[<green>TeamChat</green>]: ");
        bean.setReplacementType("TEXT_CLOSING");
        API.get().getSQLManager().getJdbi().withExtension(ReplacementDAO.class,extension -> {
            extension.insert(bean);
            return null;
        });

(This example is taken out of the TeamChat Plugin for the Core) If you want to use this replacement, you should be highly familiar with MiniMessage and the MessageSystem in general. If you want to get familiar with this type of replacement, you may want to take a look in the JDBITagAdapter