3.5 KiB
3.5 KiB
天鹅绒小丑 · Velvet Joker
一款可在浏览器游玩的单人扑克构筑游戏。使用 TypeScript + PixiJS 8，在 Canvas / WebGL 中绘制与操作卡牌；界面文字和按钮使用 HTML，保障中文清晰和键盘操作。
启动
需要 Node.js 22（已验证 22.15.1）。
npm ci
npm run dev
打开终端给出的本地地址。开发服务器默认端口 5173；仅本机访问可使用 npm run dev -- --host 127.0.0.1。
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 的基础机制，但卡池、美术与部分规则为本作独立设计。具体数值、触发顺序和差异见 规则文档，不声称完整复刻原作。
代码结构
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、真实手机触摸和硬件帧率尚未验收。
- 固定种子贪心玩家能正常胜败，不代表全部流派已经平衡；目前对子成长流更容易形成稳定组合。
- 不包含完整原作卡池、挑战/解锁系统、云存档和无尽大数模式。