Documentations

Hello and welcome to the Sprummlbot documentations. You can learn how to configure and use the bot and also how to interact with the bot.

Last updated: 6th October 2016

Quick Jump

settings 0.4.0+

Please refer to the forum post.

power 0.4.7

Prerequisites

First of all you will need Java Development Kit 8 or newer. If you are new to Java, then choose an IDE. I use IntelliJ IDEA. IntelliJ IDEA is a user friendly and nice looking IDE for Java. A good alternative to IntelliJ IDEA is Eclipse. And you also need the latest Sprummlbot.jar

This tutorial can differ, if you use an older or newer version than IntelliJ IDEA Community 2016.1.1!

Getting Started

Classpath

So after you have installed JDK8 and IntelliJ, you have to create a new project by clicking Create New Project. Then select Java in the sidemenu, if not already selected. Click Next. Click Next again and give your project a name. Optionally you can change the project's location. Now you need to import the latest Sprummlbot.jar file into our project. Click on File, then on Project Structure. Now you have to click on Libraries. There you have to click on the add and then Java. You will have to select the JAR file in the following menu. After it was selected you can close the windows via OK.

Package structure and main class

Now you can start creating our structure. First of all you will create a package. Right click the src folder and click New, Package. Packages in Java should be named like the following example net.scrumplex.sprummlbot. After you have created a package, Right click the package and click New and then Java Class. Just name it Main or YourPluginName. Now your class should look like something like this:


package net.scrumplex.testplugin;

public class Main {
}

Now change the class to:


package net.scrumplex.testplugin;

import net.scrumplex.sprummlbot.plugins.SprummlbotPlugin;

public class Main extends SprummlbotPlugin{
}

Defining plugin information

After you created a basic SprummlbotPlugin class, you have to create a plugin.ini file. Right click your project on the left pane and click New, File and enter plugin.ini. Here is an example file:


[Plugin]
main = net.scrumplex.testplugin.Main

[Information]
name = DummyPlugin
version = 1.0
author = Scrumplex

You MUST change main to your package name and class name. So if your package's name is com.example.bestplugin and your main class' name Main, it has to be com.example.bestplugin.Main. CASE SESITIVE!

Enable Disable events

The SprummlbotPlugin class offers two methods for loading and unloading. To do something on plugin load (e.g. Registering commands).

onEnable() and onDisable() functions


@Override
public void onEnable() {
    //do something on plugin load
}

@Override
public void onDisable() {
    //do something on plugin unload
}

Interacting with the TeamSpeak 3 Server

Work in progress

Understanding the command system

The Sprummlbot command system is fully managed via code. So if you want to register a command, you have to do it via code. The Sprummlbot has PermissionGroups. These are groups, where clients can be put into. You, as a plugin developer, can also use these PermissionGroups. So if you create a command, which should be only accessible by admins, you could set the PermissionGroup to Admins for example. The Sprummlbot also has a syntax error handler. While registering a command, you can set a usage definition.


Registering a command

Basic command


CommandManager commandManager = getCommandManager();
ChatCommand cmdHelloWorld = commandManager.registerCommand("helloworld");

So this example will get the CommandManager class, which the Sprummlbot is using. The second line registers a basic command which, would be triggered by typing !helloworld. This command will be accessible by everyone.

Command with usage


CommandManager commandManager = getCommandManager();
ChatCommand cmdHello = commandManager.registerCommand("hello", "!hello <Username>");

Now this example will get the CommandManager class, which the Sprummlbot is using. The second line registers a basic command with a usage definition. This command will be accessible by everyone.

Setting the command handler

If you now want to give your command a function, you will have to add a CommandHandler to the ChatCommand.


cmdHello.setCommandHandler(this, new CommandHandler() {
    @Override
    public CommandResponse handleCommand(ClientInfo clientInfo, String[] args) throws Exception {
        getAPI().sendPrivateMessage(clientInfo.getId(), "[B]Hello[/B] " + clientInfo.getNickname() + "!");
        return CommandResponse.SUCCESS;
    }
});

This method will set the CommandHandler for the ChatCommand. The CommandHandler is an interface and could be implemented in another class.
CommandHandler#handleCommand() has to return a CommandResponse enum.

CommandResponse types

Type Description
CommandResponse.SUCCESS This should be returned if the command was successfully executed.
CommandResponse.ERROR This should be returned if the command was executed with an error.
CommandResponse.SYNTAX_ERROR This should be returned if the command was not used correctly.
CommandResponse.FORBIDDEN Internal This should be returned if a client is not permitted to use a command.
CommandResponse.INTERNAL_ERROR Internal This should be returned if an exception occurred while executing.
CommandResponse.NOT_FOUND Internal This should be returned if a command was not found.

http 0.4.7

Work in progress