Tolker: A Paper Messaging Library

Tolker is an easy to use messaging library, designed for the Minecraft Server Software called Paper. It makes it very easy for developers to load and use messages from various sources with support for placeholders.

Motivation

Why when I can simply hardcode my messages?

Well, you can hardcode your messages. A lot of smaller plugins do that. But the biggest caveat to this is: You users cannot customize these messages. Nobody likes to have a plugin which enforces whole messages, credits or even just a prefix.

But I can simply use Javas `MessageFormatter`!

Of course you can. But this has two disadvantages:

You cannot use named placeholders. This adds an additional layer of complexity for your users.
You cannot embed already rendered Adventure Components inside your messages.

Tolker supports the whole Adventure library and all of it’s features. This isn’t limited to named placeholders, but you can also embed pre-rendered components into your messages. It also supports conditional placeholders, which isn’t supported by Javas MessageFormatter.

Using Tolker

Alright, you got me. I’m in! But how can I use this library in my own plugin?

Installing Tolker

Great that you’ve asked! Tolker can be installed using the published Maven package on the GitHub Package Repository or using JitPack. For ease of use I definitely recommend JitPack. I won’t cover the GHPR installation process here, as you definitely know what you’re doing when using that.

You can find Tolker on JitPack here.

First, inside your pom.xml, include the JitPack repository:

  
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

After that, add the dependency, too:

  
<dependency>
    <groupId>com.github.tinyoverflow</groupId>
    <artifactId>minecraft-tolker</artifactId>
    <version>Tag</version>
</dependency>

Replace the Tag with the version number you want to use. Great, you’re done!

Basic Concepts explained

Now that you’ve successfully installed Tolker, it’s time to learn how to use it. Tolker uses message bags for that. A message bag is any object that implements the MessageBag interface and it basically means: An object that can map string tokens to message templates.

For example: If you want to send a player a welcome message when they join, you might want to call that message welcome-player. The message bag will receive the string welcome-player and return the appropiate template with the text, variables, formatting and so on. Tolker doesn’t care about where the message actually comes from. Therefore you can use the provided message bags or implement your own and pass it to Tolker when instantiating it.

Instantiating Tolker

To use Tolker, you first need to set it up. Basically you can do that wherever you want, though I suggest doing that inside your onEnable() method or inside your bootstrapper, so you have it ready when you need it.

In the following example, I’m using a Java ResourceBundle with the Tolker-native ResourceBundleBag. It basically just allows Tolker to access data from the ResourceBundle provided to it.

  
// Create MessageBag from ResourceBundle
ResourceBundle messageBundle = ResourceBundle.getBundle("messages");
MessageBag messageBag = new ResourceBundleBag(messageBundle);

// Create a new Tolker instance
tolker = new Tolker(messageBag);
tolker.registerDefaultSerializers();

A Note on Serializers

Did you notice this line?

  
tolker.registerDefaultSerializers();

This line is responsible for registering the default serializers. Unexpected, I know! But what is a serializer in Tolkers context?

It’s the same as anywhere else: It takes a value and serializes it into a compatible one. Though, Tolker serializers only work one way. Deserializing is typically not required when using Tolker.

TypeSerializers, how Tolker calls them internally, are used to make human-readable text out of complex objects. The WorldSerializer, for example, makes it possible to just pass a Bukkit World object into Tolker to print out the world’s name.

If you want to know more about which TypeSerializers Tolker implements by default, please take a look at the repository: src/main/java/me/tinyoverflow/tolker/serializer

As Tolker allows you to register your custom serializers, it doesn’t register it’s own by default. Therefore you have to call registerDefaultSerializers(). After registering the default ones, you can of course register your own and override existing ones with your own implementation.

Sending A Message

Now that we’ve setup Tolker, it’s finally time to send a message. We’ll use the previous example of welcoming a user to the server inside the PlayerJoinEvent. I’ll skip the boilerplate to keep this example clean. This example assumes that you have a messages.properties with the following content:

  
welcome-player=Welcome, <green><player></green>! You're playing on <red><world></red>.

We can then send this message in our code using the Tolker message builder:

  
tolker.build("welcome-player")
      .with("player", event.getPlayer())
      .with("world", event.getPlayer().getWorld())
      .send(event.getPlayer());

Let’s break this code down a bit:

tolker.build("welcome-player") gives us a new MessageBuilder. It pulls the message out of the previously given message bag, which uses a resource bundle in this example, using the key welcome-player.
The with method is used to pass in variables. You might have noticed the <player> substring inside the properties-file. This is the method you use to finally assign a value to it. The same happens with world.
Finally, the message is being send to the player. You don’t have to send it to a player directly. You can send it to any object that implements the Audience interface from Paper.

Did you notice that we just pass the Player and the World object into it? We can do this because of the type serializers, which I’ve mentioned earlier.

That was easy and pretty straight forward, wasn’t it?

Summary

As you can see, using Tolker is pretty easy and straight forward. It’s mostly self-explanatory and you’ll get familiar with it pretty soon. It’s so damn easy that I’m actually impressed, that there isn’t such a API built into Paper by default, as it is such a common task.

If you have any questions, noticed bugs or want to suggest a new feature, just head over to the repository at GitHub and create an issue.

Have you used this library in a project? Let me know!