# 桌游大厅 · Boardgame Hall

**今晚，再来一局。** 一个运行在浏览器里的像素风桌游大厅：坐下、发牌，与本地 AI 对手过招，结束后留下一张战绩小票。

**介绍网页已上线**：[中文](https://boardgame-hall-website.pages.dev/?lang=zh) · [English](https://boardgame-hall-website.pages.dev/?lang=en) · [网页仓库](https://github.com/smartlotus/boardgame-hall-website)。游戏源码的许可待确认项与候选状态仍见下文。

![桌游大厅实机画面](website/images/hall.png)

项目使用 **Phaser 3.80.1、原生 JavaScript 与 JSON 配置**。对局 AI 是本地规则与策略程序，游玩不需要模型 API、账号或后端。当前版本为 **0.1.0，开发预览版**，优先支持桌面浏览器。

## 快速开始

需要 Python 3.10+；开发验证另需 Node.js 24+。游戏运行不需要安装 npm 依赖，Phaser 已附在 `vendor/`。

在项目根目录执行：

```bash
python -m http.server 8777 --bind 127.0.0.1
```

- 游戏：[http://127.0.0.1:8777/index.html](http://127.0.0.1:8777/index.html)
- 介绍网页：[http://127.0.0.1:8777/website/](http://127.0.0.1:8777/website/)

也可以运行 `npm run dev`。必须通过 HTTP 服务访问，直接双击 HTML 无法正确加载模块与配置。断网前已取得完整项目时，可使用附带的 Phaser 文件离线游玩。

## 今晚开哪些桌

人数表示桌上全部座位，包含你和 AI，不表示在线多人联机。

| 桌游 | 座位 | 状态 |
|---|---|---|
| UNO | 2–10 | 已接入大厅 |
| 璀璨宝石 / Splendor | 2–4 | 已接入；组件数值表来源许可待确认 |
| 马戏星探 / SCOUT | 3–5 | 已接入大厅 |
| 情书 / Love Letter | 2–4 | 已接入大厅 |
| 斋浦尔 / Jaipur | 2 | 已接入大厅 |
| 失落之城 / Lost Cities | 2 | 已接入大厅 |
| 寿司猫 / Sushi Go | 2–5 | 已接入大厅 |
| 爆炸猫 / Exploding Kittens | 2–5 | 已接入大厅 |
| 须臾 | 6 | 剧本杀框架保留；公开包未附商业剧本数据，入口关闭 |
| 德国心脏病 / Halli Galli | — | 本地内核开发中，未进入公开包 |

八款桌游支持初级、中级、高级 AI 档位，并已接入练习 / 正式桌。练习桌提供讲解、悔棋和代走；正式桌记录战绩。留座、续玩和小票使用浏览器本地存储；清理站点数据或切换浏览器不会保留这些记录。

实现细节与已知限制见 [项目说明](docs/PROJECT.md)、[当前状态](docs/STATUS.md)。本项目不是相关桌游品牌的官方产品；名称仅用于说明规则实现。

## 文件分类

```text
index.html              游戏入口
project.json            分辨率、帧率与初始 scene
engine/                 VibeGame 运行层，基于 Phaser 3
scripts/                大厅、各桌规则内核、AI、布局与 surface
scenes/                 初始 node 树与入口配置
config/                 桌单、输入、讲解、等待时长
assets/                 manifest 与程序自绘卡牌、头像
vendor/                 Phaser 本地副本及原始许可
modules/                运行层附带的复用模块
tests/                  验证代码
tools/                  候选包导出与公开验证工具
website/                项目介绍网页（独立入口）
docs/                   架构、状态与开源发布说明
```

开发工作区还保留 `.vibegame/`、`.agents/`、`gates/`、`runs/` 等内部过程资料；开源候选包不包含这些目录。候选包保留原源码路径，便于继续开发。

## 验证

公开候选包：

```bash
npm run check
npm test
```

前者校验资源与发布边界；后者运行八款桌游的精选规则、视野和布局判据。冻结候选包的文件哈希另用 `node tools/check_public.mjs --verify-manifest` 验真。它们不是完整走桌验收。

原始开发工作区：

```bash
node gates/nano_gate.mjs --no-browser
node tools/test_public.mjs
python scripts/pipeline_state.py --with-suite
```

真实浏览器冒烟另需 `playwright` 与 Chromium：

```bash
python -m pip install playwright
python -m playwright install chromium
# 先在另一终端启动 8777 静态服务
node gates/nano_gate.mjs
```

浏览器工具是开发依赖，不是玩家运行依赖。完整内部套件还依赖未公开的剧本数据、取证资料等，不能在候选包中声称全量可运行。

## 本地准备开源包

仅适用于原始开发工作区：

```bash
npm run release:plan       # 查看分类白名单
npm run release:prepare    # 生成新目录和 ZIP
```

产物在 `dist/open-source-<时间戳>/`，包含按类别列出的 `RELEASE_MANIFEST.json` 与每个文件的 SHA-256。该流程不初始化 Git、不提交、不推送。首次公开仓库应从候选目录开始，避免带入开发仓库历史。详见 [发布说明](docs/RELEASE.md)。

## 贡献与许可

欢迎报告问题、改善交互和补充有证据的规则验证，参见 [贡献指南](CONTRIBUTING.md)。安全问题按 [安全说明](SECURITY.md) 私下报告。

候选包附 GitHub 问题模板与 CI 配置。上传后 CI 会检查资源与精选规则测试；不会自动部署或发布。

本项目可授权的代码、文档与自绘资源采用 [MIT](LICENSE)。第三方版权与尚待确认的来源项见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)；根 MIT 许可不能替代这些组件的上游许可。当前候选包尚未公开，发布前需确认 VibeGame 来源许可与璀璨宝石组件数值表的分发条件。