MSL 插件开发文档

Appearance

plugin_log ​

输出日志到控制台，带有插件名称前缀和时间戳。

函数签名 ​

javascript
plugin_log(type: "INFO" | "WARN" | "ERROR", message: string): void

参数说明 ​

参数类型必填说明
typestring是日志类型：INFO、WARN 或 ERROR
messagestring是日志消息内容

参数详解 ​

  • type：日志类型，影响日志的显示颜色和重要性

    • "INFO"：普通信息日志，白色显示
    • "WARN"：警告日志，黄色显示
    • "ERROR"：错误日志，红色显示

  • message：日志消息内容，会与时间戳和插件名称一起输出

返回值 ​

无返回值。

功能描述 ​

plugin_log 是插件输出日志的标准方式。所有通过此函数输出的日志都会带有统一格式的时间戳和插件名称前缀，便于追踪和调试。

日志格式为：

[HH:mm:ss TYPE]: [pluginName] message

其中：

  • HH:mm:ss：当前时间
  • TYPE：日志类型（INFO/WARN/ERROR）
  • pluginName：当前插件名称
  • message：日志消息

使用示例 ​

基本用法 ​

javascript
// 输出信息日志
plugin_log("INFO", "插件已加载");

// 输出警告日志
plugin_log("WARN", "配置文件不存在，使用默认配置");

// 输出错误日志
plugin_log("ERROR", "无法连接到数据库");

在事件中使用 ​

javascript
plugin_onEvent("playerJoin", (time, player) => {
    plugin_log("INFO", `玩家 ${player} 加入了服务器`);
});

plugin_onEvent("playerQuit", (time, player) => {
    plugin_log("INFO", `玩家 ${player} 离开了服务器`);
});

plugin_onEvent("serverLog", (line) => {
    if (line.includes("WARN")) {
        plugin_log("WARN", `检测到服务器警告: ${line}`);
    }
    if (line.includes("ERROR")) {
        plugin_log("ERROR", `检测到服务器错误: ${line}`);
    }
});

调试日志 ​

javascript
const DEBUG = true;

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

plugin_onEvent("playerSendMessage", (time, player, message) => {
    debugLog(`${player} 说: ${message}`);
});

错误处理日志 ​

javascript
async function fetchData(url) {
    try {
        plugin_log("INFO", `正在请求: ${url}`);
        // ... 请求逻辑
    } catch (error) {
        plugin_log("ERROR", `请求失败: ${error.message}`);
        plugin_log("ERROR", `堆栈: ${error.stack}`);
    }
}

使用 console 对象 ​

MSL 沙箱环境中的 console 对象会自动调用 plugin_log：

javascript
// 这两种方式等效
plugin_log("INFO", "消息");
console.log("消息");

plugin_log("WARN", "警告");
console.warn("警告");

plugin_log("ERROR", "错误");
console.error("错误");

日志颜色 ​

不同类型的日志在控制台中显示不同颜色：

  • INFO：白色（默认颜色）
  • WARN：黄色
  • ERROR：红色

输出示例 ​

[10:30:45 INFO]: [myplugin] 插件已加载
[10:30:50 INFO]: [myplugin] 玩家 Steve 加入了服务器
[10:31:00 WARN]: [myplugin] 配置项缺失，使用默认值
[10:31:10 ERROR]: [myplugin] 无法连接到数据库

最佳实践 ​

1. 选择合适的日志级别 ​

javascript
// 正常操作日志
plugin_log("INFO", "玩家加入服务器");

// 潜在问题
plugin_log("WARN", "配置文件格式错误，使用默认配置");

// 严重错误
plugin_log("ERROR", "数据库连接失败，插件无法正常工作");

2. 包含上下文信息 ​

javascript
// 不推荐：信息不足
plugin_log("INFO", "玩家加入");

// 推荐：包含详细信息
plugin_log("INFO", `玩家 ${player} 在 ${time} 加入了服务器，IP: ${ip}`);

3. 结构化日志 ​

javascript
function logPlayerAction(action, player, details) {
    plugin_log("INFO", `[${action}] ${player}: ${JSON.stringify(details)}`);
}

logPlayerAction("JOIN", "Steve", { time: "10:30:45", ip: "192.168.1.1" });
logPlayerAction("CHAT", "Steve", { message: "Hello!" });

4. 错误日志包含堆栈 ​

javascript
try {
    // 可能出错的代码
} catch (error) {
    plugin_log("ERROR", `操作失败: ${error.message}`);
    plugin_log("ERROR", `堆栈信息: ${error.stack}`);
}

注意事项 ​

  1. 日志频率：避免在高频事件（如 serverLog）中输出过多日志
  2. 敏感信息：不要在日志中输出密码、令牌等敏感信息
  3. 调试模式：调试日志应该只在调试模式下输出

相关 API ​