Command Framework

插件

· 作者 CroaBeast

适用于 Bukkit、Spigot 和 Paper 插件的动态命令框架。

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

最新 1.1 · 1.21.10 · Bukkit / Folia

一键开服(送7天)

Command Framework

Command Framework 是一个灵活且可扩展的命令框架,专为 Bukkit/Spigot 以及特别是 Paper 分支设计。它简化了在运行时动态创建、注册和管理命令的过程——由于 Bukkit/Spigot 与 Paper 之间固有的差异和限制,这项任务通常颇具挑战性。


概述

me.croabeast.command 包提供了一个模块化的命令系统,具备以下功能:

  • 健壮的注册/注销机制:
    即使在 Paper 服务器上也能无缝地于运行时注册和注销命令,而许多传统的 Bukkit/Spigot 实现在此场景下可能会失效。Command Framework 解决了 Paper 带来的运行时注册挑战。

  • 子命令支持:
    轻松实现带有子命令的命令层级结构。每个子命令会自动从其父命令派生权限节点,并可以配置别名。

  • 动态 Tab 补全:
    使用内置的 TabBuilder 类构建上下文敏感的 Tab 补全建议。你可以定义静态和动态的建议,甚至可以使用谓词(predicates)和函数,根据命令发送者或输入内容定制补全结果。

  • 权限处理:
    利用 Permissible 和 DefaultPermissible 接口进行健壮的权限检查。该框架支持通配符权限,并能与 Bukkit 权限系统完美集成。

  • 流畅的命令创建体验:
    使用 CommandBuilder 类提供的流畅 API 快速创建和配置命令,设置诸如覆盖行为、错误处理和自定义 Tab 补全策略等属性。

  • 与 Bukkit/Spigot/Paper 的集成:
    建立在 Bukkit 命令系统之上,Command Framework 能够无缝集成到服务器的命令映射表和权限系统中。它特别针对 Paper 服务器进行了优化,因为在该平台上管理运行时命令 notoriously 具有挑战性。


关键组件

Permissible & DefaultPermissible

  • 用途: 定义命令的基本权限要求。
  • 用法: 实现这些接口以确保只有授权用户才能执行命令。

Executable

  • 用途: 表示要执行的命令动作。
  • 用法: 返回一个 {@code State} 枚举结果,以指示成功或失败。

BaseCommand

  • 用途: 建立命令的核心结构,包括其名称、别名和执行动作。
  • 用法: 将这些接口作为构建更复杂命令(包含子命令和权限)的基础。

Command

  • 用途: 扩展 BaseCommand 和 Completable,提供带有 Tab 补全支持的完整命令接口。
  • 用法: 自动管理子命令和通配符权限。

SubCommand

  • 用途: 创建自动链接到父命令的子命令。
  • 用法: 轻松扩展命令以增加额外功能(例如“reload”子命令),同时继承权限设置。

TabBuilder

  • 用途: 构建和管理 Tab 补全建议。
  • 用法: 为特定的命令参数配置建议,支持灵活的过滤和基于谓词的选择。

BukkitCommand

  • 用途: 一个与 Bukkit 命令系统集成的抽象基类。
  • 用法: 扩展此类以完全控制命令执行,包括运行时注册/注销——这在 Paper 服务器上是一个常见难题。

CommandBuilder

  • 用途: 提供用于构建命令的流畅 API。
  • 用法: 使用 CommandBuilder 快速创建带有 Tab 补全和错误处理的命令,非常适合需要动态运行时命令管理的 Paper 分支。

为什么 Command Framework 能在 Paper 分支上运行

Bukkit/Spigot 的 Paper 分支通常会破坏传统的命令注册方法,尤其是在尝试于运行时进行动态注册和注销时。Command Framework 就是为了解决这些挑战而设计的。它能够:

  • 支持运行时更改:
    使命令能够在 Paper 服务器上无问题地进行运行时注册和注销。

  • 处理兼容性问题:
    包含变通方案和专门实现(例如在 BukkitCommand 和 CommandBuilder 中),以应对 Paper 对命令系统的修改。

  • 确保稳定性:
    即使在 Bukkit/Spigot 与 Paper 之间的底层 API 发生变化时,也能提供健壮的错误处理和权限管理。


用法示例

示例 1:通过扩展 BukkitCommand 创建自定义命令

通过扩展 BukkitCommand 来创建自定义命令:

package com.example.myplugin.command;

import me.croabeast.command.BukkitCommand;
import me.croabeast.command.BaseCommand;
import me.croabeast.command.Executable;
import me.croabeast.command.SubCommand;
import me.croabeast.command.TabBuilder;
import me.croabeast.command.DefaultPermissible;
import org.bukkit.command.CommandSender;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.NotNull;

import java.util.Arrays;

public class GreetCommand extends BukkitCommand implements DefaultPermissible {

    /**
     * 构造带有拥有插件引用的 GreetCommand。
     *
     * @param plugin 插件实例。
     */
    public GreetCommand(Plugin plugin) {
        super(plugin, "greet");
        
        // 设置主命令的可执行动作
        setExecutable((CommandSender sender, String[] args) -> {
            sender.sendMessage("Hello, " + sender.getName() + "!");
            return Executable.State.TRUE;
        });

// 注册一个名为 "reload" 的子命令,别名为 "r"
        SubCommand reloadSub = new SubCommand(this, "reload;r");
        reloadSub.setExecutable((sender, args) -> {
            // 重载逻辑在此处
            sender.sendMessage("GreetCommand configuration reloaded.");
            return Executable.State.TRUE;
        });
        registerSubCommand(reloadSub);
    }

    /**
     * 为命令提供自定义的 Tab 补全功能。
     *
     * @param sender 命令发送者。
     * @param alias  使用的命令别名。
     * @param args   传递给命令的参数。
     * @return 建议列表。
     */
    @NotNull
    @Override
    public java.util.List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, String[] args) {
        // 创建一个简单的 TabBuilder 用于生成建议
        TabBuilder builder = new TabBuilder();
        if (args.length == 1) {
            // 当未指定子命令时,建议 "hello" 和 "hi"
            builder.addArgument(1, "hello");
            builder.addArgument(1, "hi");
        } else if (args.length > 1) {
            // 可选地,为后续参数提供额外的建议
            builder.addArgument(args.length, "option1");
            builder.addArgument(args.length, "option2");
        }
        return builder.build(sender, args);
    }
}

注册命令

在你的插件主类(继承自 JavaPlugin)中,注册该命令:

package com.example.myplugin;

import com.example.myplugin.command.GreetCommand;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // 创建 GreetCommand 实例并注册它
        GreetCommand greetCommand = new GreetCommand(this);
        greetCommand.register();
        
        // 若需稍后注销该命令,请调用:
        // greetCommand.unregister();
    }
}

示例 2:使用 CommandBuilder 创建命令

或者,使用 CommandBuilder 提供的流式 API:

package com.example.myplugin;

import com.example.myplugin.command.CommandBuilder;
import com.example.myplugin.command.Executable;
import com.example.myplugin.command.TabBuilder;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.Arrays;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // 使用 CommandBuilder 创建命令 "example"
        CommandBuilder builder = CommandBuilder.from(this, "example")
            .setOverriding(true)
            .setCompletions((sender, args) -> Arrays.asList("optionA", "optionB", "optionC"))
            .setCompletionBuilder(new TabBuilder().addArgument(1, "optionA"))
            .apply(cmd -> cmd.setExecutable((sender, args) -> {
                sender.sendMessage("Example command executed with arguments: " + String.join(" ", args));
                return Executable.State.TRUE;
            }));

        // 在运行时注册命令(与 Paper 无缝兼容)
        builder.register();

        // 若需稍后注销:
        // builder.unregister();
    }
}

Maven / Gradle 安装

要将 Command Framework 包含到项目中,请在你的构建配置中添加以下仓库和依赖项。将 ${version} 替换为所需的版本标签。

Maven

将仓库和依赖项添加到你的 pom.xml 中:

<repositories>
    <repository>
        <id>croabeast-repo</id>
        <url>https://croabeast.github.io/repo/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>me.croabeast</groupId>
        <artifactId>CommandFramework</artifactId>
        <version>${version}</version>
        <scope>compile</scope>
    </dependency>
</dependencies>

Gradle

将仓库和依赖项添加到你的 build.gradle 中:

repositories {
    maven {
        url "https://croabeast.github.io/repo/"
    }
}

dependencies {
    implementation "me.croabeast:CommandFramework:${version}"
}

将 ${version} 替换为相应的模块版本。


结语

Command Framework(me.croabeast.command 包中的类集合)旨在简化 Minecraft 插件的命令开发,特别是在 Paper 分支上运行时注册可能具有挑战性的情况下。其模块化设计、对子命令的支持、动态 Tab 补全以及强大的权限检查功能,使其成为现代插件开发的理想选择。

借助 Command Framework,你可以构建复杂的命令层级结构,提供上下文敏感的 Tab 补全,并在运行时管理命令的注册与注销——确保即使在最新的 Paper 服务器上也具备兼容性和稳定性。

祝你编码愉快,享受使用 Command Framework 构建强大命令的乐趣!
— CroaBeast

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源