Creating a Plugin

Description

This tutorial will teach you how to create Matix plugins using maven3. I’m using intelliJ idea CE, but you can use your editor or IDE of choice.

Setup

Requirements

You will need:

  • basic knowledge of java
  • basic knowledge of minecraft modding
  • maven3 installed and setup correctly (if you’re using intelliJ idea, you can just enable the plugin and use it from the IDE)
  • the Matix plugin template (optional, but recommended)

Maven

First of all make sure that maven is installed correctly. To do this, open a terminal window (Windows: Win+R -> cmd) and enter:

mvn --version

this should something along the lines of:

Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-17+01:00)
Maven home: PATH/TO/MAVEN/bin/
Java version: 1.8.0_112, vendor: Oracle Corporation
Java home: PATH/TO/JAVA/Java/jdk1.8.0_112/jre
Default locale: de_DE, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"

If instead you get “unknown command”, make sure you haven maven installed and added to your PATH variable. (https://www.tutorialspoint.com/maven/maven_environment_setup.htm).

Getting a plugin template

If the mvn command works fine, you can continue to get the Matix plugin template. This is optional, but I would highly recommend this for beginners. You have three options:

  • Use the MatixPluginsBuilder to generate a template with the correct plugin name
    1. Go to https://bitbucket.org/matixclient/matixpluginsbuilder/downloads/ and download the MatixPluginsBuilder.jar
    2. Move the MatixPluginsBuilder.jar to a directory that will hold all of the plugins made by you.
    3. Download the create.bat (windows) or create.sh (unix) and move it next to the MatixPluginsBuilder.jar
    4. Open a command prompt (windows: Shift+Right Click in the explorer folder, select Open Command Prompt)
    5. Execute the create script create.bat <name of your plugin> <matix version the plugin is built for>. To get the exact same structure as the template linked below, enter create.bat Template 1.12-1.8.2B
  • Use git to clone the template (this assumes that you know how to use git and are on a unix based system. If you know how to use git and are on windows, use the equivalent commands please)
    1. Open a command prompt and cd into the directory that will hold all plugins made by you
    2. Execute git clone git@bitbucket.org:matixclient/plugin-template.git <name of your plugin>
    3. cd into the folder you just created
    4. Execute rm -rf .git/ followed by git init to create an empty git repository
  • Download a zip of the repository template
    1. Open https://bitbucket.org/matixclient/plugin-template/downloads/ and select Download repository
    2. Move the zip to a folder that will hold all plugins made by you
    3. Extract the zip and change the name of the folder to your desired plugin name

If you used the MatixPluginsBuilder.jar to create your plugin template, you will now have to create a module class yourself. To do this, create an empty package in src/main/java/. The template uses de.paxii.clarinet.module.external, but you can use also your own package. Now, create a new module class with the name Module<YourModule>.java (inside of src/main/java/de/paxii/clarinet/module/external or your own package). The plugin has to extend de.paxii.clarinet.module.Module.

If you used git clone or the Download repository method, you will now have to rename the created module class. Open src/main/java/de/paxii/clarinet/module/external and change the name of the ModuleTemplate.java.

To automatically load your plugin when Matix starts, you will have to modify the contents of the file src/main/resources/META-INF/services/de.paxii.clarinet.module.Module. It contains the fully qualified name of your plugin’s class, so replace the name (and package, if you changed that) inside of it as well. Do not rename the file itself. This will break loading of the plugin.

You should now have the following structure inside of your plugin folder (replace every occurrence Template with the name of your plugin, of course):

Template/
  .gitignore
  src/
   main/
    java/
     de/
      paxii/
       clarinet/
        module/
         external/
          ModuleTemplate.java
   resources/
    META-INF/
     services/
      de.paxii.clarinet.module.Module
    module.json
  pom.xml

Developing a Plugin

Plugins use the default Module as superclass. You can look at it here. The most basic plugin would look something like this.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
package de.paxii.clarinet.module.external;

import de.paxii.clarinet.module.Module;
import de.paxii.clarinet.module.ModuleCategory;
import de.paxii.clarinet.util.chat.Chat;

public class ModuleTemplate extends Module {

  public ModuleTemplate() {
    super("Template", ModuleCategory.OTHER);

    this.setVersion("1.0");
    this.setBuildVersion(18200);
    this.setDescription("A module template.");
  }

  @Override
  public void onEnable() {
    Chat.printClientMessage("Template works!");
  }

}

In the constructor, you have to call the constructor of the Module class. It takes the following parameters:

  • module name
  • category of the module
  • optional: Default keybind of the module

You will also have to define the version (human-readable version) and the buildVersion (integer used to compare versions) of plugins, so the user will get an update notification if they open the game with your plugin installed. If you want to use events inside of you plugin, make sure to call this.setRegistered(true); inside of your constructor to automatically register the module for events when it’s enabled.

All existing plugins are hosted on BitBucket, so you can check their source out here. For a list of available Events, check out the event package.

Compiling a plugin

Once you’re done with hacking, you will want to compile your plugin and create a plugin.jar out of it. Since we’re using maven, this is super easy. Simply execute mvn package inside of your plugin directory to get a target folder that holds a

PluginName.jar and a PluginName-with-dependencies.jar. Depending on whether or not you included external libraries, you will want to either use the default or the one with dependencies included. For most plugins, the default jar will suffice.

Once your jar is created, you can drop it into the modules Folder. At this point you can either restart Minecraft or execute #reload in the chat.