youle_cocos/docs/protocol

友乐游戏前端通信协议文档（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	先读：子游戏框架的整体架构——四层结构、自研精灵引擎、桥接层、平台/子游戏分层、生命周期、子游戏接入机制、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.js 1:1 对照）。除 5 个预留名外，全部已在 01–05 章给出收发字段并经源码核对。