plugin_triggerEvent

触发自定义事件，用于实现插件间通信或通知其他监听器。

函数签名

plugin_triggerEvent(eventName: string, ...args: any[]): void

参数说明

参数	类型	必填	说明
eventName	string	是	事件名称
...args	any[]	否	传递给事件监听器的参数

参数详解

• eventName：事件名称，建议使用插件名作为前缀以避免冲突，如 "myPlugin:customEvent"
• args：任意数量的参数，会原样传递给所有监听该事件的回调函数

返回值

无返回值。

功能描述

plugin_triggerEvent 用于触发自定义事件。当调用此函数时，所有通过 plugin_onEvent 监听该事件的回调函数都会被调用，并接收传入的参数。

这个函数主要用于以下场景：

• 插件间通信：一个插件触发事件，其他插件监听并响应
• 模块化设计：将插件功能拆分为多个模块，通过事件通信
• 扩展机制：允许其他插件扩展你的插件功能

使用示例

基本用法

// 触发一个简单事件
plugin_triggerEvent("myPlugin:initialized");

// 触发带参数的事件
plugin_triggerEvent("myPlugin:playerAction", "Steve", "jumped");

插件间通信

插件 A（触发事件）：

// economy-plugin.js
plugin_onEvent("playerJoin", (time, player) => {
    // 查询玩家经济数据
    const economy = plugin_pull("economy") || {};
    const balance = economy[player] || 0;
    
    // 触发事件，通知其他插件
    plugin_triggerEvent("economy:balanceChecked", player, balance);
});

// 玩家购买物品
function purchaseItem(player, item, cost) {
    const economy = plugin_pull("economy") || {};
    if ((economy[player] || 0) >= cost) {
        economy[player] -= cost;
        plugin_push("economy", economy);
        
        // 触发购买事件
        plugin_triggerEvent("economy:purchase", player, item, cost);
        return true;
    }
    return false;
}

插件 B（监听事件）：

// welcome-plugin.js
plugin_onEvent("economy:balanceChecked", (player, balance) => {
    if (balance > 1000) {
        plugin_executeCommand(`tellraw ${player} {"text":"尊贵的VIP玩家！","color":"gold"}`);
    }
});

plugin_onEvent("economy:purchase", (player, item, cost) => {
    plugin_log("INFO", `${player} 购买了 ${item}，花费 ${cost}`);
});

模块化设计

// 主模块
function initializePlugin() {
    loadConfig();
    setupCommands();
    
    // 触发初始化完成事件
    plugin_triggerEvent("myPlugin:ready");
}

// 配置模块
plugin_onEvent("myPlugin:ready", () => {
    plugin_log("INFO", "插件已就绪，开始处理业务");
    startBackgroundTasks();
});

// 命令模块
plugin_onEvent("myPlugin:ready", () => {
    registerAllCommands();
});

玩家成就系统

// 定义成就
const achievements = {
    "first_join": { name: "初次到来", description: "第一次加入服务器" },
    "first_kill": { name: "初出茅庐", description: "击杀第一个怪物" },
    "level_10": { name: "小有成就", description: "达到10级" }
};

// 授予成就
function grantAchievement(player, achievementId) {
    const achievement = achievements[achievementId];
    if (!achievement) return;
    
    plugin_log("INFO", `${player} 获得成就: ${achievement.name}`);
    plugin_executeCommand(`tellraw ${player} {"text":"获得成就: ${achievement.name}","color":"gold"}`);
    plugin_executeCommand(`playsound minecraft:entity.player.levelup master ${player}`);
    
    // 触发成就事件
    plugin_triggerEvent("achievement:granted", player, achievementId, achievement);
}

// 监听玩家加入，授予首次加入成就
plugin_onEvent("playerJoin", (time, player) => {
    const joined = plugin_pull("joinedPlayers") || {};
    if (!joined[player]) {
        joined[player] = true;
        plugin_push("joinedPlayers", joined);
        grantAchievement(player, "first_join");
    }
});

// 其他插件可以监听成就事件
plugin_onEvent("achievement:granted", (player, achievementId, achievement) => {
    // 记录到数据库或发送通知
    plugin_log("INFO", `成就系统: ${player} - ${achievement.name}`);
});

事件链

// 事件链处理
plugin_onEvent("playerJoin", (time, player) => {
    // 触发预处理事件
    plugin_triggerEvent("playerJoin:pre", player);
});

plugin_onEvent("playerJoin:pre", (player) => {
    // 检查玩家状态
    checkPlayerStatus(player);
    
    // 触发主处理事件
    plugin_triggerEvent("playerJoin:process", player);
});

plugin_onEvent("playerJoin:process", (player) => {
    // 发送欢迎消息
    sendWelcomeMessage(player);
    
    // 触发后处理事件
    plugin_triggerEvent("playerJoin:post", player);
});

plugin_onEvent("playerJoin:post", (player) => {
    // 记录日志
    logPlayerJoin(player);
});

事件命名规范

建议使用以下命名规范以避免事件名称冲突：

// 推荐：使用插件名作为前缀
plugin_triggerEvent("myPlugin:eventName", ...args);

// 推荐：使用命名空间
plugin_triggerEvent("economy:player:purchase", player, item);
plugin_triggerEvent("economy:player:sell", player, item);

// 不推荐：通用名称可能冲突
plugin_triggerEvent("update", ...);  // 可能与其他插件冲突

注意事项

1. 同步执行：所有事件监听器会同步执行，避免在监听器中执行耗时操作
2. 错误隔离：某个监听器的错误不会影响其他监听器的执行
3. 参数传递：参数会原样传递给所有监听器
4. 调试模式：开启调试模式后，自定义事件触发会输出日志（serverLog 事件除外）

相关 API

• plugin_onEvent - 监听事件

相关指南

• 事件机制 - 详细了解事件系统