MSL 插件开发文档

Appearance

plugin_executeCommand ​

执行 Minecraft 服务器指令，并可选地捕获指令的响应输出。

函数签名 ​

javascript
plugin_executeCommand(command: string, callback?: (lines: string[]) => void): void

参数说明 ​

参数类型必填说明
commandstring是要执行的 Minecraft 指令（不含 / 前缀）
callbackfunction否接收指令响应的回调函数

参数详解 ​

  • command：要执行的完整 Minecraft 指令字符串。注意不要在指令前添加 / 前缀，因为 MSL 直接将指令发送到服务器控制台。

  • callback：可选的回调函数，用于接收指令执行后服务器的输出响应。回调函数接收一个字符串数组参数 lines，包含 500 毫秒内收集到的所有服务器日志行。

返回值 ​

无返回值。

功能描述 ​

plugin_executeCommand 是插件与 Minecraft 服务器交互的核心 API。通过这个函数，插件可以向服务器发送任何控制台指令，如广播消息、传送玩家、管理世界等。

当提供回调函数时，MSL 会捕获指令执行后 500 毫秒内的所有服务器输出，并将其作为字符串数组传递给回调函数。这对于需要获取指令结果的场景非常有用，例如查询在线玩家列表、获取服务器种子等。

使用示例 ​

执行简单指令 ​

javascript
// 广播消息
plugin_executeCommand("say 欢迎来到服务器！");

// 传送玩家
plugin_executeCommand("tp Steve 100 64 200");

// 设置时间
plugin_executeCommand("time set day");

发送彩色消息 ​

javascript
// 使用 tellraw 发送 JSON 格式消息
plugin_executeCommand('tellraw @a {"text":"服务器公告","color":"gold","bold":true}');

// 发送给特定玩家
plugin_onEvent("playerJoin", (time, player) => {
    plugin_executeCommand(`tellraw ${player} {"text":"欢迎回来！","color":"green"}`);
});

捕获指令响应 ​

javascript
// 查询在线玩家
plugin_executeCommand("list", (lines) => {
    lines.forEach(line => {
        if (line.includes("players online")) {
            plugin_log("INFO", `在线玩家信息: ${line}`);
            // 解析玩家列表
            const match = line.match(/There are (\d+) of a max of (\d+) players online/);
            if (match) {
                plugin_log("INFO", `当前在线: ${match[1]}/${match[2]}`);
            }
        }
    });
});

查询服务器信息 ​

javascript
// 查询世界种子
plugin_executeCommand("seed", (lines) => {
    lines.forEach(line => {
        const match = line.match(/Seed: \[(-?\d+)\]/);
        if (match) {
            const seed = match[1];
            plugin_log("INFO", `世界种子: ${seed}`);
            plugin_push("worldSeed", seed);
        }
    });
});

// 查询白名单
plugin_executeCommand("whitelist list", (lines) => {
    const whitelist = [];
    lines.forEach(line => {
        if (line.includes("whitelisted players:")) {
            // 解析白名单玩家
            const players = line.split(":")[1]?.trim().split(", ");
            if (players) {
                whitelist.push(...players.filter(p => p));
            }
        }
    });
    plugin_log("INFO", `白名单玩家: ${whitelist.join(", ")}`);
});

玩家管理 ​

javascript
// 踢出玩家
function kickPlayer(player, reason = "被踢出服务器") {
    plugin_executeCommand(`kick ${player} ${reason}`);
    plugin_log("INFO", `已踢出玩家 ${player}，原因: ${reason}`);
}

// 封禁玩家
function banPlayer(player, reason = "被封禁") {
    plugin_executeCommand(`ban ${player} ${reason}`);
    plugin_log("INFO", `已封禁玩家 ${player}，原因: ${reason}`);
}

// 给予物品
function giveItem(player, item, count = 1) {
    plugin_executeCommand(`give ${player} ${item} ${count}`);
    plugin_log("INFO", `已给予 ${player} ${count} 个 ${item}`);
}

批量执行指令 ​

javascript
// 批量执行多个指令
function executeCommands(commands) {
    commands.forEach((cmd, index) => {
        setTimeout(() => {
            plugin_executeCommand(cmd);
        }, index * 100);  // 每条指令间隔 100ms
    });
}

// 服务器初始化
plugin_onEvent("serverDone", () => {
    executeCommands([
        "gamerule doDaylightCycle false",
        "gamerule doWeatherCycle false",
        "time set day",
        "weather clear",
        "say 服务器已初始化"
    ]);
});

响应捕获机制 ​

当提供回调函数时，MSL 会：

  1. 执行指令并将指令发送到服务器控制台
  2. 开始记录服务器输出
  3. 持续收集 500 毫秒内的所有日志行
  4. 将收集到的日志行数组传递给回调函数

这种机制适用于大多数查询类指令，但对于输出量很大的指令，可能需要额外处理。

注意事项 ​

  1. 指令格式：不要在指令前添加 / 前缀
  2. 响应时间：回调函数会在 500 毫秒后执行，确保服务器有足够时间响应
  3. 异步执行：指令是异步执行的，不会阻塞插件代码
  4. 权限检查：确保服务器有执行相应指令的权限

相关 API ​

相关指南 ​