daoqi/youle_cocos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c2e487d8f5b43cdc64b155939652d3f45e7fa98
youle_cocos/CLAUDE.md
T
joywayerandClaude Opus 4.8 2e18396388 docs(claude): 新增客户端侧适配约束（远程配置/原生数据/WVJB 桥接） 
第二类不可妥协约束：远程配置文件读取(get_config→ServerUrl_Succ)、
原生同步接口(window.settings.getothername)、原生↔H5 异步桥
(WebViewJavascriptBridge: setupWebViewJavascriptBridge + registerHandler/callHandler)
须与原项目逐字一致；含源码位置与 14+ 个已注册 handler 清单 + Cocos 适配注意。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 14:15:37 +08:00

81 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 第一准则：服务器零改动
**任何前端开发都必须完全遵循前后端数据包的协议与数据结构，做到服务器零改动。** 这是本仓库不可逾越的最高准则，优先于一切其它考量：
- 协议信封、`route`/`rpc` 命名、字段名与类型、`roomtype` 配置数组、`deskinfo` 快照结构等，**必须与现有协议逐字节对齐**（依据 `docs/protocol/`），不得为前端方便而改变格式或新增/重命名字段。
- 遇到协议层有疑问时，**先读 `docs/protocol/` 对应章节核对，不要臆测**；宁可前端多做适配，也绝不要求服务器配合改动。
- 新的 Cocos 前端（`YouleNexus`）的目标，就是在不改服务器的前提下复刻该协议契约、实现联调兼容。
## 仓库总览
这是友乐（Youle）棋牌游戏平台的前端工作区，核心是「**一套前端模板 + 多个子游戏**」的架构，并正在迁移到 Cocos Creator。三个顶层目录：
- **`projects/`** —— 旧版 HTML5 前端。`projects/Game_Surface_3` 是**前端模板（平台外壳）**，其余目录（`doudizhu` / `erqiwang` / `niuniu` / `majiang_jx` / `guanpai-jx` / `pdk_card_client-jinxian` / `sangelaok` / `zpy` / `gamehall3` …）都是**基于该模板扩展出来的子游戏**，平台层几乎不动，只改子游戏层 + 美术数据。
- **`docs/protocol/`** —— 前端模板框架与服务器收发包的**协议规范**（权威文档，8 篇）。改动任何网络层代码前**必须先读对应章节**，服务器不可改，前端必须严格对齐协议。
- **`cocoscreator_projects/YouleNexus/`** —— 新的 Cocos Creator 3.8+ 前端工程，目标是按 `docs/protocol` 复刻协议契约，做到服务器零改动即可联调。
## 前端模板 Game_Surface_3 与子游戏（`projects/`）
**四层结构（自底向上）：**
1. **引擎层** —— `js/gameabc.min.js`（gameabc 精灵引擎）+ Spine（`spine-canvas.js` / `SpineMgr.js`）+ Canvas 渲染；提供触屏/定时器/资源/WebSocket 底层回调。
2. **桥接层** —— `js/gamemain.js`：统一事件总线，把引擎回调分发到平台 UI、子游戏 `Game_Modify`、对战逻辑。
3. **平台层** —— `js/00_Surface/*`（12 个文件）：登录、大厅、房间、聊天、社交、网络、资源、排行、任务等通用能力。**子游戏间几乎不变**。
4. **子游戏层** —— `js/01_SubGame/*`（3 个文件）：只实现本游戏的对局逻辑与房间 UI。
**平台层关键文件（`js/00_Surface/`）：** `02_Const.js`（`ConstVal`/`AppList`/路由表）、`04_Data.js`（`GameData` 全局态）、`09_Net.js`（`Net._SendData()` 收发分发）、`12_Logic.js`（`Logic` 连接/重连/分发编排）、`07_Desk.js`（`Desk` 房间状态机）、`06_Player.js`（`C_Player`/`Player` 数据结构）、`11_GameUI.js`（平台 UI）、`00_minhttp.js`（WebSocket 底层封装）。
**子游戏层（`js/01_SubGame/`，开发子游戏 = 改这 3 个文件 + 美术数据）：**
- `00_SubGame_Config.js` —— `Game_Config`（房间数、气泡位置、分享、调试开关）
- `01_SubGame_modify.js` —— `Game_Modify` / `gameCombat`（对局实现 + 房间/胜负 UI）
- `02_SubGame_Input.js` —— 平台回调钩子（模板里是桩，子游戏覆写为真实逻辑）
- 另需补充：`gamemain.js`（扩展对局初始化）、专用算法模块（牌型/出牌等）、美术数据 `output/gameabc_data.min.js`。
**状态归属：** 平台层维护 `Desk`（房间/座位）、`C_Player`（自己）、`GameData`（连接/资产）；子游戏维护对局态（手牌、出牌历史、轮次、分数）于自身命名空间，并需可序列化为 `deskinfo` 以支持断线重连。
## 网络协议（`docs/protocol/`，新旧前端共同契约）
- **传输层：** 单条长连 **WebSocket，纯 JSON 文本**（无二进制/protobuf）。先 HTTP GET 配置服务拿 `urlserver`，再 `ws://<ip:port>` 连接；支持 `connect_agentserver`/`connect_roomserver` 切换服务器。
- **消息信封：**
- 客户端→服务器（单层）：`{ "app":"youle", "route":"agent|room|platform|<game_route>", "rpc":"<name>", "data":{…} }`
- 服务器→客户端（**双层包裹**）：外层 `{ "data": <inner> }`；inner 可能是字符串需 `JSON.parse`。**收包必做过滤**：`@toconcon`（前 9 字符，握手包，忽略）、`data.com === "@serverheartbeat"`（服务器心跳，~20s 一次，**不回复**）。
- **路由分发：** `route ∈ {agent, room, platform}` → 平台层处理（`Net.<rpc>` → `Desk.*` / `C_Player.*`）；`route` 为其它值 → 交子游戏 `Game_Modify._ReceiveData(msg)`，由子游戏 `switch(msg.rpc)` 派发对局包。平台请求通用身份字段：`agentid`/`gameid`/`playerid`（房间操作再加 `roomcode`）。
- **心跳/超时/重连：** 客户端 30s 收包超时（`ConstVal.Max.heartbeat = 30000`），超时报“网络慢”并重连；断线时 `Logic` 轮询候选服务器，重连后重发 `player_login`。
- **核心数据结构（详见 `04-数据结构.md`）：** `C_Player`（本地玩家）、`Player(seat)`（座位玩家）、`Desk`（房间/牌桌）、`player_login` 响应（账号资产 + 可选房间恢复段：`roomcode`/`isbattle`/`deskinfo`…）。
- **两个不可妥协的约束：** ① `roomtype` 房间配置数组结构必须与目标子游戏**逐字节一致**（服务器据此解析规则）；② `deskinfo` 对局快照须可序列化/反序列化以支持 `isbattle==1` 时 `Game_Modify.Reconnect(deskinfo)` 断线重连。
**协议文档索引：** `00-框架架构设计` · `01-传输层与架构` · `02-协议-agent路由` · `03-协议-room路由` · `04-数据结构` · `05-游戏内协议与桥接` · `06-子游戏开发模式与Cocos方案`。改协议相关代码前先读对应篇。
## 客户端侧适配约束：远程配置 / 原生数据接口 / 原生↔H5 桥接（须与原项目逐字一致）
继「服务器零改动」之后的**第二类不可妥协约束**：除 WebSocket 协议外，前端还通过「远程配置文件」与「原生接口」获取大量数据。新 Cocos 前端必须与原项目**逐字一致**地复刻这些读取/互调/注册方式（接口名、数据格式、回调约定、URL 构造），让原生侧与配置服务**零改动**即可对接。三类机制：
1. **远程配置文件读取**：入口 `Game_Config.Debugger.gameserver`（`projects/Game_Surface_3/js/01_SubGame/00_SubGame_Config.js:11`，远程 `.txt` URL + `ifast_random()` 防缓存 + `serverType` 切正式/本地）。读取链：`Logic.setGameServer()`（解析 URL 参数 `gameconfig` 或 `Func.getothername("gameserver")` 覆盖，`12_Logic.js:1259-1281`）→ `get_config(gameserver)`（**引擎层函数**，GET 远程 txt，`12_Logic.js:521`）→ `ServerUrl_Succ(_msg)` 回调（`12_Logic.js:533`）→ `GameData.Server = _msg.data.urlserver`（`12_Logic.js:549`）。**URL 构造、请求方式、回包字段解析须一致。**
2. **原生同步数据接口（注入对象）**：`Func.getothername(name)` → `window.settings.getothername(name)`（`js/00_Surface/05_Func.js:2467-2471`）。`window.settings` 是**原生注入的全局对象**，用于同步取配置（如渠道/包信息/gameserver 覆盖）。
3. **原生↔H5 异步桥 = WebViewJavascriptBridge (WVJB)**（`05_Func.js:2627` 起）：
- 初始化 `setupWebViewJavascriptBridge(callback)`（经 `window.WVJBCallbacks` / `WebViewJavascriptBridgeReady` 事件 / `wvjbscheme://__BRIDGE_LOADED__` iframe）。
- **H5 注册供原生调用**：`bridge.registerHandler("<name>", (data, responseCallback) => {…})`。已注册 handler（名称/数据结构须一致）：`getVideoinfo`、`sharelogin`、`sharesuccess`、`gameui_play_voice`、`gameui_stop_voice`、`getphoneinfo`、`getAddressBook`、`phonestate`、`appservice`、`getaudiourl`、`getBattery`、`getwifiLevel`、`getnetwork`、`shakeEnd` 等（`05_Func.js:2651+`）。
- **H5 调用原生**：`bridge.callHandler("<name>", data, responseCallback)`（WVJB 约定）。
- 覆盖能力：分享、视频、语音录制/播放、电话状态、通讯录、电量/wifi/网络、摇一摇等。
> **Cocos 适配注意**：原项目是 H5（WebView + WVJB + `window.settings` + 引擎 `get_config`）。新 Cocos 前端无论走 WebView 还是原生（jsb），都必须对接**同名 handler、同样的数据结构与回调约定**，并保持远程配置读取流程一致，使**原生侧与配置服务无需改动**即可互通。这套桥接的落地属 sdk/平台层范畴（后续 Plan）。改这部分前先核对上述源码位置，不要臆测接口名或数据格式。
## Cocos Creator 新前端：优先使用 cocos-creator-mcp
新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**（场景、节点、组件、prefab、资源、预览/截图/录制等），都应**优先使用 `cocos-creator-mcp` 这组 MCP 工具**（命名空间 `mcp__cocos-creator-mcp__*`，共 164 个）直接驱动编辑器，而不是手改 `.scene` / `.prefab` / `.meta` 等序列化文件——手改极易破坏 UUID 引用与序列化结构。
**前置条件（缺一不可，否则工具调用必然失败）：**
1. Cocos Creator 3.8+ 已打开 `YouleNexus` 工程；
2. 扩展 `cocos-creator-mcp` 已启用，并在其面板里点了 **Start Server**（监听 `http://127.0.0.1:3000/mcp`）。
**开工前先探活**：先调用 `mcp__cocos-creator-mcp__server_get_status`（或 `curl http://127.0.0.1:3000/health`，期望 `{"status":"ok","tools":164}`）。**连不上时，提示用户在编辑器里启动服务，不要盲目重试**——MCP 桥（`extensions/cocos-creator-mcp/client/stdio-bridge.js`）只转发，无法替你启动编辑器服务。
**工具分类（按前缀）：** `scene_*`（场景生命周期/层级/查询/撤销）、`node_*`（增删改/变换/树）、`component_*`、`prefab_*`、`asset_*`、`project_*`、`builder_*`（预览/构建）、`debug_*`（截图、录制、game command、控制台日志）、`view_*`（gizmo/相机/网格）、`refimage_*`、`preferences_*`、`server_*`。
> MCP 的项目级安装方式与排障细节（扩展位置、`package.json` name 必须为 `cocos-creator-mcp`、镜像 404 等坑）记录在项目记忆 `cocos-creator-mcp-setup`。
Reference in New Issue View Git Blame Copy Permalink