first commit

README.md

@@ -0,0 +1,64 @@
+# 天鹅绒小丑 · Velvet Joker
+
+一款可在浏览器游玩的单人扑克构筑游戏。使用 TypeScript + PixiJS 8，在 Canvas / WebGL 中绘制与操作卡牌；界面文字和按钮使用 HTML，保障中文清晰和键盘操作。
+
+## 启动
+
+需要 Node.js 22（已验证 22.15.1）。
+
+```sh
+npm ci
+npm run dev
+```
+
+打开终端给出的本地地址。开发服务器默认端口 5173；仅本机访问可使用 `npm run dev -- --host 127.0.0.1`。
+
+```sh
+npm test          # 规则测试 + 16 个固定种子的自然对局检查
+npm run build    # TypeScript 检查与生产构建
+npm run preview  # 预览 dist 构建产物
+```
+
+`dist/` 可部署到静态站点。游戏不需要账号、API 或服务器数据；无外部字体、图片、音频请求。首次页面加载仍需静态服务器，未实现 Service Worker 离线缓存。
+
+## 操作
+
+- 点击卡牌选择，最多 5 张；拖动手牌或小丑调整顺序。
+- `1–8` 选牌，`Enter` 出牌，`D` 弃牌，`Esc` 取消选择或关闭弹窗。
+- 小丑从左向右触发；点击查看效果、调整顺序或出售。
+- 右上角消耗品点击使用；塔罗需先选择目标手牌。右键或长按手牌查看信息。
+- 过关后进入商店，购买、刷新、开包，随后挑战下一盲注。
+- 设置中可调整音效、CRT 效果、结算速度，或输入种子开始新局。
+- 成功操作后自动保存；刷新会恢复已提交状态，不重播奖励。浏览器不同来源/端口的存档彼此独立。
+
+## 首版内容
+
+24 张独立小丑、12 类牌型及行星升级、9 种塔罗、4 类强化和红色蜡封、6 种常规 Boss、1 种终局 Boss、8 Ante / 24 个盲注。支持跳盲奖励、购买出售、开包、利息、胜利失败和本地续局。
+
+规则参考 Balatro 的基础机制，但卡池、美术与部分规则为本作独立设计。具体数值、触发顺序和差异见 [规则文档](docs/rules.md)，不声称完整复刻原作。
+
+## 代码结构
+
+- `src/core/`：纯规则、牌型、计分事件、随机数、事务状态机。
+- `src/content/`：卡牌、牌型和 Boss 内容。
+- `src/app/`：界面、命令协调、结算动画和样式。
+- `src/render/`：PixiJS 牌桌、程序卡面、拖拽与命中检测。
+- `src/platform/`：存档校验与 Web Audio 音效。
+- `tests/`：手算规则用例、自然规则模拟、浏览器交互。
+
+增加小丑需要同时定义内容、计分处理、金样测试，并更新规则文档。动画不可反向修改计分状态。
+
+## 浏览器验证
+
+先启动开发服务器，再运行 `npm run test:browser`。脚本默认使用 macOS 系统 Chrome 的独立临时环境，其他环境可设置 `CHROME_PATH` 指向 Chrome；也可使用安装了 Playwright Chromium 的环境。
+
+测试覆盖真实 Canvas 点击/拖动、出牌/弃牌、刷新恢复、小丑重排、消耗品、商店/卡包和跳盲。测试中的定向 UI 夹具用于覆盖指定分支，不是自然通关证据；自然通关由 `tests/balance.test.ts` 另行验证。截图写入 `artifacts/`。
+
+## 当前边界
+
+- 需要 WebGL；不可用时显示明确提示。桌面横屏优先，手机横屏可玩，竖屏提示旋转。
+- 已验证 Chrome 软件 WebGL 与多个视口；Safari、真实手机触摸和硬件帧率尚未验收。
+- 固定种子贪心玩家能正常胜败，不代表全部流派已经平衡；目前对子成长流更容易形成稳定组合。
+- 不包含完整原作卡池、挑战/解锁系统、云存档和无尽大数模式。
+
+详见 [验收记录](docs/verification.md) 和 [资源来源](docs/assets.md)。