UltiTools 6

UltiTools' Reborn

---

	👈 Click to join Discord server!	点击右侧按钮加入官方 QQ 群！ 👉

UltiTools-API Introduction

中文文档

I hope my plugin can help with your plugin development! XD

Detailed Dev Documents

Annotation-driven

UltiTools-API has changed the way plugin development is done. By introducing advanced syntax like annotations, it makes your plugin development much more efficient.

With UltiTools-API, you no longer need to manually register commands and listeners. Simply add annotations to your command classes and listener classes, and UltiTools-API will automatically register them for you.

You can also write your commands like a controller. You no longer need to make tedious judgments for a command. Just add annotations to your command methods, and UltiTools-API will automatically match the commands to the corresponding methods.

@CmdTarget(CmdTarget.CmdTargetType.PLAYER)
@CmdExecutor(alias = {"lore"}, manualRegister = true, permission = "ultikits.tools.command.lore", description = "Lore edit function")
public class LoreCommands extends AbstractCommendExecutor {

    @CmdMapping(format = "add <lore...>")
    public void addLore(@CmdSender Player player, @CmdParam("lore...") String[] lore) {
        ...
    }

    @CmdMapping(format = "delete <position>")
    public void deleteLore(@CmdSender Player player, @CmdParam("position") int position) {
        ...
    }

    @CmdMapping(format = "edit <position> <lore...>")
    public void editLore(@CmdSender Player player, @CmdParam("position") int position, @CmdParam("lore...") String[] lore) {
        ...
    }

    @Override
    protected void handleHelp(CommandSender sender) {
        sender.sendMessage(ChatColor.RED + "lore add <content>" + ChatColor.GRAY + " - " + BasicFunctions.getInstance().i18n("Add Lore"));
        sender.sendMessage(ChatColor.RED + "lore delete <lineNum>" + ChatColor.GRAY + " - " + BasicFunctions.getInstance().i18n("Delete Lore"));
        sender.sendMessage(ChatColor.RED + "lore edit <linNum> <content>" + ChatColor.GRAY + " - " + BasicFunctions.getInstance().i18n("Edit Lore"));
    }
}

In terms of data storage, UltiTools provides wrapped APIs for both MySQL and JSON, allowing you not to worry about which data storage method the users will choose.

For example

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
@Table("economy_accounts")
public class AccountEntity extends AbstractDataEntity {
    @Column("name")
    private String name;
    @Column(value = "balance", type = "FLOAT")
    private double balance;
    @Column("owner")
    private String owner;
}

// check if the player account exists
public boolean playerHasAccount(UUID player, String name) {
    DataOperator<AccountEntity> dataOperator = UltiEconomy.getInstance().getDataOperator(AccountEntity.class);
    return dataOperator.exist(
            WhereCondition.builder().column("name").value(name).build(),
            WhereCondition.builder().column("owner").value(player.toString()).build()
        );
}

Regarding configuration files, UltiTools allows you to read the configuration files as if you were manipulating objects.

For example

@Getter
@Setter
@ConfigEntity(path = "config/config.yml")
public class EcoConfig extends AbstractConfigEntity {
    @ConfigEntry(path = "useThirdPartEconomy", comment = "Whether to use another economy plugin as a base (i.e., only use the bank function of this plugin)")
    private boolean useThirdPartEconomy = false;
    @ConfigEntry(path = "enableInterest", comment = "Whether to enable interest")
    private boolean enableInterest = true;
    @ConfigEntry(path = "interestRate", comment = "Interest rate, interest = interest rate × principal")
    private double  interestRate = 0.0003;
    @ConfigEntry(path = "interestTime", comment = "Interval for interest distribution (minutes)")
    private int interestTime = 30;
    @ConfigEntry(path = "initial_money", comment = "Initial amount of currency for players")
    private double initMoney = 1000;
    @ConfigEntry(path = "op_operate_money", comment = "Whether the server administrator can increase or decrease player currency")
    private boolean opOperateMoney = false;
    @ConfigEntry(path = "currency_name", comment = "Name of the currency")
    private String currencyName = "Gold Coin";
    @ConfigEntry(path = "server_trade_log", comment = "Whether to enable server trade log")
    private boolean enableTradeLog = false;
    public EcoConfig(String configFilePath) {
        super(configFilePath);
    }
}

// Get the configuration file of the economy plugin and read the interest rate
EcoConfig config = UltiEconomy.getInstance().getConfig(EcoConfig.class);
double interestRate = config.getInterestRate();

IOC Container

UltiTools-API provides a Spring IOC container, which can manage all the Beans in your plugin and automatically inject dependencies.

// @Service marks the type as a Bean, and UltiTools-API will automatically scan and register it
@Service
public class BanPlayerService {
    
    ...

    public void unBanPlayer(OfflinePlayer player) {
        DataOperator<BanedUserData> dataOperator = BasicFunctions.getInstance().getDataOperator(BanedUserData.class);
        dataOperator.delById(player.getUniqueId().toString());
    }
}

@CmdTarget(CmdTarget.CmdTargetType.BOTH)
@CmdExecutor(permission = "ultikits.ban.command.all", description = "Ban function", alias = {"uban"}, manualRegister = true)
public class BanCommands extends AbstractCommendExecutor {
    
    // Using the @Autowired annotation, UltiTools-API will automatically inject the dependency
    @Autowired
    private BanPlayerService banPlayerService;

    @CmdMapping(format = "unban <player>")
    public void unBanPlayer(@CmdSender CommandSender sender, @CmdParam("player") String player) {
        banPlayerService.unBanPlayer(Bukkit.getOfflinePlayer(player));
        sender.sendMessage(BasicFunctions.getInstance().i18n("§aUnban successful"));
    }
    
    ...
}

If you don't like automatic injection, or can't use automatic injection, you can also manually obtain the Bean.

BanPlayerService banPlayerService = getContext().getBean(BanPlayerService.class);

Providing Numerous Modern Dependency Libraries

UltiTools-API offers some functionalities of Hutool, including a large number of utility classes.

Hutool Documentation

In terms of GUI interfaces, UltiTools provides the obliviate-invs API, facilitating rapid GUI development.

ObliviateInvs — Highly efficient modular GUI library

UltiTools also offers the Adventure API.

Adventure Documentation

Quick Start

For more detailed documentation, please refer to UltiTools API Documentation

Below is a simple quick start guide.

Installing Dependencies

First, add the UltiTools-API dependency to your project.

Using Maven

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

Using Gradle

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

Before starting, please create a plugin.yml file in the resources folder with the following content:

# Plugin name
name: TestPlugin
# Plugin version
version: '${project.version}'
# Plugin main class
main: com.test.plugin.MyPlugin
# UltiTools-API version used by the plugin, for example, 6.0.0 is 600
api-version: 600
# Plugin authors
authors: [ wisdomme ]

Create a config folder, where you can put your plugin configuration files according to your needs. These configuration files will be placed unmodified in the collective configuration folder of the UltiTools plugin for display to users.

Simple Guide

Create a main class extending UltiToolsPlugin. Similar to traditional Spigot plugins, UltiTools plugins also need to override the start and stop methods. However, UltiToolsPlugin adds an optional UltiToolsPlugin#reloadSelf() method for use during plugin reload.

public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() {
        // Executes when the plugin starts
        return true;
    }

    @Override
    public void unregisterSelf() {
        // Executes when the plugin shuts down
    }
    
    @Override
    public void reloadSelf() {
        // Executes when the plugin is reloaded
    }
}

With this, you've completed an UltiTools plugin that does nothing. Then, you can register your listeners and commands in the UltiToolsPlugin#registerSelf() method.

public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() {
        // Register a Test command, with permission 'permission.test', and command 'test'
        // No need to register the command in Plugin.yml
        getCommandManager().register(new TestCommands(), "permission.test", "Sample Function", "test");
        // Register listeners
        getListenerManager().register(this, new TestListener());
        return true;
    }
}

Then, you can add your configuration file in the main class, and UltiTools will automatically load the configuration file.

public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() {
        // Register a Test command, with permission 'permission.test', and command 'test'
        // No need to register the command in Plugin.yml
        getCommandManager().register(new TestCommands(), "permission.test", "Sample Function", "test");
        // Register listeners
        getListenerManager().register(this, new TestListener());
        // Register configuration file
        getConfigManager().register(this, new TestConfig("config/config.yml"));
        return true;
    }
}

Alternatively, you can override the UltiToolsPlugin#getAllConfigs() method to register all configuration files here.

@Override
public List<AbstractConfigEntity> getAllConfigs() {
    return Arrays.asList(
            new TestConfig("config/config.yml")
    );
}

WakaTime Statistics

Development Timeline Statistics

Click to view statistics

Main Contributors

Contributor	Description
@wisdommen	Founder, UltiKits Author
@qianmo2233	UltiTools Developer, Main Maintainer of UltiKits Development Documentation
@Shpries	UltiTools Developer
@JueChenChen	Feedback on UltiKits Issues, Bugs & Suggestions
拾柒	Graphic Designer

Found an Issue? Want to Make a Suggestion?

Click here to submit an Issue!

Acknowledgments

	Dep checker
	Offical CI Tool
	Development language
	Recorded every moment of our development journey
	The strongest Java IDE for a pleasant development experience
	Helped solve many repetitive and tedious tasks
	Brought many high-tech features to the plugin
	Official build tool
	Official built-in WebSocket client