💬 Tolker

Tolker is an easy-to-use messaging library for Paper. It provides you an interface which allows you to easily compose messages with placeholders in them.

• Installation
  • Install using Maven
  • Install using Gradle
• Usage
  • Message Format
  • Instantiating Tolker
  • Custom Type Serializers

Installation

Simply add the package me.tinyoverflow:tolker:<version> to your project. While this package is available on GitHub Packages, it is recommended to use JitPack.

Install using Maven

<!-- Repository -->
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<!-- Dependency -->
<dependency>
    <groupId>com.github.tinyoverflow</groupId>
    <artifactId>minecraft-tolker</artifactId>
    <version><version tag></version>
</dependency>

Install using Gradle

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

dependencies {
    implementation 'com.github.tinyoverflow:minecraft-tolker:<version tag>'
}

Usage

This plugin consists out of 3 components:

1. MessageBag
2. Tolker
3. MessageBuilder

The MessageBag is responsible for providing any messages. It is an interface that you can implement into your message loader, if you have one. The Tolker library also provides you with two implementations:

1. MemoryBag
   Provides an empty message bag that you can add messages to which are only stored in memory.

2. ResourceBundleBag
   Serves messages from a ResourceBundle that you give to it.

Message Format

Each message is represented by a so-called Message Key. The key is simply a string which uniquely identifies the message template itself. Properties files are great examples of that concept:

player-kicked=<player> was kicked by <admin>.
player-banned=<player> was banned by <admin> for <reason>.

In this example the keys are player-kicked and player-banned.

Instantiating Tolker

Instantiating Tolker is pretty easy. You simply provide it with a MessageBag and you're good to go. We'll use the ResourceBundleBag with the following messages.properties in this example.

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

class MyPlugin extends JavaPlugin implements Listener
{
    private Tolker tolker;

    public void onEnable()
    {
        // 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();

        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event)
    {
        // Send the welcome-message to the joining player with the given
        // objects as values for the corresponding placeholders
        tolker.build("welcome-message")
                .with("player", event.getPlayer())
                .with("world", event.getPlayer().getWorld())
                .send(event.getPlayer());
    }
}

Custom Type Serializers

Tolker supports custom type serializers. To add a custom one, create a class which extends the TypeSerializer<T> interface. Here's an example for a serializer for the UUID object:

public class UUIDSerializer implements TypeSerializer<UUID>
{
    public @NotNull Component serialize(@NotNull UUID obj)
    {
        return Component.text(obj.toString());
    }
}

After creating it, register it to Tolker after it was instantiated:

Tolker tolker = new Tolker(/* Message Bag */);
tolker.registerSerializer(UUID.class, new UUIDSerializer());

You can now pass UUID objects as a value to the MessageBuilder#with method.