Cocos2dx 自定义事件（EventDispatcher）分发与监听技术详解

一、引言​

二、技术背景​

1. Cocos2dx事件系统架构

• EventDispatcher（事件分发器）：全局单例，负责事件的注册、分发与移除，每个Node节点可通过getEventDispatcher()获取。
• EventListener（事件监听器）：抽象类，派生出EventListenerCustom（自定义事件）、EventListenerTouchOneByOne（单点触摸）等子类，定义事件触发时的回调逻辑。
• Event（事件基类）：派生出EventCustom（自定义事件）、EventTouch（触摸事件）等，携带事件类型与数据。

2. 自定义事件 vs 系统事件

三、应用场景​

四、核心原理与流程图​

1. 原理解释

1. 创建事件：通过EventCustom类实例化，指定事件名称（如"EVENT_NAME"），并可附加用户数据（setUserData）。
2. 注册监听器：通过EventDispatcher::addEventListenerWithSceneGraphPriority（场景图优先级，随节点销毁自动移除）或addEventListenerWithFixedPriority（固定优先级，需手动移除）注册EventListenerCustom，绑定回调函数。
3. 分发事件：调用EventDispatcher::dispatchEvent(event)将事件推入分发队列，按顺序触发监听器。
4. 处理事件：监听器回调函数被执行，提取事件数据并处理业务逻辑。
5. 销毁事件：事件处理完毕后自动回收，监听器需在节点销毁时通过removeEventListener移除，避免内存泄漏。

2. 原理流程图

graph TD
    A[业务逻辑触发事件] --> B[创建EventCustom对象]
    B --> C[设置事件名称与用户数据]
    C --> D[EventDispatcher注册监听器]
    D --> E[监听器绑定回调函数]
    E --> F[调用dispatchEvent分发事件]
    F --> G[EventDispatcher按优先级排序监听器]
    G --> H[依次执行监听器回调]
    H --> I[处理事件数据（业务逻辑）]
    I --> J[事件处理完毕，清理资源]
    J --> K[移除无用监听器（可选）]

五、核心特性​

1. 灵活的事件标识：通过字符串命名事件（如"PLAYER_HURT"），支持动态扩展。
2. 优先级控制：监听器可设置优先级（数值越小优先级越高），高优先级监听器先执行。
3. 事件吞噬（Swallow）：部分事件支持吞噬（如触摸事件），但自定义事件默认不吞噬，需手动控制传播。
4. 跨节点通信：事件可在任意节点间传递，无需知道发送者/接收者具体类型。
5. 用户数据传递：通过EventCustom::setUserData传递任意类型数据（需继承Ref或用std::shared_ptr管理）。

六、环境准备​

1. 开发环境

• 引擎版本：Cocos2dx 3.17+（推荐4.0+，优化了事件系统性能）
• 开发工具：
  • Windows：Visual Studio 2019+
  • macOS：Xcode 12+
  • Android：Android Studio + NDK r21+
• 语言：C++11+（支持lambda表达式简化回调）

2. 项目配置

auto dispatcher = Director::getInstance()->getEventDispatcher(); // 全局分发器
// 或节点局部分发器（随节点销毁）
auto nodeDispatcher = this->getEventDispatcher();

七、详细代码实现​

场景1：基础自定义事件（无参数）​

1. 头文件（CustomEventBase.h）

#ifndef CUSTOM_EVENT_BASE_H
#define CUSTOM_EVENT_BASE_H

#include "cocos2d.h"
using namespace cocos2d;

class CustomEventBase : public Layer {
public:
    static Scene* createScene();
    virtual bool init() override;
    CREATE_FUNC(CustomEventBase);

private:
    // 按钮点击回调（触发事件）
    void onButtonClick(Ref* sender, ui::Widget::TouchEventType type);
    // 自定义事件监听器回调
    void onCustomEvent(EventCustom* event);
};

#endif // CUSTOM_EVENT_BASE_H

2. 源文件（CustomEventBase.cpp）

#include "CustomEventBase.h"
#include "ui/CocosGUI.h"

USING_NS_CC;

Scene* CustomEventBase::createScene() {
    auto scene = Scene::create();
    auto layer = CustomEventBase::create();
    scene->addChild(layer);
    return scene;
}

bool CustomEventBase::init() {
    if (!Layer::init()) return false;

    // 1. 创建按钮（触发事件）
    auto button = ui::Button::create("button_normal.png", "button_pressed.png");
    button->setTitleText("触发事件");
    button->setPosition(Vec2(VisibleRect::center().x, VisibleRect::center().y));
    button->addClickEventListener(CC_CALLBACK_1(CustomEventBase::onButtonClick, this));
    addChild(button);

    // 2. 注册自定义事件监听器（事件名称："BUTTON_CLICKED"）
    auto listener = EventListenerCustom::create("BUTTON_CLICKED", 
        CC_CALLBACK_1(CustomEventBase::onCustomEvent, this));
    // 使用场景图优先级（随节点销毁自动移除）
    _eventDispatcher->addEventListenerWithSceneGraphPriority(listener, this);

    return true;
}

void CustomEventBase::onButtonClick(Ref* sender, ui::Widget::TouchEventType type) {
    if (type == ui::Widget::TouchEventType::ENDED) {
        // 3. 创建并分发自定义事件（无参数）
        EventCustom event("BUTTON_CLICKED");
        _eventDispatcher->dispatchEvent(&event);
        CCLOG("【触发】按钮点击事件已分发");
    }
}

void CustomEventBase::onCustomEvent(EventCustom* event) {
    // 4. 处理事件（输出日志）
    CCLOG("【接收】监听到自定义事件：%s", event->getEventName().c_str());
    // 可通过event->getUserData()获取附加数据（本示例无参数）
}

场景2：带参数的自定义事件​

1. 数据载体（PlayerLevelUpData.h）

#ifndef PLAYER_LEVEL_UP_DATA_H
#define PLAYER_LEVEL_UP_DATA_H

#include "cocos2d.h"
using namespace cocos2d;

class PlayerLevelUpData : public Ref {
public:
    static PlayerLevelUpData* create(int newLevel, int newHP) {
        auto data = new (std::nothrow) PlayerLevelUpData();
        if (data && data->init(newLevel, newHP)) {
            data->autorelease();
            return data;
        }
        CC_SAFE_DELETE(data);
        return nullptr;
    }

    int getNewLevel() const { return _newLevel; }
    int getNewHP() const { return _newHP; }

private:
    bool init(int newLevel, int newHP) {
        _newLevel = newLevel;
        _newHP = newHP;
        return true;
    }

    int _newLevel;
    int _newHP;
};

#endif // PLAYER_LEVEL_UP_DATA_H

2. 事件发布者（EventPublisher.h）

#ifndef EVENT_PUBLISHER_H
#define EVENT_PUBLISHER_H

#include "cocos2d.h"
#include "PlayerLevelUpData.h"
using namespace cocos2d;

class EventPublisher : public Node {
public:
    CREATE_FUNC(EventPublisher);

    void triggerLevelUpEvent(int newLevel, int newHP) {
        // 1. 创建事件数据
        auto data = PlayerLevelUpData::create(newLevel, newHP);
        // 2. 创建自定义事件，附加数据
        EventCustom event("PLAYER_LEVEL_UP");
        event.setUserData(data); // 设置用户数据
        // 3. 分发事件
        _eventDispatcher->dispatchEvent(&event);
        CCLOG("【发布】玩家升级事件：等级%d，生命值%d", newLevel, newHP);
    }
};

#endif // EVENT_PUBLISHER_H

3. 事件监听者（EventSubscriber.h + EventSubscriber.cpp）

// EventSubscriber.h
#ifndef EVENT_SUBSCRIBER_H
#define EVENT_SUBSCRIBER_H

#include "cocos2d.h"
#include "PlayerLevelUpData.h"
using namespace cocos2d;

class EventSubscriber : public Node {
public:
    CREATE_FUNC(EventSubscriber);
    virtual bool init() override;

private:
    Label* _levelLabel; // 显示等级的标签
    void onLevelUpEvent(EventCustom* event); // 事件回调
};

#endif // EVENT_SUBSCRIBER_H

// EventSubscriber.cpp
#include "EventSubscriber.h"

bool EventSubscriber::init() {
    if (!Node::init()) return false;

    // 创建UI标签
    _levelLabel = Label::createWithSystemFont("当前等级：1", "Arial", 30);
    _levelLabel->setPosition(Vec2(VisibleRect::center().x, VisibleRect::center().y));
    addChild(_levelLabel);

    // 注册监听器（事件名称："PLAYER_LEVEL_UP"）
    auto listener = EventListenerCustom::create("PLAYER_LEVEL_UP", 
        CC_CALLBACK_1(EventSubscriber::onLevelUpEvent, this));
    _eventDispatcher->addEventListenerWithSceneGraphPriority(listener, this);

    return true;
}

void EventSubscriber::onLevelUpEvent(EventCustom* event) {
    // 1. 获取事件数据
    auto data = static_cast<PlayerLevelUpData*>(event->getUserData());
    if (!data) return;

    // 2. 处理数据（更新UI）
    int newLevel = data->getNewLevel();
    int newHP = data->getNewHP();
    _levelLabel->setString(StringUtils::format("当前等级：%d\n生命值：%d", newLevel, newHP));
    CCLOG("【订阅】收到升级事件：等级%d，生命值%d", newLevel, newHP);
}

4. 整合场景（GameScene.cpp）

#include "GameScene.h"
#include "EventPublisher.h"
#include "EventSubscriber.h"

bool GameScene::init() {
    if (!Layer::init()) return false;

    // 添加发布者
    auto publisher = EventPublisher::create();
    addChild(publisher);

    // 添加订阅者
    auto subscriber = EventSubscriber::create();
    addChild(subscriber);

    // 模拟玩家升级（3秒后触发事件）
    scheduleOnce([=](float dt) {
        publisher->triggerLevelUpEvent(5, 200); // 等级5，生命值200
    }, 3.0f, "level_up_schedule");

    return true;
}

场景3：跨场景事件与监听器移除​

关键代码（SceneTransition.cpp）

// 场景A（发布事件）
void SceneA::switchToSceneB() {
    // 发布场景切换事件，传递场景B路径
    EventCustom event("SCENE_TRANSITION");
    event.setUserData(String::create("SceneB")); // 传递场景名称
    _eventDispatcher->dispatchEvent(&event);

    // 切换到场景B
    Director::getInstance()->replaceScene(SceneB::createScene());
}

// 场景B（监听事件）
bool SceneB::init() {
    if (!Layer::init()) return false;

    // 注册监听器（固定优先级，需手动移除）
    auto listener = EventListenerCustom::create("SCENE_TRANSITION", 
        CC_CALLBACK_1(SceneB::onSceneTransition, this));
    _eventDispatcher->addEventListenerWithFixedPriority(listener, 1); // 优先级1

    return true;
}

void SceneB::onSceneTransition(EventCustom* event) {
    auto sceneName = static_cast<String*>(event->getUserData())->getCString();
    CCLOG("【场景B】收到切换事件，目标场景：%s", sceneName);
}

// 场景B销毁时移除监听器（避免内存泄漏）
void SceneB::onExit() {
    Layer::onExit();
    _eventDispatcher->removeEventListener(listener); // 需保存listener指针
}

场景4：优先级与事件吞噬​

// 监听器1（高优先级，优先级1）
auto listener1 = EventListenerCustom::create("PRIORITY_TEST", 
    [](EventCustom* event) {
        CCLOG("【高优先级监听器】执行");
        // 吞噬事件（阻止低优先级执行）
        // event->stopPropagation(); // 自定义事件默认不吞噬，需手动实现标记
    });
_eventDispatcher->addEventListenerWithFixedPriority(listener1, 1); // 优先级1（高）

// 监听器2（低优先级，优先级2）
auto listener2 = EventListenerCustom::create("PRIORITY_TEST", 
    [](EventCustom* event) {
        CCLOG("【低优先级监听器】执行");
    });
_eventDispatcher->addEventListenerWithFixedPriority(listener2, 2); // 优先级2（低）

// 分发事件
EventCustom event("PRIORITY_TEST");
_eventDispatcher->dispatchEvent(&event);
// 输出：先执行listener1，再执行listener2（若未调用stopPropagation）

八、运行结果与测试步骤​

1. 预期效果

• 场景1：点击按钮后，日志输出“【触发】按钮点击事件已分发”和“【接收】监听到自定义事件：BUTTON_CLICKED”。
• 场景2：3秒后，标签显示“当前等级：5 生命值：200”，日志输出发布与订阅信息。
• 场景3：场景切换时，场景B日志输出目标场景名称。
• 场景4：事件分发后，高优先级监听器先执行，低优先级后执行（若未吞噬）。

2. 测试步骤

1. 环境配置：创建Cocos2dx项目，将上述代码文件加入Classes目录，配置资源路径（如按钮图片）。
2. 编译运行：使用VS/Xcode编译并部署到真机/模拟器。
3. 功能验证：
   • 场景1：点击按钮，观察控制台日志。
   • 场景2：等待3秒，观察UI标签变化与日志。
   • 场景3：切换场景，检查场景B是否正确接收事件。
   • 场景4：分发事件，确认监听器执行顺序。

九、部署场景​

十、疑难解答​

十一、未来展望与技术趋势​

1. 趋势

• 异步事件支持：Cocos2dx可能引入异步事件分发（如基于std::future），避免阻塞主线程。
• 事件总线（Event Bus）封装：更高层的事件总线类，简化多事件管理与订阅者注册。
• 类型安全事件：通过模板或强类型枚举替代字符串事件名称，减少拼写错误（如enum class EventType { PLAYER_LEVEL_UP }）。
• 跨线程事件：支持后台线程分发事件，主线程监听并更新UI（需线程同步机制）。

2. 挑战

• 事件依赖管理：复杂系统中事件间可能存在依赖（如A事件需等待B事件完成），需引入事件编排机制。
• 性能优化：高频事件（如每帧更新的位置同步）可能导致性能瓶颈，需支持事件合并与节流。
• 调试难度：事件流分散在各模块，需开发可视化事件调试工具（如事件日志追踪）。

十二、总结​

1. 核心流程：创建EventCustom→注册EventListenerCustom→分发事件→处理回调。