AnnotatedCommandAPI

插件

· 作者 ItsVaidas

旨在帮助你使用 Paper 命令 API 快速创建命令的 API

0 本站下载 0 关注 更新于 1 年前

最新 1.2 · 1.21.7 · Paper

一键开服(送7天)

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)的实例,并通过命令注册器进行注册。
  • 此过程会自动扫描注解并将命令挂钩到服务器中。

工作原理

  1. 命令注册: AnnotatedCommandAPI 会在一类中注册所有的命令和子命令。
  2. 参数映射: 方法参数会根据其顺序和类型匹配命令参数。
  3. 权限检查: 在命令执行前,会自动验证所需的权限。
  4. Tab 补全: 基于参数类型和自定义提供程序,用户可获得动态的 Tab 补全功能。
  5. 执行上下文: 方法接收执行者(Player 或 CommandSender)以及解析后的参数,从而允许对命令逻辑进行完全控制。

为什么选择 AnnotatedCommandAPI?

  • 降低复杂度 — 不再需要手动管理 Brigadier 树。
  • 加速开发 — 只需注解方法并使用简单的 Java 代码即可处理命令。
  • 提高可读性 — 命令逻辑在类和方法中得到清晰组织。
  • 提升用户体验 — 内置 Tab 补全和权限处理功能。
  • 可扩展性 — 轻松添加适合你需求的新参数类型和提供程序。

总结

AnnotatedCommandAPI 是 Minecraft 插件开发者的优雅解决方案,旨在无需面对 Brigadier 复杂命令树的麻烦即可创建复杂的命令。它利用 Java 注解直观地定义命令、参数和权限,支持丰富的参数类型、自定义提供程序,并赋予开发者对命令执行者和执行方式的完全灵活性。

立即开始使用 AnnotatedCommandAPI,更快、更简洁、更智能地构建命令!


如果你需要示例、详细指南或帮助将其集成到你的插件中,欢迎随时提问!

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源