Files

T

joywayerandClaude Opus 5 594820d393 初始化仓库：友乐/gameabc 房卡游戏平台脚手架（client + server + docs）

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-07-01 18:13:26 +08:00

8.7 KiB

Raw Blame History

CLAUDE.md

本文件为 Claude Code（claude.ai/code）在本仓库中工作时提供指导。

这是一个什么仓库

一个友乐/gameabc 房卡类小游戏平台：浏览器端由私有的 gameabc.min.js 2D Canvas 引擎驱动，服务端是一个 Node.js 游戏服务器平台（youle 应用），双方通过 WebSocket/HTTP 收发 JSON 包通信。项目根目录没有 package.json、没有 npm 构建/lint/测试流水线、也没有 git 仓库——这是纯静态 JS：客户端靠 <script> 标签加载，服务端靠平台自带的 min_loadJsFile/require 加载。

client/js/01_SubGame/codes/ 和 server/games 目前都是空的——尚未接入任何具体子游戏。本仓库是平台层 + 可复用框架的脚手架，未来第一个子游戏会在此基础上搭建。

常用命令

没有配置任何构建/lint/测试工具。仓库里唯一的脚本：

# 根据 client/assets/spine/*.json 重新生成 client/generated/spine_assets.js 与 spine_data.js
client/scripts/build_spine_data.cmd        # 内部调用 build_spine_data.ps1

在 client/assets/spine/ 增删 Spine 导出文件后运行；不要手改这两个生成文件。

查看客户端效果需用 HTTP 方式（而非 file://）打开 client/index.html，例如 npx http-server client -p 8080。

shared/（共享算法，待子游戏接入后才有）的改动应按两份文档中「§10 测试纪律」的要求跑 Node 单测验证——目前尚未接入测试框架，意味着需要直接用 node 运行相应脚本。

架构

两套独立代码库，一份线上协议

client/ —— 浏览器端，严格 ES5，由 gameabc canvas 引擎驱动。
server/ —— Node.js，严格 ES5，即 youle 游戏平台。
两端交换的 JSON 包结构固定为 { app: "youle", route, rpc, data }：route 决定投递到服务端哪个模块，rpc 决定调用该模块上的哪个方法（mod[pack.rpc](pack)——没有二次 switch(action) 分发，一个操作对应一个 RPC 方法）。服务端把结果告知客户端的唯一可靠方式是主动推送（o_room.method.sendpack_toseat/toother）；DoPack 的返回值并不是真正的下发通道。成败判定只看推送包里的 data.success（布尔值）——绝不用 status/code。

客户端分层（`client/js/`，依赖关系即 `index.html` 里的加载顺序）

js/vendor/                 第三方与引擎（gameabc.min.js、jquery、spine-canvas）—— 禁止修改
js/00_Surface/              平台代码 —— 禁止修改
js/gameabc-framework/       可复用、游戏中立的框架（见下）—— 禁止渗入任何具体玩法的逻辑
  core/   GameABCUtils（唯一允许直接调用 gameabc/引擎原生 API 的模块）、SpriteManager（做 ID 校验的业务级精灵 API）
  system/ EventBus（空的 Events{} 容器——具体玩法事件由子游戏自行追加，框架不预置）、SpriteEventController、SpriteGestureRecognizer、AnimationManager、AudioManager
  ui/     BaseComponent、UIManager、SpriteCopyUtils、DynamicSpriteList、RecordView（及其默认配置）、AlignmentUtils
  spine/  SpineMgr —— 必须在 gameabc.min.js 之后、gamemain.js/gameenddraw 被（重新）定义之前加载
  network/RpcHelper —— 自动给外发请求注入平台字段（agentid/gameid/playerid/roomcode/seat）
  templates/  *.template.js —— 供新子游戏「复制填充」的起点模板；不会被 index.html 直接引用
js/01_SubGame/
  00_SubGame_Config.js / 01_SubGame_modify.js / 02_SubGame_Input.js   固定的平台契约文件（见下）
  codes/     子游戏自己的代码（尚未创建）；codes/shared/ 将是 server/<游戏>/shared/ 的只读同步副本

依赖方向严格单向：01_SubGame/codes → gameabc-framework → gameabc.min.js。框架不反向依赖任何子游戏。index.html 里的加载顺序就是依赖关系图——新增文件必须插在其依赖之后、使用者之前，否则运行时会拿到 undefined（这里没有模块系统）。

可编辑范围：

路径	规则
`js/vendor/`、`js/00_Surface/`	禁止修改
`01_SubGame/00_SubGame_Config.js`	仅可改已有 `Game_Config.*` 配置项的值——禁止新增/删除/改名/改结构
`01_SubGame/01_SubGame_modify.js`	仅可填顶部「配置区」（`Type_1/Type_2/CreateRoomData/combat/game_config/roomDes`）；转发壳部分不碰
`01_SubGame/02_SubGame_Input.js`	完全不碰
`js/gameabc-framework/`	可改，但须保持游戏中立（不含具体玩法常量/逻辑）
`01_SubGame/codes/`（除 `shared/`）	子游戏自由开发区
`01_SubGame/codes/shared/`	服务端 `shared/` 的只读同步副本；改服务端一侧后再同步

子游戏有两种接入方式（见 docs/client/development-guide/06）：内联模式（旧——业务逻辑直接写进三个契约文件）或 Hooks 外置模式（新——三个契约文件退化为纯转发壳，查 SubGameHooks.X 并委托；子游戏逻辑全部放在 codes/SubGameHooks.js + codes/）。每个子游戏二选一，不能混用；Hooks 外置模式的模板位于 gameabc-framework/templates/subgame-entry/。

服务端分层（`server/`）

server/packet.js、applist.js             顶层收包入口 / 应用注册表 —— 禁止修改
server/class/class.app.js|class.mod.js   三层路由：app（按 pack.app）→ mod（按 pack.route）→ method（按 pack.rpc）
server/youle/                            "youle" 应用
  server_room/class.room.js              o_room（seatlist[]、sendpack_toseat/toother）
  server_room/class.player.js            o_player（每座位一个，持有用于定向发包的 conmode/fromid）
  server_room/class.export.js|import.js  平台自身的 export/import 服务（check_player、deduct_roomcard、save_grade……）
server/<游戏容器目录>/<游戏>/             ← 子游戏接入后**唯一**可编辑的区域（目录名并非框架强制固定；"games2" 只是早期的一种约定）
  mod.js       创建模块（cls_mod.new(modname, routename, youle_app)），按依赖顺序加载文件，把 RPC 方法定义为「提参 → 委托给 handler」的薄入口
  export.js    平台按需回调的可选接口（get_needroomcard、get_asetcount、makewar、get_deskinfo、get_disbandRoom、player_enter/leave……）
  import.js    对平台 4 个服务的薄封装：check_player、deduct_roomcard、save_grade、finish_gametask

每个房间的状态挂在 o_room.o_desk.data.* 上（在 export.makewar 内创建，且必须建立 o_room.o_desk ⇄ o_desk.o_room 双向引用）。对局状态禁止用模块级单例/全局变量存放——服务端在同一进程内并发跑多个房间；缓存/定时器/决策表必须以 房间 + seat 为 key（而非仅 seat），并在小局结束/解散/开新局时清理干净。

服务端代替玩家执行的「自动」操作（AI 托管、超时等）必须走与真人操作完全相同的 handler → 广播链路，这样客户端永远不需要为它们单开一套解析分支。

文档（改动前先读）

docs/client/development-guide/与docs/server/development-guide/（按 01→05/04 编号）是本项目遵循的权威、项目专属开发指南——改哪块就读对应编号的文档，而不是从代码反推约定。docs/games/engineering/ 是位于两者之上的、与平台无关的工程方法论层（单一权威数据源 SSOT、单向依赖、职责单一、对扩展开放对修改封闭 OCP、配置优先于硬编码、显式失败优于隐式兜底）。

注意：server/docs/development-guide/ 是 docs/server/development-guide/ 的旧版、部分过期的副本（例如它仍写死可编辑目录为 games2/，而新版已改为「容器目录名不再框架强制」）。两者冲突时以 docs/server/development-guide/ 为准。

两套文档中反复强调的硬性规则（文档记载均对应过真实事故）：

全面严格 ES5（var/function，继承用 Object.create；禁止 let/const/箭头函数/模板字符串/class/解构/Promise）。
服务端 require 只能写在文件开头的守卫块内（if (typeof require !== 'undefined') { var X = require(...); }）——禁止在函数体内中途 require；两个运行时之后统一按同一个全局名引用。
成败判定只看推送包上的 data.success——绝不用 status/code，也不能写两者都判的兼容兜底。
对影响发牌/庄家/手牌/计分/重连的权威数据，禁止用默认值掩盖缺失（|| 0、|| []、|| ''）——应直接显式报错；默认值仅允许用于纯展示/日志字段。
一个职能只在一个模块实现——需要该能力时调用其所属模块，而不是在别处重新实现一份。

8.7 KiB Raw Blame History Unescape Escape