blombler008 / teamspeak-3-bot

Teamspeak3Bot with build in plugin manager for users creation

Teamspeak 3 Bot

This bot is 'Plugin Based', Which means Admins/Users are able to Create their own plugins for their server. Which uses the TeamSpeak-3-Java-API by TheHolyWaffle as engine.

Features

• Plugins can be loaded while running the query client.
• MySQL driver, ready to connect.
• Command and Event manager.

Usage

To use the bot you can simply create a folder (eg. mkdir /home/example/bot) and download put the Teamspeak-sq-bot.jar in that folder. As soon as you execute the jar, a folder called Teamspeak3Bot is created in that same directory where the bot jar lays. You can specify the work dir by using the start parameter workDir. The Default work directory is ./Teamspeak3Bot.

Maven (Coming soon)

Standalone(jar)

If you are not able to use maven you can download the standalone jar with dependencies and implement that into your project.

Parameters

Parameters are used like the following (--Key=Value). A start parameter always starts with two dashes.

Option	Value	Required	Example	Description
debug		No	--debug	Enables the Debugger. NOTE: Complete information about the server query is shown (Password, Username, Server address, Port, etc)
workDir	bot's work directory	No	--workDir=/etc/bot/	Changes the work directory to the given path if valid. DEFAULT: ./Teamspeak3Bot
auth-key			--auth-key=abcdefgh	Only uses while developing

Config

The config is a simple properties file called config.ini, which is located and generated in the work directory. The first two lines of the config file is a comment, comment always starts with #. NOTE: Everything has a key, a value and is required.

Option	Default	Example	Description
nickname	serverquerybot	nickname=Example Bot	Gives the bot a nickname when connecting to the server. Users who gets a message from the bot will see this name.
port	10011	port=12345	Server Query port to connect
host	127.0.0.1	host=ts.example.com	The hostname/Ip-address of the server
username	username	username=example	Username to login as server query
password	password	password=12345678	Password to login as server query
prefix	\!	prefix=\!	The command prefix for the com.github.theholywaffle.teamspeak3.commands entered by user in Teamspeak. NOTE: Special characters need a backslash like the ! to be recognized!
lang	english	lang=english	Let you change the language for plugins
owner	1234567890abdef	owner=zbv5DDqRa3jy4LuM1cfUeyurud8\\=	Sets the owner of the bot, so the owner kan execute admin commands first before any of the other users. NOTE: Put the UID from your own client in this property
channel	0	channel=0	Sets the channel where the bot ist going to connect to. NOTE: invalid channel id causes errors

Commands

A list of Commands

Command	Aliases	Parameters	Examples	Description
uploadErrorLog			uploadErrorLog	Uploads the log file to pastebin. NOTE: Make sure that the debugging mode is used (with the debug parameter on start).
help	[help, ?]	[command]	help, help example	Shows the help of the given parameter, and list of commands if no parameter is present.
reload	[reload, rl]	[plugin]	reload, reload ExamplePlugin-v1	Reloads the given plugin, and reloads all plugins if no parameter is given
plugins	[plugins, pl]		plugins	Shows a list of plugins.
stop	[stop, quit, exit]		stop	Logs out of the teamspeak server query and exit the program.

Examples

Adding an event listening

To add an event listener you have to add the event class to the event manager. Like Shown in the Example class.

public class Example extends JavaPlugin {
    public void onEnable() {
        getInstance().getEventManager().addEventToProcessList(new ExampleEvent());
    }
}

Now we have to register an event in the ExampleEvent class, it have to implement the Listener interface. The annotation @EventListener lets the manager know the following method is a event listener. The name of the method does not matter, what matter does is the parameter, make sure it is only one and extends the Event class.

public class ExampleEvent implements Listener {
    @EventListener
    public void onTextMessage(EventTextMessage e) {
        // do stuff
   }
}

List of Events

Events always starts with Event in the beginning.

• EventChannelCreate
• EventChannelDeleted
• EventChannelDescriptionChanged
• EventChannelEdit
• EventChannelMoved
• EventChannelPasswordChanged
• EventClientJoin
• EventClientLeave
• EventClientMoved
• EventCommandPreProcess
• EventPrivilegeKeyUsed
• EventServerEdit
• EventTextMessage

Adding an command

To create a command we have to put in our plugin.ini the command.

# Main, Version, Plugin Descruption, Plugin Name ....
commands:
  example:
     description: A example command
     usage: [optional] <required>
     aliases: [example,ex]

Now we have to get the command template from the list of commands and add an executor to the command.

public class Example extends JavaPlugin {
    public void onEnable() {
        getInstance().getCommandManager().getCommand("example").setExecutor(new ExampleCommand());
    }
}

In the ExampleCommand class we have let it extend CommandExecutor and implement the run method. The run method is executed when a user enters the command or alias.

public class ExampleCommand extends CommandExecutor {

    @Override
    public void run(CommandSender source, Command cmd, String commandLabel, String[] args) {
        // do stuff
    }    
}

Examples can be found here are 2 files of the examples on top ...

teamspeak-3-bot's Issues

Some tips and enhancement

Generally, your project is pretty solid. However, I have some suggestions for you:

1. .gitignore:
   You should update your .gitignore file to exclude unnecessary files. For a default file for Java see here. But you should also add some custom values such as:

   # IntelliJ files (no one needs your project configurations)
   /.idea
   *.iml
   
   # Java's meta informations (will be generated when running the application inside the IDE)
   /META-INF
   
   # The used sources should be linked externally, if you really want to use such a folder, call it libs
   # You may want to think about using Maven since all dependencies are added to a pom.xml, so no one needs to add them.
   /Apis
   
   # Building files (they differ since not everyone is using the same IDE, path, etc)
   build.*
   
   # Other files that are not required to successfully run the application.
   # Think about it yourself.
   ...

2. Java's naming conventions:
   You mixed a few naming conventions from other programming languages, you should try to convert every class, method and package name to Java's default conventions.

   • Class names are written in upper-case letters (e.g. MyImportantClass),

   • method names start with a lower-case letter and are written in lowerCamelCase (e.g. myMethodThatDoesStuff,

   • packages are written in all lower-case letters (e.g. com.test.myprogram),

   • and finally: folder names should be all lower-case letters (such as src, examples, etc.)

     Note: Neither of these should contain any other characters than letters and numbers (so no underscore, backslash, etc.).

3. A general resource folder:
   You may want to add a general resource for all your configurations such as languages (btw. do you really need the assets/lang folder, since you never use it?). However, the general idea of such a folder is to organise all external files the applications works with. So, a configurations and language files goes there and any other file, the client can adjust/the applications works with that is not inside the build itself (note that you do not need to call it resources, any other name works just as well).

4. Packages:
   Generally, packages should be meaningful. Thus, you may want to think about more than just three packages. As I can tell, you have several classes that are not the main class in your main package. So, instead of putting them all in one package, you may want to add an extra package (e.g., plugins where all the classes that manage the loading process of external plugins should be located).

5. Comments:
   Since your project is public you may want to think about commenting your code so other contributors can easily understand what you want to do in a method. Especially, because you provide some kind of API so one can extend your application with custom applications.

6. static:
   You may only declare a variable or method as static when it's necessary: Use instance variables instead, so you could initialise a new instance of your class in the main method of the class. Such as:

   public class Teamspeak3Bot {
       public static void main(String[] args) {
           new Teamspeak3Bot();
       }
       
       // Note that the constructor is private to prevent initialization from other classes
       private Teamspeak3Bot() {
           // Do whatever you did in your main method.
       }
   }

7. Other minor tips:

   • In some classes, you have two license headers, one above and one beneath the package declaration
   • [TO BE CONTINUED]

Remember, these are just tips and I do not want to speak badly of your project (as stated, it's a solid project), I just want to help you improve your project! 😄