MSL 插件开发文档

Appearance

plugin_registerCommand ​

注册自定义指令，允许玩家在游戏中通过聊天或命令触发插件功能。

函数签名 ​

javascript
plugin_registerCommand(expression: string, callback: (player: string, ...args: string[]) => void): void

参数说明 ​

参数类型必填说明
expressionstring是指令表达式，定义指令格式
callbackfunction是指令触发时的回调函数

参数详解 ​

  • expression：指令表达式，格式为 <prefix><command> [参数...]

    • prefix：指令前缀，必须是 !（聊天指令）或 /（命令指令）
    • command：指令名称
    • 参数：可选参数，使用 <param> 格式表示动态参数，其他文本为固定匹配

  • callback：指令回调函数，当玩家输入匹配的指令时触发

    • player：触发指令的玩家名称
    • args：指令参数（如果表达式中有 <param>）

返回值 ​

无返回值。

功能描述 ​

plugin_registerCommand 是 MSL 插件系统中最常用的 API 之一。通过这个函数，插件可以注册自定义指令，让玩家在游戏中通过简单的聊天或命令来触发插件功能。

MSL 支持两种类型的指令：

  • 聊天指令：以 ! 开头，玩家在聊天框中输入即可触发
  • 命令指令：以 / 开头，可以拦截玩家执行的 Minecraft 原生命令

指令匹配采用严格匹配规则，参数数量必须完全匹配，固定文本必须完全一致。

使用示例 ​

简单指令 ​

javascript
// 注册 !ping 指令
plugin_registerCommand("!ping", (player) => {
    plugin_executeCommand(`say ${player} 请求了 ping！`);
    plugin_log("INFO", `${player} 使用了 !ping 指令`);
});

带参数的指令 ​

javascript
// 注册 !kick <player> 指令
plugin_registerCommand("!kick <player>", (player, target) => {
    plugin_executeCommand(`kick ${target} 被 ${player} 踢出`);
    plugin_log("INFO", `${player} 踢出了 ${target}`);
});

// 注册 !ban <player> <reason> 指令
plugin_registerCommand("!ban <player> <reason>", (player, target, reason) => {
    plugin_executeCommand(`ban ${target} ${reason}`);
    plugin_log("INFO", `${player} 封禁了 ${target}，原因：${reason}`);
});

混合固定文本和参数 ​

javascript
// 注册 !tp to <player> 指令
plugin_registerCommand("!tp to <player>", (player, target) => {
    plugin_executeCommand(`tp ${player} ${target}`);
    plugin_log("INFO", `${player} 传送到 ${target}`);
});

// 注册 !tp coords <x> <y> <z> 指令
plugin_registerCommand("!tp coords <x> <y> <z>", (player, x, y, z) => {
    plugin_executeCommand(`tp ${player} ${x} ${y} ${z}`);
    plugin_log("INFO", `${player} 传送到 (${x}, ${y}, ${z})`);
});

拦截原版命令 ​

javascript
// 拦截 /home 命令
plugin_registerCommand("/home", (player) => {
    const homes = plugin_pull("playerHomes") || {};
    if (homes[player]) {
        const home = homes[player];
        plugin_executeCommand(`tp ${player} ${home.x} ${home.y} ${home.z}`);
        plugin_executeCommand(`tellraw ${player} {"text":"已传送到你的家","color":"green"}`);
    } else {
        plugin_executeCommand(`tellraw ${player} {"text":"你还没有设置家","color":"red"}`);
    }
});

// 拦截 /sethome 命令
plugin_registerCommand("/sethome", (player) => {
    // 注意：需要其他方式获取玩家坐标
    plugin_executeCommand(`tellraw ${player} {"text":"家已设置！","color":"green"}`);
});

权限控制 ​

javascript
// 定义管理员列表
const admins = ["Steve", "Admin", "Owner"];

// 带权限检查的指令
plugin_registerCommand("!admin <action> <player>", (player, action, target) => {
    // 检查权限
    if (!admins.includes(player)) {
        plugin_executeCommand(`tellraw ${player} {"text":"权限不足","color":"red"}`);
        return;
    }
    
    // 执行管理员操作
    switch (action.toLowerCase()) {
        case "kick":
            plugin_executeCommand(`kick ${target}`);
            break;
        case "ban":
            plugin_executeCommand(`ban ${target}`);
            break;
        case "op":
            plugin_executeCommand(`op ${target}`);
            break;
        default:
            plugin_executeCommand(`tellraw ${player} {"text":"未知操作: ${action}","color":"red"}`);
    }
});

帮助系统 ​

javascript
// 注册 !help 指令
plugin_registerCommand("!help", (player) => {
    const helpMessages = [
        "========== 服务器帮助 ==========",
        "!help - 显示帮助信息",
        "!online - 查看在线玩家",
        "!home - 传送到家",
        "!sethome - 设置家",
        "!msg <player> <message> - 发送私聊",
        "================================"
    ];
    
    helpMessages.forEach(msg => {
        plugin_executeCommand(`tellraw ${player} {"text":"${msg}","color":"yellow"}`);
    });
});

指令匹配规则 ​

MSL 使用严格的指令匹配规则：

1. 前缀匹配 ​

javascript
plugin_registerCommand("!ping", ...);

// 匹配：!ping
// 不匹配：/ping, ping

2. 名称匹配（区分大小写） ​

javascript
plugin_registerCommand("!Ping", ...);

// 匹配：!Ping
// 不匹配：!ping, !PING

3. 参数数量匹配 ​

javascript
plugin_registerCommand("!kick <player>", ...);

// 匹配：!kick Alex
// 不匹配：!kick, !kick Alex reason

4. 固定文本匹配 ​

javascript
plugin_registerCommand("!tp to <player>", ...);

// 匹配：!tp to Alex
// 不匹配：!tp Alex, !tp from Alex

注意事项 ​

  1. 指令冲突：如果多个插件注册了相同的指令，只有第一个注册的会生效
  2. 插件卸载：插件卸载时，所有注册的指令会自动清除
  3. 错误处理：回调函数中的错误会被 MSL 捕获并记录日志
  4. 性能考虑：避免在回调函数中执行耗时操作

相关 API ​

相关指南 ​