GettingStarted

How to write your first plugin

To get started you have to choose an IDE of your choice.

IntelliJ IDEA

First, create a new Java-Project. Select File -> New -> Project...

Select Maven in the menu and click "Next".

Enter a group id. This should be the reverse pattern of an url you own - in our case twasi.net turns into net.twasi. Also give your plugin a name. This is just the organizational name, you can change the display name shown by twasi later. Click "Next".

You don't have to change the project name here since it's just the name of the folder on your hard disk. Click "Finish".

After that, IntelliJ should've created an empty java maven application. Next we need to link to the Twasi artifactory in the POM.xml file to get access to the library.

Add this code to the file (inside the tags):

<dependencies>
  <dependency>
    <groupId>net.twasi</groupId>
    <artifactId>TwasiCore</artifactId>
    <version>0.0.1-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
    <id>central</id>
    <name>libs-release</name>
    <url>https://artifactory.twasi.net/artifactory/libs-release</url>
  </repository>
  <repository>
    <snapshots />
    <id>snapshots</id>
    <name>libs-snapshot</name>
    <url>https://artifactory.twasi.net/artifactory/libs-snapshot</url>
  </repository>
</repositories>

This code adds both our artifactory repository and the library dependency to your maven project.

Your pom.yml should now look somewhat similar to this:

Next we need to tell IntelliJ to fetch the new dependency. This can easily be done by right-clicking the pom.xml and selecting Maven -> Reimport. You don't really see something happening, but when starting to write code you will have all our Api Objects available.

Next let's create a package. The package should also follow the domain inversion pattern (reversed domain + . + projectname, e.g. net.twasi.justanexampleplugin). Right-click the blue highlighted java folder and select New -> Package. Enter the name as defined above.

Now your structure should look somewhat similar to this:

Let's create our first class to write actual code (it's about time ;) ) Right-click the newly created package and select New -> Java Class. Enter a name (maybe the name of your plugin, or just main - as you like).

I already implemented a minimal version - all it does is logging that it was enabled or disabled. If you done everything correct with the maven part, it should find the class TwasiPlugin.

Let's make our plugin somewhat kind. Here is the code to simply answer a command:

@Override
public void onCommand(Command command) {
  // This is called after a registered command is executed in any chat.
  // Do your thing here! This is what you're there for, isn't it?

  // if command name is hello (e.g. !hello)
  if (command.getCommandName().equalsIgnoreCase("hello")) {
    // then be kind and return a hello world
    command.reply("Hello World!");
  }
}

So we're getting to the last step: to the plugin.yml.

Right-click the resources folder and select New -> File. Enter plugin.yml as file name (case sensitive). This is our plugin configuration, in which we will provide some more necessary information about or plugin.

name: just-an-example-plugin
main: net.twasi.justanexampleplugin.ExamplePlugin
author: Twasi Team
description: This is just an example project.
version: 1.0

# This defines if the onMessage event should be called on incoming messages.
# You should only use this if you need this. To keep everything running
# smoothly and fast, please don't block for too long onMessage.
messageHandler: false

# Call our plugins Command Handler if !hello is executed.
# You have to register all your plugins commands here
# if you want to get all messages, please use onMessage.
# Please only use lowercase.
commands:
  - hello

Important is the main value: It has to be [Your package name] + . + [Your class name]. It tells the Twasi core where to find the class that then handles the events. You also need to decide if you need to listen for all incoming messages. And then in order for onCommand to work you have to register all commands you want to use in your plugin - in our case it's just hello.

Now we are ready to build our first .jar and deploy it to the Twasi core. We use the IntelliJ Maven integration for this. In the upper right corner, click the dropdown and select "Edit configurations". Click on the "+" icon and select maven.

Just write "package" in the command line input box, to generate a jar package.

Now let's run the build - apply and close the configuration and click the green "run" button (make sure the created build configuration is selected in the dropdown in the upper right corner).

The console should log that the build was succeeded. Also, a .jar file should be created in the target directory. Let's copy that jar file to the "plugins" folder of our twasi-core and run it!

And voilà: our message gets logged at the startup.

Let's also try it in a connected twitch chat:

Works perfect!