# 友乐游戏前端通信协议文档（Game_Surface_3 框架逆向）

> 本文档基于现有 H5 前端框架 `projects/Game_Surface_3` 逆向整理，目标是为
> **使用 CocosCreator 重写一款全新前端**提供完整、精确的协议参考，做到
> **服务器不改动一行代码、完美适配**。

## 适配核心原则

新前端只要严格满足以下三点，即可被现有服务器无差别接受：

1. **传输层一致**：WebSocket（`ws://ip:port`）传输，纯文本 JSON；消息双层包装、心跳/握手包识别方式与本文档一致。
2. **消息信封一致**：发送/接收的信封字段 `{app, route, rpc, data}` 完全一致，`app` 恒为 `"youle"`。
3. **字段名/语义一致**：每个 RPC 的 `data` 字段名、类型、取值含义与本文档一致（服务器按字段名读取，多字段不影响，缺字段会报错）。

## 文档结构

| 文件 | 内容 |
|------|------|
| [00-框架架构设计.md](./00-框架架构设计.md) | **先读**：子游戏框架的整体架构——四层结构、自研精灵引擎、桥接层、平台/子游戏分层、生命周期、子游戏接入机制、CocosCreator 映射 |
| [01-传输层与架构.md](./01-传输层与架构.md) | 网络架构、消息信封、双层包装、心跳、握手、连接/重连、服务器切换、登录握手流程 |
| [02-协议-agent路由.md](./02-协议-agent路由.md) | 大厅服务器（route=agent）全部 RPC 收发字段 |
| [03-协议-room路由.md](./03-协议-room路由.md) | 房间服务器（route=room）全部 RPC 收发字段 |
| [04-数据结构.md](./04-数据结构.md) | C_Player、Desk(牌桌)、Player(座位)、登录响应、房间配置等核心数据结构 |
| [05-游戏内协议与桥接.md](./05-游戏内协议与桥接.md) | 子游戏(SubGame)游戏内协议机制、开局/结算流程、H5/小程序桥接 |
| [06-子游戏开发模式与Cocos方案.md](./06-子游戏开发模式与Cocos方案.md) | **重写参考**：框架提供给子游戏的钩子契约、状态归属、子游戏开发模式；含 CocosCreator 两套重写方案（具体某款子游戏的对局模块/roomtype/deskinfo 由各子游戏自定义，本框架文档不展开）|

## 关键事实速览

- **信封格式**：`{ "app":"youle", "route":"agent|room|platform", "rpc":"<rpc名>", "data":{...} }`
- **应用名**：`app = "youle"`（`AppList.app`）
- **路由**：`platform` / `agent`（大厅服）/ `room`（房间服）；其它路由 → 走子游戏 `Game_Modify._ReceiveData`
- **服务器→客户端**为**双层包装**：外层 `{data: <内层>}`，内层才是 `{route,rpc,data}`（详见 01）
- **心跳单向**：服务器约 ~20s 推 `@serverheartbeat`（周期仅源码注释佐证，⚠️待抓包确认），**客户端不回包**；客户端仅做 30s 收包超时检测（`ConstVal.Max.heartbeat=30000`，且仅 `!isGameHall` 时启用）
- **握手包**：连接后服务器首包为 `@toconcon...`，客户端忽略
- **身份字段**：几乎所有请求都带 `agentid`、`gameid`、`playerid`（房间相关再加 `roomcode`）

## 提取来源文件

| 模块 | 文件 |
|------|------|
| 网络发送/接收封装 | `js/00_Surface/09_Net.js` |
| 协议常量(AppList/RouteList/RpcList) | `js/00_Surface/02_Const.js` |
| 连接/分发/心跳/重连 | `js/00_Surface/12_Logic.js` |
| WebSocket/Ajax 底层封装 | `js/00_Surface/00_minhttp.js` |
| 牌桌/房间接收处理 | `js/00_Surface/07_Desk.js` |
| 玩家数据结构 | `js/00_Surface/06_Player.js` |
| 全局数据 | `js/00_Surface/04_Data.js` |
| 子游戏钩子(空模板) | `js/01_SubGame/02_SubGame_Input.js` |
| 子游戏配置 | `js/01_SubGame/00_SubGame_Config.js` |

> ⚠️ **重要说明**：`Game_Surface_3` 是「平台壳框架」。平台层协议（登录/房间/大厅/聊天/排行等）完整可用，
> 已在本文档中精确给出。**游戏内对局协议**（发牌/出牌/结算等）在本工程中 `Game_Modify._ReceiveData` 为
> **空模板**，由各具体子游戏自定义。第 05 章给出其传输通道与格式约定；若需某款具体游戏的对局协议字段，
> 须从对应子游戏工程或抓包补充。

---

## 附录 · 完整 RPC 清单与覆盖状态（对照 `02_Const.js` RpcList）

> ✓=已在文档详述并核对源码；预留=`RpcList` 中定义但框架内**无处理函数/无调用**（历史遗留，新前端可不实现）。

| rpc | 路由 | 方向 | 状态 / 所在章节 |
|-----|------|------|----------------|
| player_login | agent | 收发 | ✓ 02 / 04(响应) |
| create_room | agent | 收发 | ✓ 02 / 04 |
| self_join_room | agent | 收发 | ✓ 02 / 04 |
| quick_enter_share_room | agent | 收发 | ✓ 02 |
| get_share_room | agent | 收发 | ✓ 02 |
| advanced_roomlist / advanced_createroom | agent | 收发 | ✓ 02 |
| getInfoByShortCode | agent | 收发 | ✓ 02 |
| switchRoomList | agent | 收发 | ✓ 02 |
| get_player_grade1 / get_player_grade2 | agent | 收发 | ✓ 02 |
| get_treasurelist / getShortCodeRankList / getVipRankList | agent | 收发 | ✓ 02 |
| get_player_task / player_finish_task / get_task_award | agent | 收发 | ✓ 02 |
| can_award | agent | 推送 | 🐛 02（接收函数 `C_Player.can_award` 未定义，到达即异常）|
| send_phone_code_wechat | agent | 收发 | ✓ 02（微信发手机验证码；调用点被注释，当前不发）|
| submit_error / submit_log | agent | 发送 | ✓ 02（错误上报，二者 rpc 均为 `submit_error`）|
| refresh_task_state | agent | 发送 | ✓ 02（`Send_can_award` 实发此 rpc，硬编码、不在 RpcList）|
| get_paylist / pay_succ / topup_card | agent | 收发 | ✓ 02（pay_succ 经 HTTP 上行，WS 发送处被注释）|
| giveCoin / set_bankpwd / change_star | agent | 收发 | ✓ 02 |
| update_charm / setAllCharm | agent | 推送/发 | ✓ 02 |
| binding_invitecode / get_player_invitecode | agent | 收发 | ✓ 02 |
| optBanList / getPlayerWhiteList / optWhiteList / setVipForbidSelect | agent | 收发 | ✓ 02 |
| binding_phone / send_phone_checkcode / setSign / query_player2 | agent | 收发 | ✓ 02 |
| submit_opinion / submit_location / submit_phoneinfo | agent | 发送 | ✓ 02 |
| kick_server / broadcast / playerBehavior | agent | 收/特殊 | ✓ 02 |
| connect_agentserver | agent | 推送 | ✓ 01 / 02 |
| update_roomcard / update_bean / kick_offline / show_message | agent | 推送 | ✓ 02(末表) |
| self_break_room / other_break_room | room | 收发 | ✓ 03 |
| self_exit_room / other_exit_room | room | 收发 | ✓ 03 |
| other_join_room | room | 推送 | ✓ 03 |
| other_offline / other_online | room | 推送 | ✓ 03 |
| self_apply_free_room / other_apply_free_room | room | 收发 | ✓ 03 |
| self_agree_free_room / other_agree_free_room | room | 收发 | ✓ 03 |
| self_refuse_free_room / other_refuse_free_room | room | 收发 | ✓ 03 |
| free_room | room | 推送 | ✓ 03 |
| self_makewar / other_makewar | room | 收发 | ✓ 03 / 05 |
| player_prepare | room | 收发 | ✓ 03 |
| change_room → change_seat | room | 发/推送 | ✓ 03 |
| send_text / send_voice / send_gift / send_phiz | room | 收发 | ✓ 03 |
| call_phone / hangup_phone | room | 收发 | ✓ 03 |
| beanroom_surrender | room | 收发 | ✓ 03 |
| share_room | room | 收发 | ✓ 03 |
| connect_roomserver | room | 推送 | ✓ 01 / 03 |
| over_game | (游戏内) | 推送 | ✓ 05（结算） |
| agentserver_game | (游戏内) | — | ✓ 05（对局中转保留名） |
| joinRoom (h5RpcList) | (桥接) | — | ✓ 05（H5/小程序唤起） |
| **play_voice** | room | — | **预留**：未实现，语音回包复用 `send_voice` |
| **receive_chat** | room | — | **预留**：未实现，聊天回包复用 `send_text` |
| **other_callphone** | room | — | **预留**：未实现，复用 `call_phone`(带 seat) |
| **other_hangup** | room | — | **预留**：未实现，复用 `hangup_phone`(带 seat) |
| **other_send_gift** | room | — | **预留**：未实现，复用 `send_gift`(带 sendseat) |

> 上述为 `RpcList` 全量（与 `02_Const.js` 1:1 对照）。除 5 个预留名外，全部已在 01–05 章给出收发字段并经源码核对。