AI 驱动的现代化桌游平台，专注于桌游教学与联机对战

支持多人实时对战、本地同屏、交互式教学，提供完整的大厅、社交、创作工具与管理后台。

在线体验：easyboardgame.top

• ✨ 特性
• 🏗️ 技术栈
• 📦 项目结构
• 🚀 快速开始
• 🎮 添加新游戏
• 🐳 Docker 部署
• 🛠️ 常用命令
• 🧪 测试
• 📄 文档
• 🤝 贡献
• 📜 许可证
• 💖 赞助

• 多人实时对战 — 基于自研游戏框架 + Socket.IO，功能有房间创建/加入/观战/重赛/日志/撤回，内置乐观更新引擎实现低延迟操作体验
• 丰富的游戏库 — 召唤之战 (Summoner Wars)、王权骰铸（Dice Throne / dicethrone / 王权）、Smash Up、井字棋等
• 本地同屏模式 — 同一设备上和朋友面对面对战
• 交互式教程 — 内置 Tutorial 引擎，支持 AI 自动演示和分步引导
• 社交系统 — 好友、聊天、对局邀请、战绩查看
• 游戏工具 — 预览特效与音频，快速切图等，音频来自购买的素材包
• 简易原型工具（搁置） — 可视化游戏原型构建器，快速验证规则想法
• 国际化 (i18n) — 中英双语支持
• 管理后台 — 用户管理、房间监控、反馈处理、系统健康检查
• Docker 一键部署 — 同域 / Cloudflare Pages 分离部署均可

前端：React 19 · TypeScript · Vite · Tailwind CSS · Framer Motion · Three.js · React Router · TanStack Query · i18next

后端：自研游戏引擎 (Koa + Socket.IO) · NestJS · MongoDB · Redis · Winston (日志系统)

基础设施：Docker · Docker Compose · GitHub Actions CI/CD · Cloudflare Pages / R2

├── src/
│   ├── games/           # 游戏实现（每个游戏一个目录）
│   ├── engine/          # 引擎层（Undo / Flow / Prompt / Tutorial / EventStream / Transport 等系统）
│   ├── components/      # UI 组件（大厅 / 对局 / 社交 / 管理后台）
│   ├── contexts/        # React Context（Auth / Audio / Social / Modal 等）
│   ├── services/        # Socket 服务（lobby / match / social）
│   ├── ugc/             # 简易原型构建工具与运行时
│   └── server/          # 服务端共享模块（DB / 存储 / 模型）
├── server/              # 服务端基础设施
│   ├── logger.ts        # Winston 日志系统
│   └── middleware/      # Koa 中间件（日志 / 错误处理）
├── logs/                # 日志文件目录（自动轮转）
├── apps/api/            # NestJS API 服务（认证 / 管理 / 社交）
├── server.ts            # 游戏服务器入口（Koa + GameTransportServer）
├── docker/              # Dockerfile 与 Nginx 配置
├── scripts/             # 构建 / 部署 / 资源处理脚本
├── docs/                # 项目文档
│   └── logging-system.md  # 日志系统文档
└── e2e/                 # Playwright 端到端测试

• Node.js >= 18
• Git
• Docker（可选，用于 MongoDB）

# 克隆仓库
git clone https://github.com/zhuanggenhua/BoardGame.git
cd BoardGame

# 安装依赖
npm install

# 复制环境变量模板
cp .env.example .env

Windows 用户：将 cp 替换为 copy。

npm run dev

npm run dev 会先尝试拉起本地 mongodb 容器；如果当前 shell 没有显式配置 MONGO_URI，且检测到 127.0.0.1:27017 有可用本地 Mongo，则会自动注入开发默认值 mongodb://127.0.0.1:27017/boardgame。

无需安装 Docker 和 MongoDB。该模式会让游戏服退回纯内存存储，并跳过 API 启动；重启后数据会丢失。 该模式会自动跳过排行榜归档、UGC 动态注册等依赖游戏服持久化存储的能力；认证、社交、管理后台等依赖 API 的能力在该模式下不可用。

npm run dev:lite

启动后访问 http://localhost:5173 即可。

如果你完全不会编程，可以先把下面这段话直接复制给 AI：

请先阅读 `https://github.com/zhuanggenhua/BoardGame` 这个仓库里的 `README.md`、`AGENTS.md` 和你认为必要的项目文档，然后一步一步告诉我怎样在本地启动这个项目并成功打开页面。

这个仓库自带 Figma MCP 接入脚本，仓库内脚本和文档才是协作者接入的真相源；CODEX_HOME / D:\codex-home 里只保存每位协作者自己的 Codex 配置和 OAuth 凭据。

如果你要让 Codex / OpenClaw 在这个项目里直接读写 Figma，优先在仓库内运行下面的项目命令：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/infra/setup-figma-mcp.ps1

npm run setup:figma:mcp

npm run setup:figma:mcp:window

如果是首次授权、凭据失效，或者你明确想重新走一次网页登录，再使用下面命令：

npm run setup:figma:mcp:login

npm run setup:figma:mcp:window:login

这个脚本会：

• 自动定位当前协作者自己的 CODEX_HOME（优先 CODEX_HOME，其次 D:\codex-home，最后 %USERPROFILE%\.codex）
• 把 mcp_oauth_credentials_store 固定成 file，避免网页登录成功但新会话吃不到登录态
• 往对应的 config.toml 里补 mcp_servers.figma
• 打开 rmcp_client
• 默认不重复触发网页登录；已有文件态 OAuth 凭据会被后续新会话复用
• 只有追加 -Login 或使用 setup:figma:mcp:login / setup:figma:mcp:window:login 时，才会调用 codex mcp login figma
• 协作者只需要在浏览器里完成网页登录授权，不再手填 FIGMA_OAUTH_TOKEN

执行完成后需要重启 Codex / OpenClaw 会话，当前会话不会自动出现 Figma 工具。

更完整的协作者接入说明见 docs/infra/figma-mcp.md。

开发环境只需复制 .env.example 即可运行。核心变量：

完整说明见 .env.example。

项目内置了完整的 AI 辅助创建工作流，分 6 个阶段逐步完成（骨架 → 类型 → 领域逻辑 → 系统组装 → UI → 收尾）。

使用支持 Skill 的 AI 编辑器（或者直接扔文档），调用 .codex/skill/create-new-game 技能即可开始，AI 会引导你完成全部流程……大概。

数据录入使用的截图工具推荐pixpin

可以开新分支提pr，我会用ai审核

docker compose up -d
# 访问 http://localhost:3000

服务器上只需 Docker，无需克隆仓库。脚本会自动下载 compose 文件、引导配置环境变量、拉取镜像并启动：

# 下载部署脚本并执行（首次部署会进入交互式配置向导）
curl -fsSL https://raw.githubusercontent.com/zhuanggenhua/BoardGame/main/scripts/deploy/deploy-image.sh -o deploy.sh
bash deploy.sh

# 后续更新
bash deploy.sh update

# 手动回滚到上次成功部署版本
bash deploy.sh rollback-last

# 拉取慢时，先单独拉镜像再 update（避免 compose pull 并发抢带宽）
docker pull ghcr.io/zhuanggenhua/boardgame-game:latest
docker pull ghcr.io/zhuanggenhua/boardgame-web:latest
bash deploy.sh update

前置要求：服务器已安装 Docker 和 Docker Compose（docker compose 命令可用）。

详细部署文档见 docs/deploy.md。

npm run dev                # 启动完整开发环境
npm run dev:lite           # 启动纯内存快速体验模式
npm run build              # 构建前端
npm run generate:manifests # 重新生成游戏清单
npm run generate:locales   # 生成卡牌多语言文件
npm run compress:images    # 压缩图片资源
npm run compress:audio     # 压缩音频资源（wav → ogg）
npm run assets:manifest    # 生成资源清单
npm run check:arch         # 架构检查

# 音频注册表 & 资源上传（新增/修改音频文件后必须执行）
node scripts/audio/generate_common_audio_registry.js  # 重新生成音频注册表
npm run assets:download  # 从 R2 下载资源到本地（合作者 clone 后首次运行）
npm run assets:upload    # 上传压缩资源到 R2（需配置 R2_* 环境变量）
npm run setup:figma:mcp  # 给当前协作者补 Codex/OpenClaw 的 Figma MCP 配置
npm run setup:figma:mcp:login # 首次授权或凭据失效时重新走一次网页登录
npm run setup:figma:mcp:window # 打开独立终端执行仓库内 Figma MCP 接入脚本
npm run setup:figma:mcp:window:login # 打开独立终端并继续 Figma OAuth 登录

git push --no-verify

注意：新增或修改音频文件后，需要依次执行 compress:audio → generate_common_audio_registry.js → assets:upload，否则远程 registry.json 缺少新 key 会导致音频无法播放。

• Vitest 单元测试 — 游戏领域逻辑、引擎系统、API 服务等（2500+ 测试用例，99.4% 通过率）
• GameTestRunner — 游戏领域专用测试运行器，输入命令序列 → 执行 pipeline → 断言最终状态
• Playwright E2E — 端到端集成测试

# 运行所有单元测试
npm test

# 运行特定游戏的测试
npm run test:summonerwars
npm run test:smashup
npm run test:dicethrone

# 运行 E2E 测试
npm run test:e2e

详见 自动化测试文档。

• 架构可视化 — 动画 SVG，一图看懂整体架构与管线流程
• 架构设计文档 — 完整技术架构说明
• 部署指南 — 同域 / Pages 分离 / 镜像部署完整说明
• 前端框架 — 游戏 UI 框架与组件约定
• 后端框架 — API 与游戏服务架构
• API 文档 — 认证、社交、管理等接口说明
• 原型构建器 — 简易游戏原型工具
• 自动化测试 — 测试策略与实践

欢迎提交 Issue 和 Pull Request！

默认协作方式是 先 clone 主仓库，再在本地开分支。这样更适合多人和 AI 共同开发，也更不容易出现 fork 长期漂移、权限判断混乱、PR head 不可写等问题。只有在你没有主仓库写权限，或者明确需要账号/权限隔离时，才建议改走 fork 路线。

1. Clone 主仓库：git clone https://github.com/zhuanggenhua/BoardGame.git
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m "用中文准确描述改动"
4. 有主仓库写权限时直接推送：git push origin feature/amazing-feature
5. 没有写权限时，再 fork 到自己账号，改推送到 fork 后提 Pull Request

本项目代码基于 MIT License 开源。

游戏图片素材来自对应桌游的官方图包和民间汉化，版权归原作者所有，仅供学习交流使用，不可商用。

如果喜欢这个项目，可以请作者喝杯咖啡。如需要，可以备注加入到赞助列表。