first commit

docs/implementation-plan.md

@@ -0,0 +1,130 @@
+# Web 小丑牌实现方案
+
+日期：2026-09-21。状态：用户已授权，首版已实现。实际规则及范围以 rules.md 为准，验收情况见 verification.md。
+
+## 1. 产品目标与取舍
+
+实现可在浏览器直接游玩的单人扑克构筑游戏。重点是构筑选择、计分链与完整对局，其次是贴近参考图的复古牌桌体验。第一版使用中文，桌面横屏优先，兼容平板及手机横屏；离线本地对局，无账号和服务器依赖。
+
+推荐 TypeScript + Vite + PixiJS 8，使用 HTML Canvas 承载 WebGL 渲染。Canvas 是呈现载体，不限定必须使用 Canvas 2D API。锁定实际安装的小版本；第一版不依赖实验性 Canvas 2D 回退或 WebGPU。
+
+Cocos Creator 可以发布 Web，也适合后续小游戏平台，但目前没有现成场景、Prefab 或跨平台交付需求。此阶段增加编辑器、资源导入和构建链的收益有限。若确认主要目标变成微信/抖音小游戏，再选择 Cocos；独立规则模块可以复用，表现层仍需重做。
+
+不把完整原作内容量作为第一版承诺。规则采用可追踪的 Balatro 基础规则参考，牌面和音效制作独立资产。第一版限制卡池，但包含通关、失败和存档，不停留在可点卡牌的展示页。
+
+## 2. 图片观察与视觉方案
+
+参考图约为 16:9。左侧约四分之一为状态栏，右侧是大面积绿色牌桌；上方放小丑，下方是手牌，中部留给出牌、提示和计分。右上是消耗品，右下是牌堆。
+
+- 深墨绿底色与缓慢流动的同色纹理，低对比，不抢牌面。
+- 深灰状态板、偏暖白纸牌、蓝色筹码与红色倍率；金黄用于金钱和奖励。
+- 卡牌有粗边、轻微歪斜、短硬阴影、像素插画和扇形重叠，像桌上的实体纸牌。
+- 英文数字可用像素字体；中文优先保证辨认，使用许可明确的点阵风格字体，避免极细字形。
+- 微弱扫描线、暗角、少量色差作为可关闭的全屏效果。正文和点数保持清晰，不照搬截图的模糊感。
+- 悬停轻抬与倾斜、选中上移、出牌滑向中央、逐张触发弹跳、倍率脉冲、过关盖章。
+- 点击、发牌、加筹码、加倍率、乘倍率使用不同短音效；触发链越长，音高与节奏有递进。
+
+设计坐标建议 1440×810，按窗口等比布局并重新分配边距，不拉伸卡牌。小屏横屏收紧状态栏；竖屏先提供明确横屏提示。鼠标悬停信息在触屏改为长按；拖拽设置阈值，避免选牌误触。键盘可选牌、出牌、弃牌和取消选择。
+
+美术交付先做一套完整牌桌、扑克花色和人头牌，再制作首批独立小丑插画及牌背。不能仅用 emoji 或文字方框替代最终卡面。最终资源统一调色板、描边和像素密度。
+
+## 3. 核心玩法理解
+
+基本循环：选择盲注 → 抽牌 → 选 1–5 张出牌或弃牌 → 按顺序触发效果并累计分数 → 达标结算或次数耗尽失败 → 商店构筑 → 下一盲注。
+
+每个 Ante 包含小盲、大盲、Boss；传统通关目标为 Ante 8 的最终 Boss。Boss 改变局内约束，小丑改变计分、经济或规则，塔罗修改牌组。这些主结构由官方 FAQ 确认。[S1]
+
+核心公式是最终筹码乘最终倍率，但不能把所有增益先求和再相乘。社区触发指南明确区分 Boss / 出牌前效果、逐张计分牌、留手效果、小丑独立效果等阶段；同阶段的顺序也是策略的一部分。[S2]
+
+实现要区分四个概念：选出的牌、判定的主要牌型、牌型包含关系、真正参与计分的牌。例如“包含对子”的效果不应只在最终牌型名称恰好为对子时生效。
+
+牌型引擎覆盖高牌、对子、两对、三条、顺子、同花、葫芦、四条、同花顺，以及改牌后可出现的五条、同花葫芦、同花五条。皇家同花顺作为同花顺的展示变体，不独立建升级账本。牌型优先级不随升级后的潜在分数改变。[S3]
+
+图片中的 6/6 小丑和 10/10 手牌是局内状态，来源无法仅靠图片确定。第一版拟采用基础配置：52 张牌、8 张手牌、4 次出牌、3 次弃牌、5 个小丑槽、2 个消耗品槽；这些值在规则冻结阶段逐项核实，统一配置，不散落在 UI 内。
+
+## 4. 首版内容边界
+
+以下数量是项目范围建议，不声称是原作内容清单。
+
+| 系统 | 第一版目标 | 后续扩展 |
+| --- | --- | --- |
+| 对局 | 1 个基础牌组、1 个难度、8 个 Ante | 多牌组、多难度、无尽 |
+| 扑克牌 | 52 张初始牌、复制/删除/改点数与花色 | 更多特殊牌规则 |
+| 牌型 | 12 类计分与升级，皇家同花顺展示变体 | 特殊小丑改变判型 |
+| 小丑 | 24 张，覆盖筹码、加倍率、乘倍率、条件、成长、经济、重触发 | 复制效果、复杂规则改写 |
+| Boss | 6 种常规机制、1 种终局机制；重复抽取规则明确 | 完整 Boss 池 |
+| 消耗品 | 对应牌型的行星、9 种塔罗（新增女皇投放多倍强化） | 幻灵与更多塔罗 |
+| 卡牌修饰 | 奖励、多倍、玻璃、钢铁及红色蜡封等分阶段落地 | 全部版本、蜡封与贴纸 |
+| 商店 | 购买/出售/刷新、小丑与消耗品、基础补充包 | 更多优惠券与包型 |
+| 跳盲 | 基础跳过与有限标签池，Boss 不可跳过 | 完整标签池 |
+| 持久化 | 新开局、续局、设置、种子与规则版本 | 收集解锁、成就、挑战 |
+
+24 张小丑必须支持至少四类有不同决策的构筑，例如对子成长、花色逐张触发、留手钢铁、经济转化。不是把同一加分效果复制 24 次。
+
+## 5. 规则与状态架构
+
+依赖方向：内容与纯规则 → 应用协调 → 渲染和浏览器适配。引擎输出状态与事件，渲染不得反向拥有规则。
+
+核心模块：
+- `HandEvaluator`：主要牌型、包含关系、计分牌集合；支持 A 的低位顺子与高位顺子，拒绝跨首尾非法顺子。
+- `ScoringEngine`：按明确阶段计算；返回最终值及逐步 ScoreTrace。
+- `EffectRegistry`：有类型的效果处理器，声明触发阶段、条件、顺序与可重触发性；不建设不必要的通用脚本语言。
+- `RunState`：牌组实例、盲注、回合次数、金钱、槽位、牌型等级与历史。
+- `ShopEngine`：商品池、权重、价格、刷新、购买与出售的原子更新。
+- `SeededRng`：抽牌、商店、概率效果分别使用可保存的随机流。
+- `SaveCodec`：版本号、规则版本、种子、随机状态、内容 ID 和实例状态；损坏存档有明确恢复提示。
+
+流程状态：主菜单 → 盲注选择 → 发牌 → 等待操作 → 计分 → 达标结算 / 继续抽牌 / 失败 → 商店 → 下一盲注；最终 Boss 后进入胜利页。
+
+以 `dispatch(command, state)` 的事务边界验证操作。计分时禁止重复出牌和不合法重排；结算奖励只发一次。动画使用引擎结果播放，快进、后台恢复和刷新不改变得分。
+
+计分事件包含阶段、来源实例、目标、操作类型、前值与后值；例如“某张红桃触发 +3 Mult”。同一份事件支持动画、对局日志和测试诊断。
+
+保留三个顺序：出牌顺序、留手顺序、小丑顺序；排序按钮不应无意改变已确认的计分事务。重触发不是递归调用整轮结算，不可重复触发出牌次数或回合奖励。
+
+随机预览不消耗真实 RNG，也不承诺随机效果的确切最终分数；默认只显示牌型、基础筹码/倍率和确定触发条件。
+
+分数运算集中封装，明确乘数、小数和最终取整规则，规则冻结时核对；不使用 32 位位运算储存得分。首版限制到正常 8 Ante 范围，无尽大数另行设计。
+
+## 6. 规则研究交付
+
+在编码前补齐 `docs/rules.md`，每条规则记录来源、适用版本、输入例子、预期输出、核实状态与本项目差异。
+
+优先核实：牌型基础值和每级增长、包含关系、默认资源、盲注目标曲线、Boss 倍率及抽取条件、奖励/利息/刷新/卖价、补充包选择流程、弃牌补牌与牌库耗尽、失效牌与修饰牌交互、触发及取整顺序。
+
+官方 FAQ 只足以确认主循环；社区资料提供细节但并非官方规范。本次部分 Wiki 页面正文抓取失败，搜索摘要不能替代全部边界验证。已找到的资料不等于已完成全量原作复刻研究。对争议交互采用可重复对局证据；无法核实的内容先不进入首版卡池。
+
+## 7. 分阶段实施与退出条件
+
+| 阶段 | 交付物 | 进入下一阶段的条件 |
+| --- | --- | --- |
+| A 规则冻结 | 规则表、24 张小丑候选效果清单、固定计分用例 | 首版每个效果均有触发阶段与预期例子 |
+| B 纯逻辑 | 牌型、抽弃牌、计分、Boss、商店和对局状态机 | 无界面可运行固定种子流程；计分及状态边界通过 |
+| C 纵向切片 | 1 个 Ante、约 6 张代表性小丑、商店、牌桌和音效 | 从开局到 Boss 的真实循环可玩，可看懂每次加分 |
+| D 完整首版 | 8 Ante、完整首批卡池、消耗品、跳盲、存档 | 至少可复现一局胜利和一局失败，恢复进度正确 |
+| E 打磨验收 | 成套美术、CRT、反馈、触控、性能、构建产物 | 浏览器流程验证和视觉验收完成，限制有记录 |
+
+完整首版比普通单页卡牌演示复杂，应按以上交付门槛推进，不在规则未冻结时给固定工期承诺。
+
+## 8. 验证方法
+
+- 单元测试：牌型识别、A 的两种合法顺子、重复实例、主要牌型与包含关系、非计分牌、手牌等级、Boss 限制。
+- 计分金样：手算预期并记录阶段；加倍率/乘倍率换位必须产生正确差异；逐张与留手重触发范围分别验证。
+- 性质测试：无生成/销毁效果时卡牌守恒、实例不重复占区、非法命令不改状态、同种子同命令同结果。
+- 交易测试：重复点击购买/结算不重复扣钱或发奖；槽位满和余额不足不丢商品。
+- 存档测试：计分期间刷新恢复到已提交状态；随机流恢复一致；旧版本和损坏数据处理明确。
+- 浏览器流程：新局、排序、拖拽、出牌、弃牌、购买、跳盲、消耗品、胜败、刷新续局；Playwright 跑关键流程。
+- 视觉检查：1440×810、1280×720、平板和手机横屏；中文不溢出，提示框不出屏，点击命中跟随变换后牌面。
+- 性能目标：约定桌面设备上的正常场景目标 60 FPS；低性能设备关闭后处理并降低渲染分辨率，结果以实测为准。
+- 平衡测试：固定种子与脚本策略检查明显死局、数值异常和商店供给；自动策略胜率不等于人类体验，仍需人工玩不同流派。
+
+## 9. 来源
+
+- [S1 官方 FAQ](https://www.playbalatro.com/faq)：主循环、Ante 8、Joker 与塔罗的职责。
+- [S2 社区触发顺序指南](https://balatrogame.fandom.com/wiki/Guide:_Activation_Sequence)：计分阶段与顺序，非官方资料。
+- [S3 社区牌型页](https://balatrogame.fandom.com/wiki/Poker_Hands)：本次以搜索摘要取得部分信息，正文未成功获取；完整表待核实。
+- [S4 社区盲注页](https://balatrogame.fandom.com/wiki/Blinds_and_Antes)：本次仅获取搜索摘要，完整数值待核实。
+- [S5 PixiJS Application](https://pixijs.com/8.x/guides/components/application)：Canvas、渲染器与应用初始化。
+- [S6 Cocos Creator Web 发布](https://docs.cocos.com/creator/3.8/manual/en/editor/publish/publish-web.html)：Cocos 的 Web 构建支持。
+
+以上链接访问日期为 2026-09-21。依赖版本及社区规则在实施时固定，不能把网页更新自动当作项目规则变更。