用途:该技能用于在 Godot 4.3+ 项目中与 REST API、排行榜、分析服务、登录服务及其他 HTTP/WebSocket 后端通信,示例均针对 Godot 4.3+ 且不使用已弃用 API,先给 GDScript 再给 C#。
主要能力:
- 工具选型:普通 REST 调用或文件/图片下载用 HTTPRequest 节点;流式响应、自定义 keep-alive、对同一主机的大量请求用 HTTPClient;持久双向通道(聊天、实时事件、大厅服务)用 WebSocketPeer;带 RPC 的实时玩法同步用 WebSocketMultiplayerPeer。一个 HTTPRequest 节点同一时间只跑一个请求,第二个 request() 会返回 ERR_BUSY,因此应为每个并发请求创建一个节点。
- 单次请求:request() 只负责发起,返回值表示是否成功发送,而非服务器是否应答;结果通过 request_completed(result, response_code, headers, body) 信号获得,需同时检查传输结果与 HTTP 状态码,404/500 也会以 RESULT_SUCCESS 到达。
- 可复用 JSON API 客户端:以 autoload 形式封装(如命名 Api),每次调用各自创建 HTTPRequest,因此调用可重叠;支持 Accept/Content-Type/Authorization 头、JSON 序列化与解析、统一返回结构。资料另提及重试与指数退避、场景切换时取消请求、认证刷新流程,位于 references/rest-client-patterns.md。
- JSON 陷阱:JSON 数字一律解析为 float,用作索引、枚举或字典键前需转 int;parse_string() 遇错误返回 null 并记录错误,需要行号与消息时改用 JSON 实例;索引前先校验数据结构(Dictionary、has 键);stringify 后再 parse 会把整数变回浮点;stringify 仅适用于 Variant 类型,自定义对象或 Resource 需先转 Dictionary。
- 下载与上传:设置 download_file 可直接写入磁盘;用 get_downloaded_bytes() 与 get_body_size() 做进度条(无长度时为 -1,Web 上恒为 -1);body_size_limit 限制体积;request_raw 做二进制上传;远程图片用 Image 的 load_png_from_buffer/jpg/webp 后创建 ImageTexture。
- TLS 与密钥:HTTPS 对内置 CA 列表开箱即用;自签名或私有 CA 用 TLSOptions.client(cert) 并 set_tls_options();client_unsafe() 会跳过校验,切勿发布。导出包内任何内容都可被读取,特权密钥应放在自有服务器上代理;玩家令牌可存 user:// 但应视为可撤销而非机密;凭据应放在头或 POST 体,不要放 GET 查询参数。TLS 1.2 全面支持,TLS 1.3 自 Godot 4.4 起支持,4.3 连接仅支持 TLS 1.3 或仅支持 TLS 1.1 及更早的服务器会握手失败。
- 平台注意事项:Android 需在导出预设中启用 INTERNET 权限;Web 请求经浏览器发出,服务器须返回 CORS 头,https 页面禁止 http 混合内容;专用服务器可运行请求以避免密钥到达客户端。
- WebSocket 客户端:WebSocketPeer 需每帧调用 poll(),按 STATE_OPEN/STATE_CLOSED 处理收发与关闭码;使用 wss:// 与服务器真实主机名以便证书匹配,Web 导出在 https 页面必须用 wss://;handshake_headers 在 Web 上被忽略,应以连接后首条消息认证,URL 参数只能用短期一次性票据;Godot 4.4+ 可用 heartbeat_interval 维持空闲连接(Web 无效);在 STATE_CLOSED 时按退避重连而非每帧重连。
- 常见问题与检查清单:ERR_BUSY 源于复用节点;ERR_UNCONFIGURED 因节点未入树;timeout 为 0.0 会永久挂起,API 调用宜设 5–15 秒,大文件下载应改用停滞检查或取消按钮;编辑器可用而 Android 失败多为缺少 INTERNET 权限;桌面可用而 Web 失败多为 CORS 或混合内容;id 变 5.0 需强转;设置了 download_file 导致 body 为空;场景切换后请求不再完成是因父节点被释放。清单还包括每个并发请求独立节点并及时 queue_free、检查传输结果与状态码、校验解析数据形状、不在客户端内置特权密钥、不滥用 client_unsafe()、Web 构建对真实服务器测试、失败应向玩家呈现而非静默失败。
适用场景:Godot 游戏接入排行榜、登录、分析、下载更新包或远程图片、实时事件推送等。限制:所有示例仅针对 Godot 4.3+;重试与认证刷新等进阶模式的正文需查阅随附参考文件,资料未给出其完整内容;未提及任何收费、价格或效果信息。