Cocos2d-x（C++ 绑定） 快速开始与功能指南

Cocos2d-x（C++ 绑定）：前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障；接口名与签名在构建时取自公开 SDK 接口定义。

接口小节由公开 SDK 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

Cocos2d-x 端以 C++ 绑定库的形式提供：公开头文件定义与声网 C++ API 对齐的成员名与签名，实现层通过 IRtcEngineCore 接缝转发到 ni-meet C++ 核心，媒体能力由宿主工程注入。

#include <nimeet/cocos2dx/rtc_engine.h>   // 公开 C++ 接口
#include <nimeet/cocos2dx/core_seam.h>    // 核心适配接缝（宿主实现）

前置条件#

• Cocos2d-x 3.17+（C++17）；Android NDK / Xcode 由宿主工程提供。
• 宿主应用里已集成 ni-meet C++ 核心，并实现 nimeet::cocos2dx::IRtcEngineCore 接缝（1:1 转发，不含媒体逻辑）。
• App ID 与 Token 服务（见 控制台开通服务与获取凭证）。

安装#

把 SDK 的头文件目录加入头文件搜索路径，并把源文件加入构建列表即可。当前以源码方式提供，不发布独立包。

target_include_directories(your_game PRIVATE path/to/nimeet/cocos2dx/include)
target_sources(your_game PRIVATE path/to/nimeet/cocos2dx/src/rtc_engine_adapter.cpp)

获取 Token#

与其他端一致：Token 由你的后端 POST /v1/tokens 签发。绑定层的 joinChannel(token, channelId, uid) 直接接收 Token 字符串， 语义见 AccessToken2 语义。

加入频道#

#include "nimeet/cocos2dx/rtc_engine.h"
#include "nimeet/cocos2dx/core_seam.h"

class AppHandler : public nimeet::cocos2dx::IRtcEngineEventHandler
{
public:
    void onJoinChannelSuccess(const char* channel, nimeet::cocos2dx::uid_t uid, int elapsed) override { /* update UI */ }
    void onUserJoined(nimeet::cocos2dx::uid_t uid, int elapsed) override { /* attach remote view */ }
    void onError(int err, const char* msg) override { /* err 是文档错误码 */ }
};

nimeet::cocos2dx::RtcEngineAdapter engine(core);   // core 实现 nimeet::cocos2dx::IRtcEngineCore
AppHandler handler;
nimeet::cocos2dx::RtcEngineContext context;
context.appId = appId;
context.eventHandler = &handler;
engine.initialize(context);
engine.joinChannel(token, "channel-a", "info", 1234);

initialize 之后才能 joinChannel / leaveChannel：否则返回文档错误码 -7（ERR_NOT_INITIALIZED）。 initialize 缺 App ID 返回 -2（ERR_INVALID_ARGUMENT）。

发布与订阅#

绑定层只暴露文档化的开关语义，不管理 track：

• 音频：enableAudio / disableAudio / enableLocalAudio / muteLocalAudioStream / muteRemoteAudioStream / muteAllRemoteAudioStreams；
• 视频：enableVideo / disableVideo / enableLocalVideo / muteLocalVideoStream / muteRemoteVideoStream / muteAllRemoteVideoStreams；
• 预览与渲染：startPreview() / startPreview(VIDEO_SOURCE_TYPE) / stopPreview(…) / switchCamera /

setupLocalVideo(VideoCanvas) / setupRemoteVideo(VideoCanvas)（setupRemoteVideo 的 uid == 0 返回 -2）；

• 编码：setVideoEncoderConfiguration（宽高非正数返回 -2）。

事件#

回调由 IRtcEngineEventHandler 承载，14 个成员与固定的 C++ 对齐基准逐签名一致：

onJoinChannelSuccess、onRejoinChannelSuccess、onLeaveChannel、onUserJoined、onUserOffline、 onConnectionStateChanged、onError、onAudioVolumeIndication、onLocalAudioStateChanged、onRemoteAudioStateChanged、 onLocalVideoStateChanged、onRemoteVideoStateChanged、onRtcStats、onRequestToken。

initialize 把 eventHandler 交给核心（IRtcEngineCore::SetEventHandler），核心推事件、绑定层不解释事件内容。

错误处理#

成员返回文档化的 Agora C++ 错误码（0 成功；负数失败），绑定层从不把失败改写成成功：

错误码枚举与错误号见 错误码全表。

排障#

下一步#

• 完整接口与重载：同端 API 参考
• 错误码与排障：错误码全表、FAQ
• 服务端签发 Token：Token 鉴权

平台信息

本端公开接口与声网 cocos2dx 端 API 对齐；安装与运行要求见上面前置条件。

可用性

该端 SDK：正式可用。本页代码片段使用公开 API；运行时的能力边界以实际发布的 SDK 包为准。

加入频道链路

下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载，这里展示最常用的那一个；完整重载见同端 API 参考页。

enableVideo(): int
initialize(context: const RtcEngineContext&): int
joinChannel(token: const char*, channelId: const char*, info: const char*, uid: uid_t): int
leaveChannel(): int
muteRemoteAudioStream(uid: uid_t, mute: bool): int
renewToken(token: const char*): int
setChannelProfile(profile: CHANNEL_PROFILE_TYPE): int
setClientRole(role: CLIENT_ROLE_TYPE): int
setupLocalVideo(canvas: const VideoCanvas&): int

事件与回调

回调注册在 IRtcEngineEventHandler 上；不同端的命名可能不同，完整清单见同端 API 参考页。

错误码

该端 SDK 未提供错误码常量。平台侧错误见 错误码全表，跨端 SDK 错误标识见 各端 SDK 错误标识。