65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# 天鹅绒小丑 · 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)。
|