事件介绍
事件接口是 EasyBot 的核心功能，你可以在这里注册事件，并监听事件触发。
基本语法
EasyBot 使用 bus 命名空间来管理所有事件的注册和监听。基本语法如下：
bus.on(事件名, 处理函数);
基本写法示例
插件生命周期事件
// 插件启用时触发
bus.on("enable", function() {
logger.info("插件已启用");
});
// 插件禁用时触发
bus.on("disable", function() {
logger.info("插件即将禁用");
});
服务器事件示例
// 玩家登录事件
bus.on("player_login", function(server, playerName, playerUuid) {
logger.info("玩家 {0} ({1}) 尝试登录服务器", playerName, playerUuid);
});
// 玩家消息事件
bus.on("player_message", function(server, packet) {
logger.info("收到玩家消息: {0}", packet.message);
});
桥接事件示例
// 服务器上线事件
bus.on("bridge_server_online", function(server, ip) {
logger.info("服务器 {0} 已上线，IP: {1}", server.Session, ip);
});
// 服务器离线事件
bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
logger.warning("服务器 {0} 已离线，原因: {1}", server.Session, reason);
});
WebKit 事件示例
// 菜单就绪事件 - 在此注册自定义页面和菜单
bus.on("menu_ready", function(pluginMenu) {
pluginMenu.registerGroup("tools", "工具箱", "ToolOutlined");
pluginMenu.register("my_page", "/pages/mypage", "我的页面", "HomeOutlined",
(action) => { /* 处理前端调用 */ },
(sessionId) => { return "<html>...</html>"; }
);
});
配置事件示例
// 配置变更事件
bus.on("config_changed", function(data) {
logger.info("配置 {0} 发生变化: {1}", data.groupId, data.changeType);
});
// 配置启用事件
bus.on("config_enabled", function(groupId, configId, configName, configData) {
logger.info("配置 {0}/{1} 已启用", groupId, configName);
});
事件处理函数的返回值
不同的事件对返回值有不同的处理方式：
1. 无返回值事件
大部分事件只需要监听，不需要返回值：
bus.on("enable", function() {
// 只需要执行逻辑，无需返回值
logger.info("插件启用");
});
2. 可拦截事件
某些事件支持通过返回值来拦截后续处理：
// 返回 true 可以拦截消息同步
bus.on("player_message", function(server, packet) {
if (packet.message.includes("敏感词")) {
return true; // 拦截此消息的同步
}
// 返回 undefined 或不返回，允许正常处理
});
3. 自定义响应事件
某些事件允许返回自定义数据包：
// 玩家登录事件可以返回自定义登录结果
bus.on("player_login", function(server, playerName, playerUuid) {
if (playerName === "banned_player") {
return {
kicked: true,
reason: "您已被封禁"
};
}
// 返回 undefined 允许正常登录
});
注意事项
- 事件注册时机: 建议在插件启用事件中注册其他事件
- 异常处理: 事件处理函数中的异常不会影响其他事件监听器
- 性能考虑: 避免在高频事件中执行耗时操作
- 返回值类型: 严格按照事件定义的返回值类型返回
完整示例
// 在插件启用时注册所有事件
bus.on("enable", function() {
logger.info("插件启动");
});
// 注册玩家登录事件
bus.on("player_login", function(server, playerName, playerUuid) {
logger.info("玩家 {0} 正在登录服务器 {1}", playerName, server.Session);
});
// 注册服务器上线事件
bus.on("bridge_server_online", function(server, ip) {
logger.info("服务器 {0} 已连接，IP: {1}", server.Session, ip);
});
// 注册服务器离线事件
bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
logger.warning("服务器 {0} 已断开连接: {1}", server.Session, reason);
});
// 插件禁用时的清理工作
bus.on("disable", function() {
logger.info("插件即将禁用，执行清理工作");
});
这就是 EasyBot 事件系统的基本写法。接下来的文档将详细介绍每个具体事件的参数和用法。
