Plugin Tutorial: Discord Integration

Tutorial covering the development of a simple game server plugin

Let's write a simple game server plugin to log player messages sent in-game to a Discord channel using a webhook. No prior knowledge is needed for this tutorial (obviously, beyond Java).

Baby steps

Start by including the module containing the Irminsul API into your project.

    <dependency>
        <groupId>io.irminsul</groupId>
        <artifactId>common</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope> 
    </dependency>

Create your main plugin class and extend the GamePlugin class located in io.irminsul.common.plugin. Implement the required onEnable and onDisable methods.

Your plugin must have a public constructor that takes in no parameters. Java creates this implicitly if you have no other constructor.

package dev.niqumu.discordplugin;

import io.irminsul.common.game.GameServer;

public class DiscordPlugin extends GamePlugin {
    
    /**
     * Called by the plugin manager when this plugin is enabled by the server
     */
    @Override
    public void onEnable() {
        this.logger.info("Plugin enabled!");
    }

    /**
     * Called by the plugin manager when this plugin is disabled by the server
     */
    @Override
    public void onDisable() {
        this.logger.info("Plugin disabled!");
    }
}

As you may have noticed in the onEnable and onDisable methods in this example, you have access to an SLF4J logger belonging to your plugin. You also have access to the GameServer to which your plugin is running on through the this.server field.

When exactly a plugin is instantiated, and what state the server is in at that time, is unspecified and up to the implementation. Our default game server makes no guarantees of safety or nullability at the time plugins are loaded. Place your logic in onEnable, not your constructor!

Next, we must create a plugin.properties file to provide some basic information about our plugin.

# Required. The internal ID of your plugin
id=discord-logging-plugin

# Optional, but highly recommended. The version of your plugin
version=1.0.0

# Optional, but highly recommended. The display/friendly name of your plugin
name=Discord Logger

# Optional, but highly recommended. A brief description of your plugin
description=Example plugin to demonstrate the Irminsul plugin API!

# Optional, but highly recommended. The author(s) of your plugin
author=Irminsul Team

# Optional. A website associated with your plugin, such as a Git repository
website=https://github.com/niqumu/Irminsul/

# Required. The main class of your plugin (whatever extends GamePlugin)
main=dev.niqumu.discordplugin.DiscordPlugin

By convention, plugin IDs are all lowercase, with words separated by dashes.

We strongly recommend following semantic versioning for your plugin version numbers! (major.minor.patch)

Let's try it out! Build your plugin using Maven via the Package task. Install the plugin using the steps shown in the Plugin Installation tutorial. Try running Irminsul and see what happens!

A screenshot of our plugin logging to the server console

You can also try using the plugins command to verify that your plugin is loaded, and to see some information on it.

Output of the plugins command, showing our plugin successfully loaded into the server. Nice!

It works! It's not very interesting though. Let's make our plugin actually do something.

Events

Most of your plugin logic will be based around subscribing to, and handling, events. The game server fires events for basically everything. You can subscribe to events, add your own logic on them, manipulate them, or even cancel them altogether.

Irminsul's event bus is simple. Register an object as an event subscriber, and methods annotated with @EventHandler will be called intelligently based on the event in the method parameters. Let's set up a basic handler for the PlayerLoginEvent event.

@Override
public void onEnable() {
    this.registerEventSubscriber(this);
}

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    this.logger.info("{} is logging in!", event.getPlayer().getProfile().getNickname());
}

Let's try it out!

A screenshot of our plugin logging when a player joins the server

It works! We can get all sorts of information on the player joining through the event. Since PlayerLoginEvent does not extend CancellableEvent, we aren't able to cancel the player login, since it's not really something we want to cancel.

Let's add a second event handler for the PlayerChatEvent event and see what we can do with it.

@EventHandler
public void onPlayerChat(PlayerChatEvent event) {
    this.logger.info("{} -> {}: {}", event.getSender(), event.getRecipient(), event.getText());
}

A screenshot of our plugin logging in-game player messages

This picture shows a player messaging the server console (UID 0). It works! Now, let's use a simple Discord webhook library to achieve our goal. If you aren't familiar with one, check out k3kdude's simple one-class webhook wrapper.

@EventHandler
public void onPlayerChat(PlayerChatEvent event) {
    DiscordWebhook webhook = new DiscordWebhook(webhookUrl);
    DiscordWebhook.EmbedObject embed = new DiscordWebhook.EmbedObject();

    webhook.setUsername("Plugin");
    embed.setTitle("%s -> %d".formatted(event.getSender().toString(), event.getRecipient()));
    embed.setDescription(event.getEmote() != 0 ? ("(emote " + event.getEmote() + ")") : event.getText());
    embed.setColor(Color.CYAN);
    embed.setFooter("Sent from %s %s".formatted(this.getPluginInfo().getName(), this.getPluginInfo().getVersion()), "");

    try {
        webhook.addEmbed(embed);
        webhook.execute();
    } catch (IOException e) {
        this.logger.error("Couldn't send message to webhook!", e);
    }
}

Let's try it out and send some messages to the server console!

A Discord screenshot of our plugin sending messages to a webhook. Success!

It works! We did it! We wrote a simple plugin to log player chat messages to a Discord webhook. We've began to explore the potentials of the Irminsul plugin API.