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
Command Framework
Command Framework is a flexible and extensible command framework designed for Bukkit/Spigot and especially Paper forks. It simplifies the process of creating, registering, and managing commands dynamically at runtime—a task that can be challenging due to inherent differences and limitations between Bukkit/Spigot and Paper.
Overview
The me.croabeast.command package offers a modular command system that provides:
-
Robust Registration/Unregistration:
Seamlessly register and unregister commands at runtime even on Paper servers, where many traditional Bukkit/Spigot implementations can break. Command Framework addresses the runtime registration challenges posed by Paper.
-
Sub-Commands Support:
Easily implement command hierarchies with sub-commands. Each sub-command automatically derives its permission node from its parent and can be configured with aliases.
-
Dynamic Tab Completion:
Build context-sensitive tab completions with the included TabBuilder class. You can define both static and dynamic suggestions, and even use predicates and functions to tailor completions based on the command sender or input.
-
Permission Handling:
Leverage the Permissible and DefaultPermissible interfaces for robust permission checking. The framework supports wildcard permissions and integrates neatly with the Bukkit permission system.
-
Fluent Command Creation:
Use the CommandBuilder class for a fluent API to quickly create and configure commands, setting properties like overriding behavior, error handling, and custom tab completion strategies.
-
Integration with Bukkit/Spigot/Paper:
Built on top of Bukkit’s command system, Command Framework seamlessly integrates with the server’s command map and permission system. It is particularly tuned for Paper servers where runtime command management is notoriously challenging.
Key Components
Permissible & DefaultPermissible
- Purpose: Define basic permission requirements for commands.
- Usage: Implement these interfaces to ensure that only authorized users execute commands.
Executable
- Purpose: Represent the command action that is executed.
- Usage: Return a result using a {@code State} enum to indicate success or failure.
BaseCommand
- Purpose: Establish the core structure of commands, including their names, aliases, and executable actions.
- Usage: Use these interfaces as the foundation for building more complex commands with sub-commands and permissions.
Command
- Purpose: Extend BaseCommand and Completable to provide a complete command interface with tab completion support.
- Usage: Manage sub-commands and wildcard permissions automatically.
SubCommand
- Purpose: Create sub-commands that are automatically linked to a parent command.
- Usage: Easily extend commands with additional functionalities (e.g., a "reload" sub-command) while inheriting permission settings.
TabBuilder
- Purpose: Build and manage tab-completion suggestions.
- Usage: Configure suggestions for specific command arguments with flexible filtering and predicate-based selection.
BukkitCommand
- Purpose: An abstract base class that integrates with Bukkit’s command system.
- Usage: Extend this class for full control over command execution, including runtime registration/unregistration—a common challenge on Paper servers.
CommandBuilder
- Purpose: Provide a fluent API for constructing commands.
- Usage: Use CommandBuilder to quickly create commands with tab completions and error handling, perfect for Paper forks with dynamic runtime command management.
Why Command Framework Works on Paper Forks
Paper forks of Bukkit/Spigot often break traditional command registration methods, especially when attempting dynamic registration and unregistration at runtime. Command Framework was built with these challenges in mind. It:
-
Supports Runtime Changes:
Enables commands to be registered and unregistered at runtime without issues on Paper.
-
Handles Compatibility Issues:
Includes workarounds and specialized implementations (e.g., in BukkitCommand and CommandBuilder) that account for Paper’s modifications to the command system.
-
Ensures Stability:
Provides robust error handling and permission management even when underlying APIs change between Bukkit/Spigot and Paper.
Usage Examples
Example 1: Custom Command by Extending BukkitCommand
Create a custom command by extending 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 {
/**
* Constructs the GreetCommand with a reference to the owning plugin.
*
* @param plugin the plugin instance.
*/
public GreetCommand(Plugin plugin) {
super(plugin, "greet");
// Set up the main command executable
setExecutable((CommandSender sender, String[] args) -> {
sender.sendMessage("Hello, " + sender.getName() + "!");
return Executable.State.TRUE;
});
// Register a sub-command "reload" with an alias "r"
SubCommand reloadSub = new SubCommand(this, "reload;r");
reloadSub.setExecutable((sender, args) -> {
// Reload logic here
sender.sendMessage("GreetCommand configuration reloaded.");
return Executable.State.TRUE;
});
registerSubCommand(reloadSub);
}
/**
* Provides custom tab completion for the command.
*
* @param sender the command sender.
* @param alias the command alias used.
* @param args the arguments passed to the command.
* @return a list of suggestions.
*/
@NotNull
@Override
public java.util.List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, String[] args) {
// Create a simple TabBuilder for suggestions
TabBuilder builder = new TabBuilder();
if (args.length == 1) {
// Suggest "hello" and "hi" when no sub-command is specified
builder.addArgument(1, "hello");
builder.addArgument(1, "hi");
} else if (args.length > 1) {
// Optionally, provide additional suggestions for further arguments
builder.addArgument(args.length, "option1");
builder.addArgument(args.length, "option2");
}
return builder.build(sender, args);
}
}
Registering the Command
In your plugin’s main class (extending JavaPlugin), register the command:
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() {
// Create an instance of GreetCommand and register it
GreetCommand greetCommand = new GreetCommand(this);
greetCommand.register();
// To unregister the command later, call:
// greetCommand.unregister();
}
}
Example 2: Creating a Command with CommandBuilder
Alternatively, use the fluent API provided by CommandBuilder:
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() {
// Create a command "example" using CommandBuilder
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;
}));
// Register the command at runtime (works seamlessly on Paper)
builder.register();
// To unregister later:
// builder.unregister();
}
}
Maven / Gradle Installation
To include Command Framework to the project, add the following repository and dependency to your build configuration. Replace ${version} with the desired version tag.
Maven
Add the repository and dependency to your 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
Add the repository and dependency to your build.gradle:
repositories {
maven {
url "https://croabeast.github.io/repo/"
}
}
dependencies {
implementation "me.croabeast:CommandFramework:${version}"
}
Replace ${version} with the appropriate module version.
Conclusion
Command Framework (the collection of classes in the me.croabeast.command package) is designed to streamline command development for Minecraft plugins, particularly on Paper forks where runtime registration can be challenging. Its modular design, support for sub-commands, dynamic tab completion, and robust permission checks make it an ideal choice for modern plugin development.
With Command Framework, you can build sophisticated command hierarchies, provide context-sensitive tab completions, and manage command registration and unregistration at runtime—ensuring compatibility and stability even on the latest Paper servers.
Happy coding and enjoy building powerful commands with Command Framework!
— CroaBeast
评论 0
登录后参与评分
还没有评论,来抢沙发吧