MSL 插件开发文档

Appearance

plugin_onEvent ​

监听事件，当指定事件发生时执行回调函数。

函数签名 ​

javascript
plugin_onEvent(eventName: string, callback: (...args: any[]) => void): void

参数说明 ​

参数类型必填说明
eventNamestring是要监听的事件名称
callbackfunction是事件触发时的回调函数

参数详解 ​

  • eventName：事件名称，可以是 MSL 内置事件或自定义事件

    • 内置事件：serverStart、serverStop、serverDone、playerJoin、playerQuit、playerSendMessage、playerSendCommand、pluginLoaded、serverLog
    • 自定义事件：由 plugin_triggerEvent 触发的事件

  • callback：事件回调函数，参数取决于事件类型

    • 不同事件有不同的参数列表
    • 回调函数中的错误会被 MSL 自动捕获

返回值 ​

无返回值。

功能描述 ​

plugin_onEvent 是 MSL 事件系统的核心 API。通过这个函数，插件可以监听服务器发生的各种事件，如玩家加入、玩家退出、服务器启动完成等，并在事件发生时执行相应的处理逻辑。

MSL 采用事件驱动架构，事件监听器是插件与服务器交互的主要方式之一。多个插件可以同时监听同一事件，互不干扰。当插件卸载时，该插件注册的所有事件监听器会自动清除。

内置事件列表 ​

服务器生命周期事件 ​

事件参数触发时机
serverStart无服务器进程启动时
serverStop无服务器进程停止时
serverDone无服务器启动完成时

玩家事件 ​

事件参数触发时机
playerJointime, player玩家加入服务器时
playerQuittime, player玩家离开服务器时
playerSendMessagetime, player, message玩家发送聊天消息时
playerSendCommandtime, player, command, args玩家执行指令时

其他事件 ​

事件参数触发时机
pluginLoadedpluginName插件加载完成时
serverLogline服务器输出每一行日志时

使用示例 ​

监听服务器事件 ​

javascript
// 服务器启动
plugin_onEvent("serverStart", () => {
    plugin_log("INFO", "服务器进程已启动");
});

// 服务器停止
plugin_onEvent("serverStop", () => {
    plugin_log("INFO", "服务器进程已停止");
});

// 服务器启动完成
plugin_onEvent("serverDone", () => {
    plugin_log("INFO", "服务器启动完成！");
    plugin_executeCommand("say 服务器已就绪");
});

监听玩家事件 ​

javascript
// 玩家加入
plugin_onEvent("playerJoin", (time, player) => {
    plugin_log("INFO", `[${time}] 玩家 ${player} 加入了服务器`);
    
    // 发送欢迎消息
    plugin_executeCommand(`tellraw ${player} {"text":"欢迎来到服务器！","color":"green"}`);
    
    // 记录加入次数
    const joinCount = plugin_pull("joinCount") || {};
    joinCount[player] = (joinCount[player] || 0) + 1;
    plugin_push("joinCount", joinCount);
    
    if (joinCount[player] === 1) {
        plugin_executeCommand(`say 欢迎新玩家 ${player}！`);
    }
});

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

// 玩家聊天
plugin_onEvent("playerSendMessage", (time, player, message) => {
    plugin_log("INFO", `[聊天] ${player}: ${message}`);
    
    // 记录聊天日志
    const chatLog = plugin_pull("chatLog") || [];
    chatLog.push({ time, player, message });
    plugin_push("chatLog", chatLog);
});

// 玩家执行指令
plugin_onEvent("playerSendCommand", (time, player, command, args) => {
    plugin_log("INFO", `[指令] ${player} 执行了 /${command} ${args.join(" ")}`);
});

监听日志事件 ​

javascript
// 监听服务器日志
plugin_onEvent("serverLog", (line) => {
    // 检测警告
    if (line.includes("WARN")) {
        plugin_log("WARN", `检测到服务器警告: ${line}`);
    }
    
    // 检测错误
    if (line.includes("ERROR") || line.includes("Exception")) {
        plugin_log("ERROR", `检测到服务器错误: ${line}`);
    }
});

监听插件加载事件 ​

javascript
// 监听其他插件加载
plugin_onEvent("pluginLoaded", (pluginName) => {
    plugin_log("INFO", `插件 ${pluginName} 已加载`);
    
    // 可以在这里处理插件依赖
    if (pluginName === "myDependency") {
        plugin_log("INFO", "依赖插件已加载，开始初始化");
        initializePlugin();
    }
});

监听自定义事件 ​

javascript
// 监听自定义事件
plugin_onEvent("myPlugin:playerLevelUp", (player, level) => {
    plugin_log("INFO", `${player} 升级到 ${level} 级`);
    plugin_executeCommand(`say ${player} 升级了！当前等级: ${level}`);
});

// 另一个插件触发该事件
plugin_triggerEvent("myPlugin:playerLevelUp", "Steve", 50);

错误处理 ​

javascript
// 在回调中添加错误处理
plugin_onEvent("playerJoin", (time, player) => {
    try {
        // 可能出错的操作
        processPlayerJoin(player);
    } catch (error) {
        plugin_log("ERROR", `处理玩家加入事件失败: ${error.message}`);
    }
});

注意事项 ​

  1. 事件名称区分大小写：playerJoin 和 playerjoin 是不同的事件
  2. 回调错误处理：MSL 会捕获回调中的错误，但建议自行处理
  3. serverLog 事件频率：此事件非常频繁，避免在其中执行耗时操作
  4. 自动清理：插件卸载时，所有事件监听器会自动清除

相关 API ​

相关指南 ​