Quick Start

In this article, you will learn how to create an UltiTools module and how to use UltiTools-API in your own plugin.

Create a new Spigot project

Everything starts with an empty project, so you need to create an empty Spigot project. You can use IDEA's Minecraft plugin to quickly create an empty Spigot project, or manually create an empty maven project.

Add UltiTools-API to your project

Whether you are creating an UltiTools module or using UltiTools-API, you need to add UltiTools-API to your dependencies in your Java project.

Maven

<dependency>
  <groupId>com.ultikits</groupId>
  <artifactId>UltiTools-API</artifactId>
  <version>{VERSION}</version>
</dependency>

Gradle

dependencies {
  implementation 'com.ultikits:UltiTools-API:{VERSION}'
}

The newest version of UltiTools-API can be found in Maven Central.

Reload your project after adding the dependency.

Create a new UltiTools module

The following content will teach you how to create an UltiTools module.

If you just want to use UltiTools-API in your own plugin, you can jump to Use UltiTools-API.

Create a module metadata file

Before you start writing code, you need to create a plugin.yml file in the resources folder.

UltiTools will read this file before loading the module to confirm the main class of the module.

# Module name
name: TestPlugin
# Module version
version: '${project.version}'
# Module main class
main: com.test.plugin.MyPlugin
# UltiTools API version, for example 6.0.0 is 600
api-version: 600
# Module authors
authors: 
  - yourname

Create the main class of the module

Create a new class that extends UltiToolsPlugin, similar to traditional Spigot plugins, UltiTools modules also need to override the startup and shutdown methods. But UltiToolsPlugin adds an optional UltiToolsPlugin#reloadSelf() method for execution when the module is reloaded.

// This annotation contains automatic registration and must be added to the module main class
@UltiToolsModule
public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() {
      // Executed when the module is started
      // If false is returned, UltiTools will not load this module
      return true;
    }
    
    @Override
    public void unregisterSelf() {
      // Optional, 
      // if you only need to unregister all commands and listeners, 
      // you don't need to override this method
      // Executed when the module is unregistered
    }
    
    @Override
    public void reloadSelf() {
      // Optional,
      // if you only need to reload the module configuration file,
      // you don't need to override this method
      // Executed when the module is reloaded
    }
}

Then you have completed an UltiTools module that does nothing.

Utilize UltiTools-API in your plugin

TIP

If you are writing an UltiTools module that relies entirely on UltiTools to run, please skip this section and refer to the previous section!

Create a connector class

Create a new class that extends UltiToolsPlugin, this class will be the connector class of your plugin.

import com.ultikits.ultitools.abstracts.UltiToolsPlugin;
import com.ultikits.ultitools.annotations.EnableAutoRegister;

import java.io.IOException;
import java.util.List;

// This annotation is required for automatic registration
@EnableAutoRegister(scanPackage = "com.ultikits.plugin.ultikitsapiexample")
public class UltiToolsConnector extends UltiToolsPlugin {
    
    // If you need to connect to UltiTools-API, you need to override this constructor with parameters,
    // the other one without parameters is for module development.
    // Please do not use the constructor without parameters here
    public UltiToolsConnector(String name, String version, List<String> authors, List<String> depend, int loadPriority, String mainClass) {
      super(name, version, authors, depend, loadPriority, mainClass);
    }
    @Override
    public boolean registerSelf() {
        // Executed when the module is started
        // If false is returned, UltiTools will not load this module
        return true;
    }

    @Override
    public void unregisterSelf() {
        // Optional, 
        // if you only need to unregister all commands and listeners, 
        // you don't need to override this method
        // Executed when the module is unregistered
    }

    @Override
    public void reloadSelf() {
        // Optional,
        // if you only need to reload the module configuration file,
        // you don't need to override this method
        // Executed when the module is reloaded
    }
}

Register your connector class

Since your plugin is not loaded by UltiTools, you need to manually register your connector class to the UltiTools plugin manager.

import com.ultikits.ultitools.UltiTools;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.Collections;

// Your plugin main class
public final class UltiKitsExample extends JavaPlugin {
    @Override
    public void onEnable() {
        // Register this connector class to the UltiTools plugin manager
        UltiTools.getInstance().getPluginManager().register(
                UltiToolsConnector.class,
                "Example",  // Name
                "1.0.0",  // Version
                Collections.singletonList("wisdomme"),  // Authors
                Collections.emptyList(),  // Load after
                600,  // UltiTools API minimum version
                "com.ultikits.plugin.ultikitsapiexample.UltiToolsConnector"  // Full class name of the connector class
        );
    }
    
    @Override
    public void onDisable() {
        // Remember to unregister the connector class from the UltiTools plugin manager when the plugin is unloaded
        UltiTools.getInstance().getPluginManager().unregister(UltiToolsConnector.getInstance());
    }
}

Verify installation

If it is a module, put the module in the plugins/UltiTools/plugins folder and restart the server.

If it is a plugin connected to UltiTools, put the plugin in the plugins folder and restart the server.

Use this command in the game by OP or in the command line to verify that you have successfully connected to UltiTools.

ul list

If everything goes well, you should see the name and version of your plugin in the output.

ul list
[12:42:16] [Server thread/INFO]: BasicFunctions 1.0.0
[12:42:16] [Server thread/INFO]: UltiTools-Login 1.0.0
[12:42:16] [Server thread/INFO]: UltiTools-MysqlConnector 1.0.0
[12:42:16] [Server thread/INFO]: UltiTools-SidebarPlugin 1.0.0
[12:42:16] [Server thread/INFO]: Example 1.0.0           <--- This is our plugin

In the following articles, you will learn how to use commands, events, configuration files, data storage, development annotations, etc.