Cocos Creator 接入

1. 安装客户端 SDK

推荐使用 colyseus.js（TypeScript 项目最顺滑）。

完整集成教程（官方）：Cocos Creator 3 · Getting Started

官方文档索引（引擎 + Colyseus）

说明	链接
Cocos 扩展安装、db://colyseus-sdk 引用方式	Getting Started · Cocos Creator
认证体系总览	Authentication
房间侧鉴权概念	Room Authentication
本项目 JWT 如何进房	JWT 与房间鉴权

2. 连接服务端

服务端默认地址（本地）：http://localhost:2567（WebSocket 为 ws://localhost:2567）。

3. 登录并获取 JWT

先调用 HTTP 登录接口获取 JWT（详见 API 概览），再加入需要鉴权的房间。

账号登录示例：POST /api/auth/login，请求体 {"username":"...","password":"..."}，响应在 data.tokens.accessToken（与 Swagger 一致）。小游戏登录见 微信 / 抖音 教程，取响应中的 token 字段即可同样作为进房凭证。

4. 示例代码（HTTP 登录 + 带 JWT 进房）

以下示例与官方文档一致，从扩展路径引入 Colyseus；将脚本挂在任意节点上，在编辑器中填写 httpHost / 端口（与 Getting Started · Cocos Creator 中 NetworkManager 用法相同）。

（客户端代码）

import { _decorator, Component } from "cc";
const { ccclass, property } = _decorator;

import Colyseus from "db://colyseus-sdk/colyseus.js";

@ccclass("ColyseusAuthExample")
export class ColyseusAuthExample extends Component {
  @property httpHost = "127.0.0.1";
  @property httpPort = 2567;
  @property wsUseSSL = false;
  /** 与 routeConfig 一致，默认 /api */
  @property apiPrefix = "/api";

  /** 测试用账号（请改为真实用户或小游戏登录流程） */
  @property loginUsername = "";
  @property loginPassword = "";

  private client!: Colyseus.Client;

  start() {
    const proto = this.wsUseSSL ? "wss" : "ws";
    const portPart = [80, 443].includes(this.httpPort) ? "" : `:${this.httpPort}`;
    this.client = new Colyseus.Client(`${proto}://${this.httpHost}${portPart}`);
    void this.run();
  }

  private async run() {
    const base = `http${this.wsUseSSL ? "s" : ""}://${this.httpHost}:${this.httpPort}`;
    const loginUrl = `${base}${this.apiPrefix}/auth/login`;

    const res = await fetch(loginUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        username: this.loginUsername,
        password: this.loginPassword,
      }),
    });
    const json = (await res.json()) as {
      success?: boolean;
      data?: { tokens?: { accessToken?: string } };
      message?: string;
    };
    if (!res.ok || !json?.success || !json.data?.tokens?.accessToken) {
      console.error("登录失败", json?.message ?? res.statusText);
      return;
    }
    const accessToken = json.data.tokens.accessToken;

    try {
      const room = await this.client.joinOrCreate("my_room", {
        token: accessToken,
      });
      console.log("已进房", room.sessionId);

      room.onMessage("chat", (payload) => {
        console.log("chat", payload);
      });

      room.send("chat", { text: "hello from Cocos" });
    } catch (e) {
      console.error("进房失败", e);
    }
  }
}

要点：

• 进房 options 使用 token（与 accessToken 等价，见 鉴权与权限）。
• 聊天房需额外传 guildId / teamId 等时，与 token 写在同一对象即可（见 消息协议）。

5. 加入房间并收发消息（摘要）

• joinOrCreate(roomName, { token })
• room.onMessage("xxx", cb)
• room.send("xxx", payload)

6. 常见问题

• 真机/微信小游戏域名与 HTTPS 限制
• 断线重连与房间重入策略
• 本项目 JWT 与 Redis 规则：JWT 与房间鉴权