友乐游戏前端通信协议文档（Game_Surface_3 框架逆向）
本文档基于现有 H5 前端框架
projects/Game_Surface_3逆向整理，目标是为 使用 CocosCreator 重写一款全新前端提供完整、精确的协议参考，做到 服务器不改动一行代码、完美适配。
适配核心原则
新前端只要严格满足以下三点，即可被现有服务器无差别接受：
- 传输层一致：WebSocket（
ws://ip:port）传输，纯文本 JSON；消息双层包装、心跳/握手包识别方式与本文档一致。 - 消息信封一致：发送/接收的信封字段
{app, route, rpc, data}完全一致，app恒为"youle"。 - 字段名/语义一致：每个 RPC 的
data字段名、类型、取值含义与本文档一致（服务器按字段名读取，多字段不影响，缺字段会报错）。
文档结构
| 文件 | 内容 |
|---|---|
| 00-框架架构设计.md | 先读：子游戏框架的整体架构——四层结构、自研精灵引擎、桥接层、平台/子游戏分层、生命周期、子游戏接入机制、CocosCreator 映射 |
| 01-传输层与架构.md | 网络架构、消息信封、双层包装、心跳、握手、连接/重连、服务器切换、登录握手流程 |
| 02-协议-agent路由.md | 大厅服务器（route=agent）全部 RPC 收发字段 |
| 03-协议-room路由.md | 房间服务器（route=room）全部 RPC 收发字段 |
| 04-数据结构.md | C_Player、Desk(牌桌)、Player(座位)、登录响应、房间配置等核心数据结构 |
| 05-游戏内协议与桥接.md | 子游戏(SubGame)游戏内协议机制、开局/结算流程、H5/小程序桥接 |
| 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.js1:1 对照）。除 5 个预留名外，全部已在 01–05 章给出收发字段并经源码核对。