[插件开发][1.8.8-1.20.6] UltiTools-API 简单|高效|注解驱动的插件开发体验

wisdomme 发表于 2024-7-2 15:27:13

本帖最后由 wisdomme 于 2024-7-26 12:03 编辑

https://github.com/UltiKits/UltiTools-Reborn/assets/62180110/f5e8e7d3-e97d-4d37-a9ab-ba3722dc6faa

UltiTools 6UltiTools' Reborn

https://img.shields.io/github/license/ultikits/ultitools-reborn?style=flat-square https://img.shields.io/github/v/release/UltiKits/UltiTools-Reborn?style=flat-square https://img.shields.io/github/stars/wisdommen/UltiTools?style=flat-square https://img.shields.io/badge/Minecraft-1.8--1.20-blue?style=flat-square https://img.shields.io/spiget/rating/85214?label=SpigotMC&style=flat-square https://img.shields.io/bstats/players/8652?style=flat-square https://img.shields.io/bstats/servers/8652?style=flat-square https://wakatime.com/badge/user/d4b748db-828d-4641-b87e-85def2b4fc94/project/2ed8f867-16e0-4fd6-a5af-b18d50e59469.svg?style=flat-square https://img.shields.io/maven-central/v/com.ultikits/UltiTools-API?style=flat-square https://img.shields.io/github/issues/wisdommen/UltiTools?style=flat-square

---
| [!(https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/6TVRRF47) | 👈 点击左侧按钮加入官方 Discord 服务器！ | 点击右侧按钮加入官方 QQ 群！ 👉 | [!(https://img.shields.io/badge/Tencent_QQ-EB1923?style=for-the-badge&logo=TencentQQ&logoColor=white)](https://qm.qq.com/q/i5GeDH6a7C) |
|-----------------------------------------------------------------------------------------------------------------------------------------|----------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

## 服主使用方法

[插件下载地址](https://repo1.maven.org/maven2/com/ultikits/UltiTools-API/6.1.1/UltiTools-API-6.1.1.jar) <--- 下载请点它

下载后，关闭服务器，将文件放入```服务器目录/plugins``` 文件夹下，启动服务器。

**请将PAPI和Vault也放入插件文件夹。**

**第一次启动会下载插件所需依赖（仅需下载一次），下载完成之后需要再重启一次，即可启用插件。**

**本插件是一个前置插件，不包含任何实质功能，需下载模块或其他插件拓展功能。**

## UltiTools-API 简介

希望我的插件能够帮到你的插件开发！

[详细开发文档](https://dev.ultikits.com/zh/)

**下面的内容可能更新不够及时，请以上面的详细开发文档为准！**

### 注解驱动的

UltiTools-API改变了插件开发的方式，通过引入注解等高级语法，让你的插件开发更加高效。

通过使用UltiTools-API，你再也无需手动注册指令和监听器，只需要在你的指令类和监听器类上添加注解，UltiTools-API会自动帮你注册。

你可以像写一个控制器一样，再也不需要为一个命令做繁琐的判断，只需要在你的指令方法上添加注解，UltiTools-API会自动帮你将指令匹配到对应的方法上。还可以实现[限定指令的权限](https://dev.ultikits.com/zh/guide/essentials/cmd-executor.html#%E6%9D%83%E9%99%90)，[执行锁](https://dev.ultikits.com/zh/guide/essentials/cmd-executor.html#%E6%89%A7%E8%A1%8C%E9%94%81)，[命令冷却时间](https://dev.ultikits.com/zh/guide/essentials/cmd-executor.html#%E5%91%BD%E4%BB%A4%E5%86%B7%E5%8D%B4)，[命令Tab补全的自动生成](https://dev.ultikits.com/zh/guide/essentials/cmd-executor.html#%E5%8F%82%E6%95%B0tab%E6%8F%90%E7%A4%BA%E8%A1%A5%E5%85%A8)等等。

```java
@CmdTarget(CmdTarget.CmdTargetType.PLAYER)
@CmdExecutor(alias = {"lore"}, manualRegister = true, permission = "ultikits.tools.command.lore", description = "物品Lore编辑功能")
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(value="position", suggest="[位置]") int position, @CmdParam("lore...") String[] lore) {
   ...
}
}
```

数据存储方面，UltiTools提供了Mysql、SQLite和Json的封装API，由服主决定存储方式，而你只需一套代码即可搞定所有三种存储方式。

例如
```java
@Data
@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;
}
```

```java
//检查玩家账户是否存在
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()
   );
}
```

配置文件方面，UltiTools让你可以像操作对象一样读取配置文件。

例如
```java
@Getter
@Setter
@ConfigEntity(path = "config/config.yml")
public class EcoConfig extends AbstractConfigEntity {

@ConfigEntry(path = "interestRate", comment = "利率，利息 = 利率 × 本金")
private doubleinterestRate = 0.0003;

public EcoConfig(String configFilePath) {
   super(configFilePath);
}
}
```
```java
// 获取经济插件的配置文件，并且读取利息率
EcoConfig config = UltiEconomy.getInstance().getConfig(EcoConfig.class);
double intrestRate = config.getInterestRate();
```

### IOC容器管理

UltiTools-API提供了一个Spring IOC容器，它可以帮你管理你的插件中的所有Bean，并且自动注入依赖。

```java
// @Service将类型标记为一个Bean，UltiTools-API会自动扫描并注册
@Service
public class BanPlayerService {

...

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

```java
@CmdTarget(CmdTarget.CmdTargetType.BOTH)
@CmdExecutor(permission = "ultikits.ban.command.all", description = "封禁功能", alias = {"uban"}, manualRegister = true)
public class BanCommands extends AbstractCommendExecutor {

// 使用@Autowired注解，UltiTools-API会自动注入依赖
@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("§a解封成功"));
}

...
}
```

如果你不喜欢自动注入，或者无法使用自动注入，你也可以手动获取Bean。

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

### 提供超多的现代化依赖库

UltiTools-API提供了Hutool的部分功能，包括了大量的工具类。

(https://hutool.cn/docs/#/)

GUI界面方面，UltiTools提供了obliviate-invs的API，方便你快速的开发GUI界面。

(https://www.spigotmc.org/resources/obliviateinvs-%E2%80%94-highly-efficient-modular-gui-library.103572/)

UltiTools也提供了Adventure的API。

(https://docs.adventure.kyori.net/)

## 快速开始

更多详细文档请查看 (https://dev.ultikits.com/zh/)

以下是简单的快速开始

### 安装依赖

首先将UltiTools-API依赖加入到你的项目

使用Maven

```xml
<dependency>
<groupId>com.ultikits</groupId>
<artifactId>UltiTools-API</artifactId>
<version>6.1.1</version>
</dependency>
```

使用Gradle

```groovy
implementation 'com.ultikits:UltiTools-API:6.1.1'
```

开始之前请在resources文件夹下新建一个plugin.yml文件，内容如下

```yaml
# 插件名称
name: TestPlugin
# 插件版本
version: '${project.version}'
# 插件主类
main: com.test.plugin.MyPlugin
# 插件用到的UltiTools-API版本，例如6.0.0就是600
api-version: 600
# 插件作者
authors: [ wisdomme ]
```
新建一个config文件夹，里面可以按照你的需求放入你的插件配置文件。这些配置文件会被原封不动的放入UltiTools插件的集体配置文件夹中展示给用户。

### 简单开发

新建一个主类继承UltiToolsPlugin，类似传统的Spigot插件，UltiTools插件也需要重写启动和关闭方法。
但是UltiToolsPlugin增加了一个可选的```UltiToolsPlugin#reloadSelf()```方法，用于插件重载时执行。
给主类加上```UltiToolsModule```注解，即可开启监听器、命令和依赖的自动扫描注册。

```java
@UltiToolsModule
public class MyPlugin extends UltiToolsPlugin {
@Override
public boolean registerSelf() {
   // 插件启动时执行
   return true;
}

@Override
public void unregisterSelf() {
   // 插件关闭时执行
}

@Override
public void reloadSelf() {
   // 插件重载时执行
}
}
```
这样就已经完成了一个什么功能都没有的UltiTools插件。然后你就可以直接开始写命令执行器或者监听器啦！

#### 事件监听器
只要在类上加上 @EventListener 注解并实现 Listener 类即可被UltiTools自动发现并且注册为事件监听器，无需手动注册！

```java
@EventListener
public class JoinListener implements Listener {

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
   // 干一些好玩的事情
}
}
```

#### 命令执行器

在类上加上 @CmdExecutor 和 @CmdTarget 注解并继承 AbstractCommendExecutor 类即可被UltiTools自动发现并且注册为命令，也是无需手动注册！

```java
@CmdExecutor(description = "Bank", alias = {"bank"})
@CmdTarget(CmdTarget.CmdTargetType.PLAYER)
public class BankCommand extends AbstractCommendExecutor {

   @CmdMapping(format = "list")
   public void listAccounts(@CmdSender Player player) {
         List<AccountEntity> banks = bank.getOwnedAccounts(player.getUniqueId());
         if (banks.isEmpty()) {
            player.sendMessage(UltiEconomy.getInstance().i18n("你没有任何银行账户"));
         }
         player.sendMessage(UltiEconomy.getInstance().i18n("你的银行账户列表:"));
         for (AccountEntity bankName : banks) {
            player.sendMessage(" - " + bankName + " : " + bank.checkAccountBalance(player.getUniqueId(), bankName.getName()));
         }
   }
}
```

### 模块安装

写完以上代码之后，使用mvn package命令打包，生成的jar文件放入 ```服务器根目录/plugins/UltiTools/plugins``` 文件夹中，重启服务器模块即可生效！

使用命令 ul list 查看是否成功加载。

```text
> ul list
: BasicFunctions 1.0.0
: UltiTools-Login 1.0.0
: UltiTools-MysqlConnector 1.0.0
: UltiTools-SidebarPlugin 1.0.0
: Example 1.0.0       <--- 这是我们的示例插件
```

## 主要贡献者
| 贡献者                                           | 描述                                  |
|--------------------------------------------------|-----------------------------------------|
| [@wisdommen](https://github.com/wisdommen)    | 创始人，UltiKits套件作者                      |
| [@qianmo2233](https://github.com/qianmo2233) | UltiTools&UltiCore开发者，UltiKits开发文档主要维护者 |
| [@Shpries](https://github.com/Shpries)       | UltiTools开发者，UltiTools使用文档主要维护者       |
| [@DevilJueChen](https://github.com/DevilJueChen) | UltiKits问题&漏洞&建议反馈                   |
| 拾柒                                           | 美工                                  |

## 发现问题？想提建议？
[点击这里提交开启一个Issue！](https://github.com/UltiKits/UltiTools-Reborn/issues/new/choose)

## 鸣谢

|                                                                                                                         |                      |
|---------------------------------------------------------------------------------------------------------------------------|------------------------|
| !(https://img.shields.io/badge/WakaTime-000000?style=for-the-badge&logo=WakaTime&logoColor=white)    | 记录了我们开发途中的每一刻       |
| !(https://img.shields.io/badge/IntelliJ_IDEA-000000.svg?style=for-the-badge&logo=intellij-idea&logoColor=white) | 地表最强 Java IDE 助力愉悦开发体验 |
| !(https://img.shields.io/badge/ChatGPT-74aa9c?style=for-the-badge&logo=openai&logoColor=white)                | 帮助解决了许多重复且枯燥的工作    |
| !(https://img.shields.io/badge/Spring-6DB33F?style=for-the-badge&logo=spring&logoColor=white)                | 为插件带来了许多黑科技          |
| !(https://img.shields.io/badge/apache_maven-C71A36?style=for-the-badge&logo=apachemaven&logoColor=white)    | 官方构建工具             |

wisdomme 发表于 2024-7-2 15:30:27

擀，保存草稿点成发布了
{:tsj52:}

看海发表于 2024-7-26 10:55:01

1.点击交流群链接显示加群校验失败
2.快速开始更多详细文档请查看 UltiTools API 文档这个位置的文档链接掉了https://dev.ultikits.com/ -> https://dev.ultikits.com/zh/

wisdomme 发表于 2024-7-26 12:01:21

看海发表于 2024-7-26 10:55
1.点击交流群链接显示加群校验失败
2.快速开始更多详细文档请查看 UltiTools API 文档这个位置的文档链接 ...

感谢提醒{:kira:}

页: [1]

MCBBS纪念版's Archiver

[插件开发][1.8.8-1.20.6] UltiTools-API 简单|高效|注解驱动的插件开发体验