AnnotatedCommandAPI
AnnotatedCommandAPI 是一个强大且易于使用的命令框架,旨在通过消除 Brigadier 命令树结构的复杂性来简化 Minecraft 插件的命令开发。它提供了一种基于注解的直观系统,允许开发者在普通的 Java 类和方法中清晰、高效地定义命令、子命令、权限和参数解析。
主要功能
- 基于注解的命令:使用
@Command 和 @Path 等简单直接的注解来定义命令和子命令,消除冗长且易出错的样板代码。
- 灵活的参数解析:支持基本类型(
String、int、double 等)和高级类型(World、Player、自定义对象),并具备自动标签补全功能。
- 自定义参数提供程序:轻松创建您自己的参数提供程序,以提供动态的命令参数建议。
- 权限集成:通过注解在命令和子命令级别附加权限,从而无缝控制访问权限。
- 清晰的分离:按类组织命令,并将子命令分组为带注解的方法,使代码库保持整洁且易于维护。
- 玩家与控制台执行:通过方法参数(
Player 或 CommandSender)明确指定命令是否可以由玩家、控制台或两者运行。
入门指南
集成到您的插件中
要在您的 Minecraft 插件中使用 AnnotatedCommandAPI,请将以下依赖项添加到您的 build.gradle 文件中:
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.ItsVaidas:AnnotatedCommandAPI:TAG'
}
将 TAG 替换为 AnnotatedCommandAPI 仓库 中的最新版本标签。
基本命令示例
定义一个简单的命令,向所有玩家广播消息:
@Path(
name = "<Message>",
description = "Send message to the whole server"
)
public void command(CommandSender sender, Sentence message) {
Bukkit.getOnlinePlayers().forEach(p -> p.sendMessage(message.toString()));
}
@Path 注解声明了一个带有参数的命令路径。
Sentence 是一种特殊的参数类型,旨在捕获包含空格的长字符串。
- 对于单个单词的参数,请使用
String。
包含子命令的完整命令类
一个展示多个子命令和权限的复杂传送命令:
@Command(
name = "tpw",
description = "World teleport command",
permission = "zccommands.command.teleport"
)
public class TpwCommand {
@Path(
name = "load <World>",
description = "Load a world",
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 <World>",
description = "Unload a world",
permission = "zccommands.command.teleport.unload"
)
public void unload(CommandSender sender, String world) {
Bukkit.unloadWorld(world, true);
}
@Path(
name = "<World>",
description = "Teleport to a world",
permission = "zccommands.command.teleport.world"
)
public void teleportToWorld(Player sender, World world) {
sender.teleportAsync(world.getSpawnLocation());
}
@Path(
name = "<World> <X> <Y> <Z>",
description = "Teleport to a world by coordinates",
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 属性定义了命令语法,包括必需的参数(例如 <World> <X> <Y> <Z>)。
- 方法参数对应于这些命令参数,它们的类型可以是原生 Java 类型或由系统识别的自定义对象。
- 可以为每个子命令设置权限,以微调访问控制。
- 方法的第一个参数是
Player 或 CommandSender,具体取决于谁可以执行该命令。
参数类型与自定义提供程序
AnnotatedCommandAPI 支持:
- 基本类型:
String、int、double、boolean 等。
- 复杂类型:
Player、World、Location 等,具备自动标签补全功能。
- Sentence:一种特殊的参数类型,用于捕获整个句子或多个带有空格的单词。
- 自定义参数提供程序:用于支持动态或特定于插件的参数建议。
创建自定义参数提供程序
示例:为命令参数提供动态竞技场名称。
@Path(
name = "start <Name>",
description = "Start an event"
)
public void onStart(CommandSender sender, @Argument(provider = ArenaNameProvider.class) String name) {
// Implementation here
}
public class ArenaNameProvider extends ArgumentProvider {
public ArenaNameProvider() {} // Required no-arg constructor
@Override
public Stream<String> provide(CommandSourceStack source) {
return Data.getArenas().stream()
.map(ArenaDTO::getName);
}
}
- 实现
ArgumentProvider 并重写 provide 以返回有效参数字符串的流。
- 使用
@Argument(provider = YourProvider.class) 将提供程序附加到命令参数。
- 这允许根据插件数据或运行时状态动态启用自定义标签补全和验证。
命令注册
要在你的插件中激活命令,你需要使用 CommandRegister 类来注册它们。以下是在插件主类(通常在 onEnable 方法中)进行注册的示例:
CommandRegister cr = new CommandRegister(this);
cr.register(new TpwCommand());
this 指的是你的插件实例。
- 你创建命令类(例如
TpwCommand)的实例,并通过命令注册器进行注册。
- 此过程会自动扫描注解并将命令挂钩到服务器中。
工作原理
- 命令注册: AnnotatedCommandAPI 会在一类中注册所有的命令和子命令。
- 参数映射: 方法参数会根据其顺序和类型匹配命令参数。
- 权限检查: 在命令执行前,会自动验证所需的权限。
- Tab 补全: 基于参数类型和自定义提供程序,用户可获得动态的 Tab 补全功能。
- 执行上下文: 方法接收执行者(
Player 或 CommandSender)以及解析后的参数,从而允许对命令逻辑进行完全控制。
为什么选择 AnnotatedCommandAPI?
- 降低复杂度 — 不再需要手动管理 Brigadier 树。
- 加速开发 — 只需注解方法并使用简单的 Java 代码即可处理命令。
- 提高可读性 — 命令逻辑在类和方法中得到清晰组织。
- 提升用户体验 — 内置 Tab 补全和权限处理功能。
- 可扩展性 — 轻松添加适合你需求的新参数类型和提供程序。
总结
AnnotatedCommandAPI 是 Minecraft 插件开发者的优雅解决方案,旨在无需面对 Brigadier 复杂命令树的麻烦即可创建复杂的命令。它利用 Java 注解直观地定义命令、参数和权限,支持丰富的参数类型、自定义提供程序,并赋予开发者对命令执行者和执行方式的完全灵活性。
立即开始使用 AnnotatedCommandAPI,更快、更简洁、更智能地构建命令!
如果你需要示例、详细指南或帮助将其集成到你的插件中,欢迎随时提问!
AnnotatedCommandAPI
AnnotatedCommandAPI is a powerful, easy-to-use command framework designed to simplify Minecraft plugin command development by removing the complexity of Brigadier's command tree structure. It provides an intuitive annotation-based system that allows developers to define commands, subcommands, permissions, and argument parsing cleanly and efficiently within plain Java classes and methods.
Key Features
- Annotation-Driven Commands: Define commands and subcommands using straightforward annotations like
@Command and @Path, eliminating verbose and error-prone boilerplate.
- Flexible Argument Parsing: Supports primitive types (
String, int, double, etc.) and advanced types (World, Player, custom objects) with automatic tab completion.
- Custom Argument Providers: Easily create your own argument providers to supply dynamic command argument suggestions.
- Permission Integration: Attach permissions at the command and subcommand level via annotations to control access seamlessly.
- Clear Separation: Organize commands by class and group subcommands as annotated methods, making your codebase clean and maintainable.
- Player vs Console Execution: Explicitly specify whether a command can be run by players, console, or both via method parameters (
Player or CommandSender).
Getting Started
Integrating into your Plugin
To use AnnotatedCommandAPI in your Minecraft plugin, add the following dependency to your build.gradle file:
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.ItsVaidas:AnnotatedCommandAPI:TAG'
}
Replace TAG with the latest version tag from the AnnotatedCommandAPI repository
Basic Command Example
Define a simple command that broadcasts a message to all players:
@Path(
name = "<Message>",
description = "Send message to the whole server"
)
public void command(CommandSender sender, Sentence message) {
Bukkit.getOnlinePlayers().forEach(p -> p.sendMessage(message.toString()));
}
- The
@Path annotation declares a command path with parameters.
Sentence is a special argument type designed to capture long strings including spaces.
- For a single word argument, use
String.
Full Command Class with Subcommands
A complex teleport command illustrating multiple subcommands and permissions:
@Command(
name = "tpw",
description = "World teleport command",
permission = "zccommands.command.teleport"
)
public class TpwCommand {
@Path(
name = "load <World>",
description = "Load a world",
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 <World>",
description = "Unload a world",
permission = "zccommands.command.teleport.unload"
)
public void unload(CommandSender sender, String world) {
Bukkit.unloadWorld(world, true);
}
@Path(
name = "<World>",
description = "Teleport to a world",
permission = "zccommands.command.teleport.world"
)
public void teleportToWorld(Player sender, World world) {
sender.teleportAsync(world.getSpawnLocation());
}
@Path(
name = "<World> <X> <Y> <Z>",
description = "Teleport to a world by coordinates",
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));
}
}
Explanation:
- The
@Command annotation marks the class as a command root, setting its base name, description, and permission.
- Each method annotated with
@Path represents a subcommand or variant of the main command.
- The
name property of @Path defines the command syntax, including required parameters (e.g., <World> <X> <Y> <Z>).
- Method parameters correspond to those command arguments, and their types can be native Java types or custom objects recognized by the system.
- Permissions can be set per subcommand to fine-tune access control.
- The first argument to every method is either a
Player or CommandSender, depending on who can execute the command.
Argument Types & Custom Providers
AnnotatedCommandAPI supports:
- Primitive types:
String, int, double, boolean, etc.
- Complex types:
Player, World, Location, etc., with automatic tab-completion.
- Sentence: A special argument type capturing entire sentences or multiple words with spaces.
- Custom argument providers: To support dynamic or plugin-specific argument suggestions.
Creating a Custom Argument Provider
Example: Providing dynamic arena names for command arguments.
@Path(
name = "start <Name>",
description = "Start an event"
)
public void onStart(CommandSender sender, @Argument(provider = ArenaNameProvider.class) String name) {
// Implementation here
}
public class ArenaNameProvider extends ArgumentProvider {
public ArenaNameProvider() {} // Required no-arg constructor
@Override
public Stream<String> provide(CommandSourceStack source) {
return Data.getArenas().stream()
.map(ArenaDTO::getName);
}
}
- Implement
ArgumentProvider and override provide to return a stream of valid argument strings.
- Attach the provider to the command argument with
@Argument(provider = YourProvider.class).
- This enables custom tab completions and validation dynamically based on plugin data or runtime state.
Command Registration
To activate your commands in your plugin, you need to register them with the CommandRegister class. Here's how you can do it in your plugin's main class (usually in onEnable):
CommandRegister cr = new CommandRegister(this);
cr.register(new TpwCommand());
this refers to your plugin instance.
- You create an instance of your command class (e.g.,
TpwCommand) and register it with the command register.
- This process automatically scans annotations and hooks commands into the server.
How It Works
- Command registration: AnnotatedCommandAPI registers all the commands and subcommands in one class.
- Argument mapping: Method parameters are matched to command arguments by their order and type.
- Permission checks: Before command execution, required permissions are verified automatically.
- Tab completion: Based on argument types and custom providers, users receive dynamic tab completions.
- Execution context: Methods receive the executing sender (
Player or CommandSender) and parsed arguments, allowing full control over command logic.
Why Choose AnnotatedCommandAPI?
- Reduces complexity — no more managing Brigadier trees manually.
- Speeds up development — annotate methods and handle commands with simple Java code.
- Improves readability — command logic is cleanly organized in classes and methods.
- Enhances user experience — built-in tab completion and permission handling.
- Extensible — easily add new argument types and providers tailored to your needs.
Summary
AnnotatedCommandAPI is an elegant solution for Minecraft plugin developers seeking to create complex commands without the hassle of Brigadier’s intricate command trees. It embraces Java annotations to define commands, arguments, and permissions intuitively, supports rich argument types, custom providers, and grants full flexibility over who can execute commands and how.
Start using AnnotatedCommandAPI today and build commands faster, cleaner, and smarter!
If you want examples, detailed guides, or help integrating with your plugin, feel free to ask!
评论 0
登录后参与评分
还没有评论,来抢沙发吧