Cocos Creator 快速开始与功能指南

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

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

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

Cocos Creator 端提供与声网 Cocos Creator 公开 API 对齐的 TypeScript 接口，覆盖频道加入、发布订阅、事件与错误处理。媒体与渲染能力通过注入的桥接入你的原生工程，SDK 本身不内置媒体栈。

前置条件#

• Cocos Creator 3.8+（TypeScript）。
• 一个平台桥：CocosBridgePort.invoke(method, params)。Web 构建目标用浏览器 RTC 桥；原生构建目标用

Cocos2d-x 绑定（同一个 ni-meet C++ 核心）。

• App ID 与 Token 服务（见 控制台开通服务与获取凭证）。

安装#

pnpm --filter @nimeet/rtc-cocos build      # 源码 sdk/cocos，产物 sdk/cocos/build

Cocos Creator 3.x 支持 npm 依赖，把构建产物目录作为本地包引入；当前以源码方式提供。

获取 Token#

Token 由你的后端 POST /v1/tokens 签发，客户端只拿 { appId, rtcToken, rtcUid }， 语义见 AccessToken2 语义。initialize 接收 App ID，joinChannel 接收 Token。

加入频道#

import { AgoraRtc } from '@nimeet/rtc-cocos';

const client = AgoraRtc.createAgoraRtcClient({ bridge }); // bridge = 你的 CocosBridgePort
await client.initialize(appId);
await client.joinChannel(token, 'channel-a', 1234);
await client.setClientRole('broadcaster');

• initialize(string | AgoraRtcEngineConfig)：App ID 为空 → protocol_error。
• 需要引擎的成员在 initialize 之前调用 → bridge_unavailable（提示 call initialize() first），不会打到桥。
• joinChannel(token, channelId, uid, options?)：频道名为空或 uid 非整数 → protocol_error。

发布与订阅#

绑定层与声网 Cocos 封装一致：不管理 track 对象，用工程开关表达发布/订阅意图。

• 音频：enableAudio / enableLocalAudio / muteLocalAudioStream / muteRemoteAudioStream / muteAllRemoteAudioStreams / setAudioProfile；
• 视频：enableVideo / enableLocalVideo / muteLocal* / muteRemote* / startPreview / stopPreview / switchCamera；
• 渲染：setupLocalVideoView(canvas) / setupRemoteVideoView(uid, canvas) / update* / remove*，以及 setRenderBackend('engine-texture')；
• 混音与音效：startAudioMixing / pauseAudioMixing / resumeAudioMixing / stopAudioMixing / getAudioMixingCurrentPosition / setAudioMixingPosition / adjustAudioMixing*,

preloadEffect / playEffect / pauseEffect / resumeEffect / stopEffect / setEffectsVolume。

每个成员都带"文档化的方法名"转发给桥；桥侧实现见 sdk/cocos2dx（原生）或浏览器 RTC 桥（Web）。

事件#

on(event, listener) 返回取消订阅函数，off(event, listener) 精确移除。事件集合是兼容版本里的 23 个 AgoraEventMap 键：

uploadLogResult、joinChannelSuccess、leaveChannel、rejoinChannelSuccess、connectionInterrupted、 connectionStateChanged、localVideoTextureReady、remoteVideoTextureReady、localVideoTextureReleased、 remoteVideoTextureReleased、renderBackendState、userJoined、userOffline、remoteVideoStateChanged、 localVideoStateChanged、firstLocalAudioFramePublished、audioMixingFinished、audioMixingStateChanged、 remoteAudioStateChanged、volumeIndication、rtcStats、contentInspectResult、error。

错误处理#

错误对象 AgoraSdkError，code 是文档化的字符串码，原生数字码（若有）在 nativeCode：

本端所有公开成员都已实现；调用失败会返回上表中的错误码，不会返回假成功。

排障#

已知限制#

• 兼容目标：Cocos Creator 端与声网 Cocos Creator 的公开 API 对齐；声网未提供该端官方 API 文档，接口以公开声明为准。
• 事件：事件按名称对齐，载荷类型以本页事件表为准。
• 行为由桥决定：生命周期、参数校验、事件分发、超时与错误映射由 SDK 处理；媒体、渲染与混音转发给注入的桥，实际表现取决于宿主工程的原生实现。
• 部分导出仅供桥内部使用：纹理槽缓存、纹理视图管理等不属于公开 API。

下一步#

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

平台信息

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

可用性

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

加入频道链路

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

enableVideo(enabled: boolean): Promise<void>
initialize(config: string|AgoraRtcEngineConfig): Promise<void>
joinChannel(token: string, channelId: string, uid: number, options?: AgoraChannelMediaOptions): Promise<void>
leaveChannel(options?: AgoraLeaveChannelOptions): Promise<void>
muteRemoteAudioStream(uid: number, muted: boolean): Promise<void>
renewToken(token: string): Promise<void>
setChannelProfile(profile: 'communication'|'liveBroadcasting'): Promise<void>
setClientRole(role: 'broadcaster'|'audience', options?: AgoraClientRoleOptions): Promise<void>

事件与回调

错误码

平台 REST 层用 REST 错误码；SDK 层把连接/鉴权失败映射成声网错误号，映射表见 各端 SDK 错误标识。