youle_cocos/CLAUDE.md

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）的目标，就是在不改服务器的前提下复刻该协议契约、实现联调兼容。

第二准则：数据源权威、唯一，下游不兜底

每一类数据只能有一个权威且唯一的来源（single source of truth）；下游消费方不得猜测、修补、兜底。

• 唯一来源：同一份配置/数据（如服务器地址、渠道身份、协议常量）只在一个地方定义，其它地方一律引用，不得各处复制或并存第二份。
• 下游零兜底：消费方拿到的数据缺失或非法时，直接显式报错/抛出，把问题暴露到来源，不得用默认值「猜一个」、不得静默 ?? 兜底值、不得 try/catch 后塞个 fallback 蒙混。错误要早暴露、可定位，而不是被下游悄悄掩盖。
• 配置即契约：来源（如 profiles.ts 的服务器地址）必须把该提供的字段显式提供齐全；缺了就是配置错误，应在来源处修正，而不是让下游补。
• 例外只有一种：来源本身明确定义了「可选 + 缺省语义」，且该缺省写在来源处（而非散落在各下游）。

这条与「服务器零改动」并列：前者保边界契约不变，后者保内部数据流可信、单源、可追溯。新增/修改任何带默认值、回退、容错分支的代码前，先问：这是不是在替上游兜底？若是，改为在来源处修正 + 在下游暴露。

仓库总览

这是友乐（Youle）棋牌游戏平台的前端工作区，核心是「一套前端模板 + 多个子游戏」的架构，并正在迁移到 Cocos Creator。三个顶层目录：

• projects/ —— 旧版 HTML5 前端。projects/Game_Surface_3 是前端模板（平台外壳），也是新前端 UI 迁移的原工程（迁移源）；其余目录都是基于该模板扩展出来的子游戏，平台层几乎不动，只改子游戏层 + 美术数据。分层结构与关键文件见 projects/CLAUDE.md。
• docs/protocol/ —— 前端模板框架与服务器收发包的协议规范（权威文档，8 篇）。改动任何网络层代码前必须先读对应章节，服务器不可改，前端必须严格对齐协议。
• cocoscreator_projects/YouleNexus/ —— 新的 Cocos Creator 3.8+ 前端工程，目标是按 docs/protocol 复刻协议契约，做到服务器零改动即可联调。

原工程 Game_Surface_3 → YouleNexus 的 UI 迁移

YouleNexus 的 UI 资源（assets/framework/ui/prefabs/）从原工程 projects/Game_Surface_3 逐层复刻。数据契约与流程规范：

• 数据模型（权威）：docs/superpowers/specs/原工程数据模型.md；迁移流程：docs/superpowers/specs/UI-手工迁移规范.md（9 步 funplay MCP + 8 项验证清单）。
• 已完成的参照真相源：assets/framework/ui/prefabs/Login_Layer.prefab（Layer 2）。

⚠️ 索引与类型（易踩坑，实测修正）：源数据索引直接按 ID——gameabc_Object.json 的 ObjectList[ObjectID]、gameabc_Image.json 的 ImageFileList[ImageFileID]（不是 ID - 1，旧文档的 off-by-one 是错的）；组件类型看 ObjectType（2=Sprite、4=Text），不是 XML 的 SpiritType（那是另一套枚举）。

网络协议（docs/protocol/，新旧前端共同契约）

docs/protocol/ 是权威文档，改任何网络层代码前先读对应章节，不要凭本文件的转述臆测。

两个不可妥协的约束： ① roomtype 房间配置数组结构必须与目标子游戏逐字节一致（服务器据此解析规则）；② deskinfo 对局快照须可序列化/反序列化以支持 isbattle==1 时 Game_Modify.Reconnect(deskinfo) 断线重连。

客户端侧适配约束：远程配置 / 原生数据接口 / 原生↔H5 桥接

继「服务器零改动」之后的第二类不可妥协约束：除 WebSocket 协议外，前端还通过「远程配置文件」（gameserver → urlserver）与「原生接口」（window.settings 同步取值、WVJB 异步桥）获取大量数据。新 Cocos 前端必须与原项目逐字一致地复刻这些读取/互调/注册方式（接口名、数据格式、回调约定、URL 构造），让原生侧与配置服务零改动即可对接。

具体机制、handler 清单与源码位置见 native-bridge-contract 技能（.claude/skills/native-bridge-contract/SKILL.md）——改这部分前先读它核对，不要臆测接口名或数据格式。

Cocos Creator 新前端：优先使用 funplay-cocos-mcp

新工程 cocoscreator_projects/YouleNexus。任何涉及该工程的编辑器操作（场景、节点、组件、prefab、资源、动画、预览/截图等），都必须走 mcp__funplay_cocos__* 这组 MCP 工具驱动编辑器。

绝不允许手改 .scene / .prefab / .anim / .meta——它们是 UUID 引用的序列化资源，任何文本编辑都会破坏引用结构，导致「资源导入失败」且只能人工恢复。MCP 连不上时也不例外：应提示用户去编辑器启动服务，而不是退而求其次去手改文件。

具体工具用法不写在这里——MCP server 连上后会自注入完整说明（工具清单、action 速查、批量操作），以其为准，正常操作不需要先读任何仓库文档。

cocos-mcp 技能（.claude/skills/cocos-mcp/SKILL.md）只记录 MCP 自己给不了的部分：前置条件、探活、排障、已知坑。工具正常时不必读它；一旦 cocos_* 工具没出现、调用报连接失败、或行为与预期不符，就去读。