Godot 接入

安装客户端 SDK

官方提供 GDExtension（实验性）与 Godot Mono（C#） 等接入方式，详见：

完整集成教程（官方）：Godot Engine · Getting Started

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

说明	链接
Godot 插件安装、Web 导出与示例	Getting Started · Godot
认证体系总览	Authentication
房间侧鉴权概念	Room Authentication
本项目 JWT 如何进房	JWT 与房间鉴权

接入方式建议

桌面 / 移动端：优先按官方文档安装插件与启用顺序。
Web 导出：官方文档要求开启 Extensions Support。
需要强类型 Schema 时，可使用文档中的 State Schema Codegen（GDScript 输出）。

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

以下示例适用于 Godot 4 + Colyseus GDExtension（与官方文档中 Colyseus.Client、join_or_create 用法一致）。请将脚本挂到场景中的 Node；按需在 Inspector 填写账号密码，或改为小游戏登录 URL。

（客户端代码）

gdscript

extends Node

@export var http_host := "127.0.0.1"
@export var http_port := 2567
@export var api_prefix := "/api"
@export var login_username := ""
@export var login_password := ""

var _client: Colyseus.Client
var _room: Colyseus.Room

func _ready() -> void:
    var http := HTTPRequest.new()
    add_child(http)
    http.request_completed.connect(_on_login_completed.bind(http))

    var url := "http://%s:%d%s/auth/login" % [http_host, http_port, api_prefix]
    var body := JSON.stringify({"username": login_username, "password": login_password})
    var headers := PackedStringArray(["Content-Type: application/json"])
    var err := http.request(url, headers, HTTPClient.METHOD_POST, body)
    if err != OK:
        push_error("HTTP 请求发起失败: %s" % err)

func _on_login_completed(http: HTTPRequest, _result: int, code: int, _headers: PackedStringArray, body: PackedByteArray) -> void:
    http.queue_free()
    if code != 200:
        push_error("登录 HTTP 状态: %d" % code)
        return

    var text := body.get_string_from_utf8()
    var j := JSON.parse_string(text)
    if typeof(j) != TYPE_DICTIONARY:
        push_error("登录响应非 JSON 对象")
        return

    var data: Variant = j.get("data", {})
    if typeof(data) != TYPE_DICTIONARY:
        push_error("登录响应缺少 data")
        return

    var tokens: Variant = data.get("tokens", {})
    if typeof(tokens) != TYPE_DICTIONARY:
        push_error("登录响应缺少 tokens")
        return

    var access_token: String = tokens.get("accessToken", "")
    if access_token.is_empty():
        push_error("未解析到 accessToken")
        return

    var ws_url := "ws://%s:%d" % [http_host, http_port]
    _client = Colyseus.Client.new(ws_url)

    var opts := {"token": access_token}
    _room = _client.join_or_create("my_room", opts)
    if _room:
        _room.joined.connect(_on_room_joined)
        _room.message_received.connect(_on_message_received)
        _room.error.connect(_on_room_error)

func _on_room_joined() -> void:
    print("已进房 id=", _room.get_id(), " session=", _room.get_session_id())
    _room.send_message("chat", {"text": "hello from Godot"})

func _on_message_received(type: Variant, data: Variant) -> void:
    print("message ", type, " ", data)

func _on_room_error(code: int, message: String) -> void:
    push_error("房间错误 %d: %s" % [code, message])

func _exit_tree() -> void:
    if _room and _room.connected:
        _room.leave()

说明：

若你使用的 Colyseus Godot 版本中 join_or_create 仅支持房间名一个参数，请查阅当前插件文档，将 token 合并到官方约定的 options 字典或等价 API 中。
进房 options 使用 token（与 accessToken 等价），详见 JWT 与房间鉴权。
房间内 Room.state（Schema） 的字段含义与 Colyseus.Callbacks 监听示例见文档状态同步（Schema）。

最小接入目标

通过 HTTP 登录拿到 JWT（与服务端约定一致）
使用 SDK 连接服务端并 join_or_create 进入房间
处理状态回调、message_received 与主动 send_message

Godot 接入 ​

安装客户端 SDK ​

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

接入方式建议 ​