MSL 插件开发文档

Appearance

调试插件 ​

在开发插件过程中，调试是必不可少的环节。MSL 提供了多种调试工具和命令，帮助你快速定位和解决问题。

调试模式 ​

开启调试模式 ​

调试模式会输出详细的 API 调用日志，帮助你追踪插件的执行流程。

方法一：配置文件

在 config.js 中设置：

javascript
module.exports = {
    debug: true,  // 开启调试模式
    // ...其他配置
}

方法二：控制台命令

在 MSL 控制台中输入：

msl debug on

关闭调试模式 ​

msl debug off

查看调试状态 ​

msl debug

输出示例：

[10:30:45 INFO]: [MinecraftServerListener] Debug mode is ON

调试日志内容 ​

开启调试模式后，每次调用插件 API 都会输出日志：

[10:30:45 INFO]: [MinecraftServerListener] plugin_require('axios')
[10:30:45 INFO]: [MinecraftServerListener] plugin_executeCommand('list', [callback])
[10:30:45 INFO]: [MinecraftServerListener] plugin_onEvent('playerJoin')
[10:30:45 INFO]: [MinecraftServerListener] plugin_registerCommand('!ping')

注意

serverLog 事件不会输出调试日志，因为服务器日志非常频繁，会导致日志刷屏。

热重载插件 ​

MSL 最重要的调试功能之一是热重载，它允许你在不重启 Minecraft 服务器的情况下重新加载插件代码。

重载所有插件 ​

msl reload

这个命令会：

  1. 卸载所有已加载的插件
  2. 清除所有事件监听器、注册的指令和 API
  3. 清除所有定时器
  4. 重新加载 plugins 目录下的所有插件

输出示例：

[10:30:45 INFO]: [MinecraftServerListener] All plugins have been unloaded
[10:30:45 INFO]: [MinecraftServerListener] Plugin 'demo' is loading...
[10:30:45 INFO]: [demo] Demo plugin loaded
[10:30:45 INFO]: [MinecraftServerListener] Plugin 'demo' is done
[10:30:45 INFO]: [MinecraftServerListener] All plugins have been reloaded

单独加载/卸载插件 ​

加载单个插件：

msl enable_plugin myplugin

卸载单个插件：

msl disable_plugin myplugin

加载所有插件：

msl enable_plugin all

卸载所有插件：

msl disable_plugin all

插件状态管理 ​

查看插件列表 ​

msl list_plugins

输出示例：

[10:30:45 INFO]: [MinecraftServerListener] Plugin list:
  - demo [loaded]
  - myplugin [unloaded]
[10:30:45 INFO]: [MinecraftServerListener] Total: 2 plugins, 1 loaded

插件状态说明 ​

状态说明
loaded插件已加载并运行中
unloaded插件文件存在但未加载

日志输出 ​

使用 plugin_log ​

在插件中使用 plugin_log 输出日志：

javascript
plugin_log("INFO", "这是一条信息日志");
plugin_log("WARN", "这是一条警告日志");
plugin_log("ERROR", "这是一条错误日志");

输出格式：

[10:30:45 INFO]: [myplugin] 这是一条信息日志
[10:30:45 WARN]: [myplugin] 这是一条警告日志
[10:30:45 ERROR]: [myplugin] 这是一条错误日志

使用 console 对象 ​

沙箱环境中的 console 对象会自动添加插件名称前缀：

javascript
console.log("普通日志");    // 等同于 plugin_log("INFO", ...)
console.warn("警告日志");   // 等同于 plugin_log("WARN", ...)
console.error("错误日志");  // 等同于 plugin_log("ERROR", ...)

常见问题排查 ​

1. 插件没有加载 ​

检查步骤：

  1. 确认插件文件在 plugins 目录下
  2. 确认文件扩展名是 .js
  3. 使用 msl list_plugins 查看插件状态
  4. 检查是否有语法错误

常见原因：

  • 文件名错误
  • 语法错误（缺少括号、引号等）
  • 文件编码问题（建议使用 UTF-8）

2. 事件没有触发 ​

检查步骤：

  1. 大部分事件没有触发的情况都是因为正则表达式配置错误导致的，请查阅快速开始章节：快速开始
  2. 确认事件名称拼写正确
  3. 确认服务器日志格式与配置中的正则表达式匹配
  4. 开启调试模式查看事件是否被触发

示例：

javascript
// 正确的事件名称
plugin_onEvent("playerJoin", ...);  // ✓
plugin_onEvent("playerjoin", ...);  // ✗ 大小写敏感

3. 指令没有响应 ​

检查步骤：

  1. 确认指令格式正确
  2. 确认玩家输入的指令与注册的表达式匹配
  3. 开启调试模式查看指令是否被匹配

指令匹配规则：

javascript
// 注册指令
plugin_registerCommand("!ping", ...);

// 玩家输入：!ping        ✓ 匹配
// 玩家输入：!ping extra  ✗ 参数数量不匹配
// 玩家输入：!Ping        ✗ 大小写敏感

4. HTTP API 无法访问 ​

检查步骤：

  1. 确认 HTTP 服务已启用（msl enable_http）
  2. 确认请求包含正确的 Authorization 头
  3. 确认 API 路径注册正确

正确的请求示例：

bash
curl -H "Authorization: Bearer your-api-token" http://localhost:30600/api/demo

调试技巧 ​

1. 使用 try-catch 捕获错误 ​

javascript
plugin_onEvent("playerJoin", (time, player) => {
    try {
        // 可能出错的代码
        riskyOperation(player);
    } catch (error) {
        plugin_log("ERROR", `处理玩家 ${player} 时出错: ${error.message}`);
        plugin_log("ERROR", `堆栈信息: ${error.stack}`);
    }
});

2. 输出变量值 ​

javascript
plugin_onEvent("playerSendMessage", (time, player, message) => {
    plugin_log("INFO", `调试 - time: ${time}, player: ${player}, message: ${message}`);
    plugin_log("INFO", `调试 - message 类型: ${typeof message}, 长度: ${message.length}`);
});

3. 使用全局数据存储调试信息 ​

关于存储调试信息

使用全局数据存储调试信息是可选的，根据需要选择是否使用。

javascript
// 存储调试计数器
let debugCounter = plugin_pull("debugCounter") || 0;

plugin_onEvent("serverLog", (line) => {
    debugCounter++;
    if (debugCounter % 100 === 0) {
        plugin_log("INFO", `已处理 ${debugCounter} 行日志`);
    }
    plugin_push("debugCounter", debugCounter);
});

4. 条件调试 ​

关于条件调试

若所做插件公开，可通过fs模块创建一配置文件，让用户决定是否开启调试模式。

javascript
const DEBUG_MODE = true;  // 开发时设为 true，发布时设为 false

function debugLog(message) {
    if (DEBUG_MODE) {
        plugin_log("INFO", `[DEBUG] ${message}`);
    }
}

plugin_onEvent("playerJoin", (time, player) => {
    debugLog(`玩家加入: ${player}`);
});

服务器控制 ​

启动/停止服务器 ​

在调试过程中，你可能需要重启 Minecraft 服务器：

msl stopmc    # 停止服务器
msl startmc   # 启动服务器

强制停止服务器 ​

如果服务器无响应，可以使用强制停止：

javascript
// 在插件中
plugin_forceStopServer();

注意

强制停止会直接杀死服务器进程，可能导致数据丢失。仅在必要时使用。

HTTP 服务控制 ​

禁用/启用 HTTP 服务 ​

msl disable_http  # 禁用 HTTP 服务
msl enable_http   # 启用 HTTP 服务

下一步 ​