# AnnotatedCommandAPI
AnnotatedCommandAPI 是一个强大且易于使用的命令框架，旨在通过消除 Brigadier 命令树结构的复杂性来简化 Minecraft 插件命令开发。它提供了一种直观的基于注解的系统，允许开发者在纯 Java 类和方法中干净、高效地定义命令、子命令、权限和参数解析。
---
## 关键特性
- **注解驱动的命令**: 使用直接的注解（如 `@Command` 和 `@Path`）来定义命令和子命令，从而消除了冗长且容易出错的样板代码。
- **灵活的参数解析**: 支持基本类型 (`String`, `int`, `double` 等) 和高级类型 (`World`, `Player`，自定义对象)，并具有自动的标签完成功能。
- **自定义参数提供者**: 轻松创建自定义参数提供者，以提供动态的命令参数建议。
- **权限集成**: 通过注解在命令和子命令级别附加权限，以无缝控制访问。
- **清晰的分离**: 通过类组织命令，并将子命令分组为注释方法，从而使您的代码库清晰且易于维护。
- **玩家与控制台执行**: 明确指定命令是否可以由玩家、控制台或两者运行，通过方法参数 (`Player` 或 `CommandSender`) 指定。
---
## 快速开始
### 将其集成到您的插件中
要在您的 Minecraft 插件中使用 AnnotatedCommandAPI，请将以下依赖项添加到您的 `build.gradle` 文件中：
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.ItsVaidas:AnnotatedCommandAPI:TAG'
}
```
将 `TAG` 替换为来自 [AnnotatedCommandAPI 仓库](https://github.com/ItsVaidas/AnnotatedCommandAPI) 的最新版本标签
### 基本命令示例
定义一个将消息广播给所有玩家的简单命令：
```java
@Path(
name = "",
description = "将消息发送到整个服务器"
)
public void command(CommandSender sender, Sentence message) {
Bukkit.getOnlinePlayers().forEach(p -> p.sendMessage(message.toString()));
}
```
- `@Path` 注解声明了一个带有参数的命令路径。
- `Sentence` 是一个特殊的参数类型，旨在捕获包括空格在内的长字符串。
- 对于单个单词的参数，使用 `String`。
---
### 带有子命令的完整命令类
一个复杂的传送命令，演示了多个子命令和权限：
```java
@Command(
name = "tpw",
description = "世界传送命令",
permission = "zccommands.command.teleport"
)
public class TpwCommand {
@Path(
name = "load ",
description = "加载一个世界",
permission = "zccommands.command.teleport.load"
)
public void load(CommandSender sender, String world) {
WorldCreator newWorld = new WorldCreator(world);
newWorld.generator(new VoidChunkGenerator());
newWorld.createWorld();
}
@Path(
name = "unload ",
description = "卸载一个世界",
permission = "zccommands.command.teleport.unload"
)
public void unload(CommandSender sender, String world) {
Bukkit.unloadWorld(world, true);
}
@Path(
name = "",
description = "传送到一个世界",
permission = "zccommands.command.teleport.world"
)
public void teleportToWorld(Player sender, World world) {
sender.teleportAsync(world.getSpawnLocation());
}
@Path(
name = " ",
description = "根据坐标传送到一个世界",
permission = "zccommands.command.teleport.world"
)
public void teleportToWorldByCoordinates(Player sender, World world, double x, double y, double z) {
sender.teleportAsync(new Location(world, x, y, z));
}
}
```
### 说明：
- `@Command` 注解将类标记为命令根，设置其基本名称、描述和权限。
- 每个使用 `@Path` 注解的方法表示主命令的一个子命令或变体。
- `@Path` 的 `name` 属性定义了命令语法，包括所需参数（例如 ` `）。
- 方法参数对应于这些命令参数，它们的类型可以是本机 Java 类型或系统识别的自定义对象。
- 权限可以针对每个子命令进行设置，以微调访问控制。
- 每种方法的第一個参数是 `Player` 或 `CommandSender`，取决于谁可以执行该命令。
---
## 参数类型和自定义提供者
AnnotatedCommandAPI 支持：
- **基本类型**: `String`, `int`, `double`, `boolean` 等。
- **复杂类型**: `Player`, `World`, `Location` 等，带有自动的标签完成功能。
- **Sentence**: 一个特殊的参数类型，捕获包含空格的整个句子或多个单词。
- **自定义参数提供者**: 用于支持动态或插件特定的参数建议。
---
### 创建自定义参数提供者
示例：为命令参数提供动态竞技场名称。
```java
@Path(
name = "start ",
description = "开始一个事件"
)
public void onStart(CommandSender sender, @Argument(provider = ArenaNameProvider.class) String name) {
// 实现代码在此处
}
public class ArenaNameProvider extends ArgumentProvider {
public ArenaNameProvider() {} // 需要的无参构造函数
@Override
public Stream provide(CommandSourceStack source) {
return Data.getArenas().stream()
.map(ArenaDTO::getName);
}
}
```
- 实现 `ArgumentProvider` 并覆盖 `provide` 以返回有效的参数字符串流。
- 使用 `@Argument(provider = YourProvider.class)` 将提供者附加到命令参数。
- 这能够根据插件数据或运行时状态动态启用标签完成和验证。
---
## 命令注册
要激活插件中的命令，您需要使用 `CommandRegister` 类将其注册。以下是如何在插件的主类中完成此操作（通常在 `onEnable` 中）：
```java
CommandRegister cr = new CommandRegister(this);
cr.register(new TpwCommand());
```
- `this` 指的是您的插件实例。
- 您创建一个命令类的实例（例如 `TpwCommand`）并使用命令注册器注册它。
- 此过程会自动扫描注解并将命令挂接到服务器。
---
## 工作原理
1. **命令注册**: AnnotatedCommandAPI 注册一个类中的所有命令和子命令。
2. **参数映射**: 方法参数与命令参数按顺序和类型进行匹配。
3. **权限检查**: 在执行命令之前，将自动验证所需的权限。
4. **标签完成**: 基于参数类型和自定义提供者，用户将获得动态的标签完成功能。
5. **执行上下文**: 方法接收执行发送者 (`Player` 或 `CommandSender`) 和解析的参数，从而可以完全控制命令逻辑。
---
## 为什么选择 AnnotatedCommandAPI？
- **减少复杂性** — 不再手动管理 Brigadier 树。
- **加快开发速度** — 使用简单的 Java 代码注释方法和处理命令。
- **提高可读性** — 命令逻辑清晰地组织在类和方法中。
- **增强用户体验** — 内置的标签完成和权限处理。
- **可扩展性** — 可以轻松添加新的参数类型和提供者，以满足您的需求。
---
## 总结
AnnotatedCommandAPI 是 Minecraft 插件开发者寻求创建复杂命令而无需 Brigadier 复杂命令树的优雅解决方案。它采用 Java 注解直观地定义命令、参数和权限，支持丰富的参数类型、自定义提供者，并对谁可以执行命令以及如何执行提供完全的灵活性。
立即开始使用 AnnotatedCommandAPI，更快、更干净、更智能地构建命令！
---
如果您想获取示例、详细指南或帮助集成到您的插件中，请随时提问！