English

API Tutorial

Whats an API?

The API of AdminTools3 can be used by Developers to integrate their plugins into the GUI as modules or add custom modules to the GUI.

This example will show how to do so. You need basic Java Knowledge and Bukkit Knowledge to follow along! Learn creating your own plugin FIRST, then learn how to use APIs!!

Getting started

Add AdminTools3 to your plugin (add the .jar file in eclipse and intellij)

It is absolutely required that admintools runs on the target server as well!! You have to tell your users this as well, as there are people out there who don't know what "api" or "dependency" means!!!

Your own Module

Each module has to extends dev.wwst.admintools3.modules.Module. Your IDE will tell you to create a constructor and the execute method.

The Constructor

In the Constructor, call super() with these arguments: super(boolean needsWorld, boolean needsPlayer, String moduleName, dev.wwst.admintools3.utils.XMaterial material);

  • needsWorld: This tells AdminTools if your module needs a world as an argument.

  • needsPlayer: This tells AdminTools if you module can be executed on another player as well. If you use true here, the user can still apply the module to himself, but he can also select another player

  • name: This tells AdminTools the name of your module. It will then retrieve the displayName from the messages.yml file. (More on adding your own translations later)

  • material: This is the Material that the Item in the GUI will have. To ensure Cross-Version compatibility, you have to use XMaterial (in the utils package)

You can also add these options in the constructor:

useDefaultMessageKeyFormat = false will remove the default message sending (module.[modulename].messages.applyToSelf and others. You need this if you want to use your own message format. Please note that error messages, such as "You don't have permission" or "you have to supply a world" will still be fetched from messages_XX.yml and sent to the player, because they are static for all Modules and your module has no idea what exactly didnt work, it just gets a boolean.

basePermission = "" The basePermission is, per default, "admintools3.module.[moduleName]". If you want to change this so that it uses your permission format, you can do so. Any player with the new permission you set can execute the module on himself and others.

permissionSelf = "" The selfpermission is, per default, "admintools3.module.[moduleName].self". If you want to change this so that it uses your permission format, you can do so. Any player with the new permission you set can execute the module on himself, but not on others.

itemname = "", itemLore = "" if you don't want to use the MessageTranslator of AdminTools (more on that later), you can always set these yourself.

aliases.add(String alias) to add your own aliases, if you don't want to use the admintools default config but might use your own or hardcode these - it's up to you.

The execute method

public boolean execute(Player player, Player other, World world)

  • player is the player who executed the module, e.g. who clicked in the GUI or who sent the command.

  • other is the player himself if he left-clicked, or the player he selected if he right-clicked

  • world is the world he selected (if you chose to set needsWorld to true, or in the command)

Please paste these lines of code at the beginning of all execute methods of all your modules:

if(!super.execute(player, other, world)) {
    return false;
}

The execute method in module does many things, and unless you want to recode them all, just use the small code snippet at the start of all of your Modules and you are good.

  • It checks for permissions on the player (you can change the permissions it checks for in the constructor options)

  • It checks for a world and a player, if you selected those options in the constructor

  • It checks for a cooldown, if one could be loaded from the config or was set directly AND the player doesnt have the bypass permission

  • It sends the messages it could load from messages.yml unless you disabled useDefaultMessageKeyFormat (in that case you have to do that yourself)

  • It logs the player, the module, the target and the world unless that option was set to false in the config.

You can do anything you want after those three lines, but remember to return true; at the end of the method to not get an error.

Registering the module

in your onEnable method, or any other place that gets called when the plugin is loaded, please add these lines:

 dev.wwst.admintools3.modules.ModuleLoader moduleLoader = dev.wwst.admintools3.modules.ModuleLoader.getInstance();
 moduleLoader.registerModule(new YourModule());

This is how you register your modules.

Finally, you have to set AdminTools as a depends (if you want that your plugin doesnt load if AdminTools3 isnt present) or softdepends (if you just want AdminTools3 to load first, this also means that you have to check for AdminTools3 yourself) of your plugin in your plugin.yml

Adding a custom message file

You might want your plugin to have its own message files - and thats ok!

If these message files follow the message format of AdminTools3 (which can be seen in any AdminTools3 messages_XX.yml file), you can just add them to the MessageTranslator and use the default key format. (This will make your life WAY easier).

Simply add this snippet to your onEnable:

 dev.wwst.admintools3.util.MessageTranslator msg = dev.wwst.admintools3.util.MessageTranslator.getInstance();
 msg.loadMessageFile("plugins//Yourplugin//anypath.yml");

This will add all keys in that configuration to the messages list, which means that you can then use the MessageTranslator and its beautiful abilites in any of your modules as well.

Examples

TestModule:

AdminTools - TrollAddition (full plugin):

PreviousPermission list

Last updated