Command（命令系統）

ll/api/command/ · 通用

概述

Command 模塊提供了在 Minecraft 基岩版中註冊自定義命令的高級 API。支持類型化參數、枚舉、軟枚舉（Soft Enum）、運行時枚舉、命令別名、權限等級和重載。

頭文件

頭文件	說明
`ll/api/command/CommandRegistrar.h`	命令註冊器單例
`ll/api/command/CommandHandle.h`	單個命令的句柄，用於添加重載和別名
`ll/api/command/Command.h`	命令基類模板
`ll/api/command/Overload.h`	流式重載構建器，包含參數鏈
`ll/api/command/OverloadData.h`	重載元數據存儲
`ll/api/command/RuntimeOverload.h`	動態運行時重載創建
`ll/api/command/ParamTraits.h`	參數類型信息和解析
`ll/api/command/EnumName.h`	命令參數的枚舉到名稱映射
`ll/api/command/SoftEnum.h`	軟枚舉包裝類型
`ll/api/command/Optional.h`	可選參數包裝器

核心類

CommandRegistrar

管理所有命令註冊的單例，通過 getInstance(bool isClientSide)（或簡寫 getServerInstance() / getClientInstance()）獲取。

C++

namespace ll::command {
class CommandRegistrar {
public:
    static CommandRegistrar& getInstance(bool isClientSide);

    CommandHandle& getOrCreateCommand(
        std::string const&      name,
        std::string const&      description = {},
        CommandPermissionLevel  requirement = CommandPermissionLevel::Any,
        CommandFlag             flag        = CommandFlagValue::NotCheat,
        std::weak_ptr<mod::Mod> mod         = mod::NativeMod::current()
    );

    bool hasEnum(std::string const& name);
    bool tryRegisterEnum(name, values, type, parser);
    bool addEnumValues(name, values, type);

    template <std::is_enum T> bool tryRegisterEnum();
    template <std::is_enum T> bool tryRegisterRuntimeEnum();

    bool hasSoftEnum(std::string const& name);
    bool tryRegisterSoftEnum(name, values);
    bool addSoftEnumValues(name, values);
    bool removeSoftEnumValues(name, values);
    bool setSoftEnumValues(name, values);

    template <Specializes<SoftEnum> T> bool tryRegisterSoftEnum();
};
}

CommandHandle

由 getOrCreateCommand() 返回。用於添加重載和別名。

C++

namespace ll::command {
class CommandHandle {
public:
    template <reflection::Reflectable Params = EmptyParam>
    Overload<Params> overload(std::weak_ptr<mod::Mod> mod = mod::NativeMod::current());

    RuntimeOverload runtimeOverload(std::weak_ptr<mod::Mod> mod = mod::NativeMod::current());

    std::vector<std::string> alias() const;
    CommandHandle& alias(std::string_view alias);
};
}

Overload<Params>

用於定義命令參數和執行處理器的流式構建器。

C++

namespace ll::command {
template <reflection::Reflectable Params>
class Overload {
public:
    Overload& optional(ParamName name);   // 标记参数为可选
    Overload& required(ParamName name);   // 标记参数为必需
    Overload& text(std::string_view text); // 添加文本字面量

    template <class Fn>
    void execute(Fn&& fn);               // 设置执行回调
};
}

執行回調 Fn 可以有以下簽名：

void(CommandOrigin const&, CommandOutput&, Params const&, ::Command const&) — 完整上下文
void(CommandOrigin const&, CommandOutput&, Params const&) — 帶參數
void(CommandOrigin const&, CommandOutput&) — 無參數
void() — 無參數

使用方法

基本命令註冊

C++

#include "ll/api/command/CommandRegistrar.h"
#include "ll/api/command/CommandHandle.h"

#include "mc/server/commands/CommandOrigin.h"
#include "mc/server/commands/CommandOutput.h"
#include "mc/server/commands/CommandPermissionLevel.h"

void registerMyCommand() {
    auto& cmd = ll::command::CommandRegistrar::getInstance(false)
        .getOrCreateCommand("hello", "打个招呼", CommandPermissionLevel::Any);

    cmd.overload().execute([](CommandOrigin const& origin, CommandOutput& output) {
        output.success("Hello, World!");
    });
}

帶參數的命令

定義一個結構體，其成員將成為命令參數：

C++

#include "ll/api/command/CommandRegistrar.h"
#include "ll/api/command/CommandHandle.h"
#include "ll/api/command/Optional.h"

#include "mc/server/commands/CommandOrigin.h"
#include "mc/server/commands/CommandOutput.h"

struct GreetParams {
    std::string name;
    ll::command::Optional<int> count;
};

void registerGreetCommand() {
    auto& cmd = ll::command::CommandRegistrar::getInstance(false)
        .getOrCreateCommand("greet", "问候某人");

    cmd.overload<GreetParams>()
        .required("name")
        .optional("count")
        .execute([](CommandOrigin const& origin, CommandOutput& output, GreetParams const& params) {
            int n = params.count.has_value() ? params.count.value() : 1;
            for (int i = 0; i < n; ++i) {
                output.success("Hello, {}!", params.name);
            }
        });
}

帶枚舉參數的命令

C++

#include "ll/api/command/CommandRegistrar.h"
#include "ll/api/command/CommandHandle.h"

enum class GameMode : int {
    Survival = 0,
    Creative = 1,
    Adventure = 2,
};

struct ModeParams {
    GameMode mode;
};

void registerModeCommand() {
    auto& registrar = ll::command::CommandRegistrar::getInstance(false);

    // 注册枚举
    registrar.tryRegisterEnum<GameMode>();

    auto& cmd = registrar.getOrCreateCommand("setmode", "设置游戏模式");

    cmd.overload<ModeParams>()
        .required("mode")
        .execute([](CommandOrigin const& origin, CommandOutput& output, ModeParams const& params) {
            output.success("模式已设置为 {}", (int)params.mode);
        });
}

軟枚舉

軟枚舉允許在運行時動態添加/刪除值：

C++

#include "ll/api/command/CommandRegistrar.h"
#include "ll/api/command/SoftEnum.h"

void registerDynamicEnum() {
    auto& registrar = ll::command::CommandRegistrar::getInstance(false);

    registrar.tryRegisterSoftEnum("warps", {"spawn", "home", "shop"});

    // 稍后，动态添加更多值
    registrar.addSoftEnumValues("warps", {"arena"});

    // 删除值
    registrar.removeSoftEnumValues("warps", {"shop"});
}

命令別名

C++

void registerWithAlias() {
    auto& cmd = ll::command::CommandRegistrar::getInstance(false)
        .getOrCreateCommand("teleport", "传送玩家");

    cmd.alias("tp");

    cmd.overload().execute([](CommandOrigin const& origin, CommandOutput& output) {
        output.success("正在传送...");
    });
}

多重載

C++

struct TeleportCoords {
    int x, y, z;
};

struct TeleportPlayer {
    std::string target;
};

void registerMultiOverload() {
    auto& cmd = ll::command::CommandRegistrar::getInstance(false)
        .getOrCreateCommand("warp", "传送命令");

    // 重载 1: /warp <x> <y> <z>
    cmd.overload<TeleportCoords>()
        .required("x").required("y").required("z")
        .execute([](CommandOrigin const&, CommandOutput& output, TeleportCoords const& p) {
            output.success("传送到 {}, {}, {}", p.x, p.y, p.z);
        });

    // 重载 2: /warp <target>
    cmd.overload<TeleportPlayer>()
        .required("target")
        .execute([](CommandOrigin const&, CommandOutput& output, TeleportPlayer const& p) {
            output.success("传送到玩家 {}", p.target);
        });
}

權限等級

等級	說明
`CommandPermissionLevel::Any`	所有玩家
`CommandPermissionLevel::GameDirectors`	管理員（OP）
`CommandPermissionLevel::Admin`	服務器管理員
`CommandPermissionLevel::Host`	服務器主機
`CommandPermissionLevel::Owner`	服務器擁有者
`CommandPermissionLevel::Internal`	內部使用