docs(demo): 添加 Lucky Dice 资源交接清单

FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.md

@@ -0,0 +1,367 @@
+# Lucky Dice 资产与配置交付清单
+
+## 文档目的
+
+这份清单用于对齐美术、策划和程序在 Lucky Dice 第一版中的交付边界：
+
+- 美术同学需要提供哪些可落地资产。
+- 策划同学需要提供哪些规则、权重和玩法入口配置。
+- 程序当前 core 已经如何实现，接下来完整开发还需要哪些外部输入。
+
+当前实现以 `LuckyDiceRollFlowService` 为核心入口，Demo 表现层只做最小 UI 演示。也就是说，core 骨架已经足够承接后续开发；接下来重点不是继续扩 demo core，而是让美术和策划补齐完整表现、完整特殊结果、运营策略和目标短玩法内容。
+
+## 当前玩法闭环
+
+第一版核心链路如下：
+
+```text
+玩家触发普通 Roll
+-> DiceRollService 生成普通骰子结果
+-> ComboFactBuilder 生成组合事实
+-> ComboRuleMatcher 按优先级命中组合规则
+-> RollActionDispatcher 执行 action
+-> 如果 action 触发 Lucky Dice
+-> LuckyDiceFlowService 筛选候选并按权重随机
+-> 生成 Lucky Dice 结果槽
+-> TargetModeResolver 解析目标玩法模式
+-> 输出 EnterTargetModeEffect 给表现层或目标玩法入口
+```
+
+当前默认结果：
+
+| 场景 | 当前配置结果 |
+| --- | --- |
+| 数字 + 数字 | 普通奖励 |
+| 数字 + clover | 普通奖励 + Clover bonus |
+| clover + clover | 触发 Lucky Dice |
+| Lucky Dice 选中 rocket | 进入 `slap_down_normal` |
+| Lucky Dice 选中 thief | 进入 `treasure_heist_normal` |
+
+## 美术资产清单
+
+### 第一版必须提供
+
+| 模块 | 资产 | 数量/规格 | 用途 | 命名建议 |
+| --- | --- | --- | --- | --- |
+| 普通骰子 | 数字骰面 | 5 个，数字 `2/3/4/5/6` | 普通 Roll 展示 | `dice_face_2` 到 `dice_face_6` |
+| 普通骰子 | Clover 骰面 | 1 个 | 触发 bonus 或 Lucky Dice | `dice_face_clover` |
+| Lucky Dice | Rocket 结果图标 | 1 个 | 表示进入 Slap Down | `lucky_result_rocket` |
+| Lucky Dice | Thief 结果图标 | 1 个 | 表示进入 Treasure Heist | `lucky_result_thief` |
+| Lucky Dice | 结果槽底板 | 1 套，可复用 3 格 | 当前显示 3 个相同结果槽 | `lucky_slot_frame` |
+| UI | Lucky Dice 标题区 | 1 套 | 进入特殊流程时显示标题 | `lucky_title_panel` |
+| UI | 倍率/奖励文案底板 | 1 套 | 显示倍率、奖励或结果反馈 | `lucky_reward_panel` |
+| UI | 普通投骰按钮状态 | 至少 3 态 | 待投、投掷中、再投一次 | `btn_roll_normal/default/disabled` |
+| UI | 特殊结果揭示状态 | 至少 1 套 | Lucky Dice 结果亮相 | `lucky_reveal_state` |
+
+### 第一版建议提供
+
+| 模块 | 资产 | 说明 |
+| --- | --- | --- |
+| 转场 | 普通 Roll 命中 Lucky Dice 的轻量转场 | 不需要复杂白烟或飞入，先提供短过渡即可 |
+| 反馈 | Clover bonus 的小特效 | 用于区分数字 + clover 和普通奖励 |
+| 反馈 | Lucky Dice 命中特殊结果的高亮 | 结果槽定格时使用 |
+| 音效 | 普通骰子滚动音效 | 可先 1 个循环或短音 |
+| 音效 | Lucky Dice 揭示音效 | 结果揭示时播放 |
+| 音效 | 进入目标玩法音效 | `rocket/thief` 跳转前反馈 |
+
+### 后续扩展预留
+
+| 扩展方向 | 资产需求 |
+| --- | --- |
+| 新 Lucky Dice 结果 | `chest/bomb/key` 等图标、命中特效、入口反馈 |
+| 结果槽数量变化 | 2 格、4 格或动态布局适配资源 |
+| 更复杂动画 | 托盘、骰子飞入、粒子爆发、白烟转场、镜头震动 |
+| 教程/Bonus 模式 | 教程标识、bonus 标识、特殊状态底板 |
+| 目标玩法落地 | Slap Down、Treasure Heist 各自入口插画或短玩法 UI |
+
+### 完整表现开发需要提供
+
+这些不是当前 demo core 的必需项，但属于下一阶段完整开发前必须向美术收齐的输入。
+
+| 模块 | 资产/说明 | 需要确认 |
+| --- | --- | --- |
+| 托盘动画 | Lucky Dice 托盘出现、停留、退出的完整动画 | 时长、入场方向、层级、是否可跳过 |
+| 骰子飞入 | 普通骰或 Lucky Dice 结果飞入槽位的动画 | 起点、路径、缓动、落点反馈 |
+| 白烟转场 | 命中 Lucky Dice 或进入目标玩法前的白烟/遮罩转场 | 遮挡范围、时长、是否承接场景切换 |
+| 粒子爆发 | 命中特殊结果、Clover bonus、进入目标玩法的粒子 | 颜色、强度、触发节点 |
+| 全套时序参考 | 竞品完整动画拆帧或时间轴 | 每段开始/结束点、可交互锁定时间 |
+| 失败/兜底表现 | 候选池为空、目标模式缺失、普通奖励兜底的提示表现 | 是否展示给玩家、是否只进调试日志 |
+
+## 策划配置清单
+
+### 骰子集合配置
+
+| 字段 | 当前值 | 说明 | 提供方 |
+| --- | --- | --- | --- |
+| `diceSetId` | `normal_main` | 普通骰子集合 ID | 策划 |
+| `setType` | `Normal` | 普通骰子集合 | 程序固定枚举，策划确认 |
+| `diceCount` | `2` | 普通 Roll 投几颗骰子 | 策划 |
+| `faces` | `2,3,4,5,6,clover` | 普通骰面池 | 策划确认，美术提供图 |
+| `diceSetId` | `lucky_dice` | Lucky Dice 集合 ID | 策划 |
+| `setType` | `Lucky` | 特殊结果集合 | 程序固定枚举，策划确认 |
+| `defaultResultSlotCount` | `3` | 特殊结果默认展示槽数 | 策划 |
+| `faces` | `rocket,thief` | 第一版特殊结果池 | 策划确认，美术提供图 |
+
+### 普通组合规则配置
+
+| 字段 | 当前示例 | 说明 |
+| --- | --- | --- |
+| `ruleId` | `normal_clover_clover_lucky_dice` | 规则唯一 ID |
+| `priority` | `100` | 优先级，高的先匹配 |
+| `matcherType` | `ExactCombo` | 使用哪种匹配器 |
+| `comboKey` | `clover_clover` | 精确组合 key |
+| `actions` | `trigger_lucky_dice` | 命中后执行的行为 |
+| `stopAfterMatched` | `true` | 命中后是否停止后续规则 |
+
+当前默认规则：
+
+| 优先级 | 规则 | 行为 |
+| --- | --- | --- |
+| 100 | `clover_clover` | `trigger_lucky_dice` |
+| 50 | 包含 1 个 `clover` | `grant_reward` + `add_multiplier` |
+| 10 | 全部是数字 | `grant_reward` |
+
+策划新增组合时，优先新增规则配置；只有现有 matcher 无法表达时才需要程序新增 matcher。
+
+### 可用 matcher 类型
+
+| matcher | 可表达内容 |
+| --- | --- |
+| `ExactCombo` | 精确匹配无序或有序组合 key |
+| `AllNumbers` | 所有骰子都是数字 |
+| `ContainsFace` | 包含指定骰面 |
+| `FaceCount` | 指定骰面数量等于某值 |
+| `FaceCountRange` | 指定骰面数量在区间内 |
+| `DiceCount` | 限定骰子数量 |
+| `NumberPair` | 数字对子 |
+| `NumberOfAKind` | N 个相同数字 |
+| `NumberSumRange` | 数字点数和区间 |
+
+### 可用 action 类型
+
+| action | 当前效果 | 需要策划提供的参数 |
+| --- | --- | --- |
+| `grant_reward` | 产出普通奖励效果 | 后续需要接真实奖励时补奖励 ID、数量、倍率策略 |
+| `add_multiplier` | 产出倍率效果 | 当前使用 `reason=clover_bonus` |
+| `trigger_lucky_dice` | 进入 Lucky Dice 流程 | 无 |
+
+规格中预留了 `enter_mode` 和 `show_popup`，但当前默认执行器尚未实现；如果策划需要直接进玩法或弹提示，需要先补程序执行器。
+
+### Lucky Dice 候选配置
+
+| 字段 | 当前示例 | 说明 |
+| --- | --- | --- |
+| `resultKey` | `rocket` | Lucky Dice 抽中的特殊结果 |
+| `targetKey` | `slap_down` | 目标玩法 ID |
+| `resultSlotCount` | `3` | 显示几个结果槽 |
+| `weight` | `1` | 权重随机用 |
+| `enabled` | `true` | 是否启用 |
+| `minLevel` | `0` | 最低玩家等级 |
+| `sourceFilter` | `normal_roll` | 允许从哪个来源触发 |
+| `isDefault` | `true` | 候选池兜底结果 |
+
+当前默认候选：
+
+| resultKey | targetKey | modeKey | slot | weight | default |
+| --- | --- | --- | --- | --- | --- |
+| `rocket` | `slap_down` | `slap_down_normal` | 3 | 1 | 是 |
+| `thief` | `treasure_heist` | `treasure_heist_normal` | 3 | 1 | 否 |
+
+### 目标模式配置
+
+| 字段 | 当前示例 | 说明 |
+| --- | --- | --- |
+| `resultKey` | `rocket` | Lucky Dice 特殊结果 |
+| `targetKey` | `slap_down` | 目标玩法 |
+| `modeKey` | `slap_down_normal` | 具体进入模式 |
+
+后续如果要支持新手教程、bonus 模式或活动模式，建议新增 mode 配置与解析规则，不要把分支写进 Lucky Dice 随机逻辑里。
+
+### 完整结果与短玩法内容配置
+
+这些内容是下一阶段开发需要策划提供的核心输入。
+
+| 内容 | 需要提供 | 说明 |
+| --- | --- | --- |
+| `chest` 完整玩法 | `resultKey`、`targetKey`、默认 `modeKey`、奖励规则、表现需求、失败/退出规则 | 当前 core 支持新增候选，但玩法语义需要策划定义 |
+| `bomb` 完整玩法 | 触发条件、目标玩法、奖励或惩罚、是否影响倍率、表现需求 | 需要明确是否只是入口还是独立短玩法 |
+| `key` 完整玩法 | 解锁对象、奖励池、目标玩法、与进度/关卡的关系 | 需要明确是否有库存、冷却或次数限制 |
+| Slap Down 短玩法规则 | 入口条件、胜负条件、交互方式、奖励结算、退出回主循环规则 | 当前只解析到 `slap_down_normal`，未实现短玩法内容 |
+| Treasure Heist 短玩法规则 | 入口条件、交互方式、奖励结算、失败处理、退出回主循环规则 | 当前只解析到 `treasure_heist_normal`，未实现短玩法内容 |
+| 组合行为说明 | 每个普通骰组合对应的玩家可感知结果、奖励、倍率、提示、是否进入 Lucky Dice | 程序仍优先映射到通用 action；只有出现新通用行为时才新增 executor |
+
+### 复杂运营权重策略
+
+当前 core 已有 `weight`、`enabled`、`minLevel`、`sourceFilter`，但复杂运营策略还需要策划补完整规则。
+
+| 策略 | 需要提供 |
+| --- | --- |
+| 活动期权重 | 活动 ID、起止条件、哪些 `resultKey` 提权、权重变化值 |
+| 新手期策略 | 第几次 Roll 固定结果、何时开放随机、教程模式如何映射 |
+| 冷却策略 | 每个 `targetKey/resultKey` 的冷却时间、次数限制、跨局是否继承 |
+| 保底策略 | 连续未命中特殊结果几次后提升概率或强制命中 |
+| 互斥策略 | 哪些结果不能连续出现，哪些结果不能与当前关卡/活动共存 |
+| 兜底策略 | 候选池为空、权重全 0、模式缺失时给玩家什么结果 |
+
+### 兜底与验收配置
+
+策划需要确认以下策略：
+
+| 问题 | 当前程序行为 | 需要确认 |
+| --- | --- | --- |
+| 普通组合未命中 | 目前规则覆盖默认 2 骰主要组合 | 未命中时是否发普通奖励兜底 |
+| Lucky Dice 候选过滤后为空 | 优先找过滤后 default；没有则 `NormalRewardFallback` | 是否允许回普通奖励 |
+| 候选权重都小于等于 0 | 不参与随机，走 default 或普通奖励兜底 | 是否需要配置校验直接报错 |
+| 目标模式缺失 | 返回 `TargetModeFailedEffect` | 是否弹错误、发普通奖励或阻断 |
+| 新增结果没有图标 | core 可出结果，但表现层无法正确展示 | 是否允许占位图 |
+
+## 当前 core 实现说明
+
+### 入口
+
+`LuckyDiceRuntimeFactory.CreateDefaultFlow()` 创建默认运行时，注入：
+
+- `DiceRollService`
+- `ComboRuleMatcher`
+- `RollActionDispatcher`
+- `LuckyDiceFlowService`
+- `TargetModeResolver`
+
+外部只需要向 `LuckyDiceRollFlowService.Execute()` 传入 `RollFlowRequest`，就能得到完整 `RollFlowResult`。
+
+### 普通 Roll
+
+`DiceRollService` 根据 `DiceSetConfig.DiceCount` 投掷，不写死两颗骰子。`ComboFactBuilder` 会把普通结果转成：
+
+- 原始 faces
+- `FaceCounts`
+- `NumberValues`
+- `NumberSum`
+- `CloverCount`
+- `NormalizedKey`
+- `OrderedKey`
+
+普通组合匹配只处理 `DiceSetType.Normal`。如果把 Lucky Dice 特殊结果交给 `ComboFactBuilder`，测试已经覆盖会拒绝处理。
+
+### 规则匹配
+
+`ComboRuleMatcher` 按优先级匹配规则，matcher 由 `MatcherType` 注册。当前默认 matcher 已覆盖第一版和 N 骰扩展常用场景。
+
+这意味着新增组合时通常只需要策划加配置，例如：
+
+```text
+FaceCountRange clover min 2 -> trigger_lucky_dice
+NumberOfAKind count 3 -> grant_reward + add_multiplier
+```
+
+### 行为执行
+
+`RollActionDispatcher` 只按 `ActionType` 找 executor，不按 `clover_clover` 这类组合 key 找方法。
+
+当前执行器只实现三类：
+
+- `grant_reward`
+- `add_multiplier`
+- `trigger_lucky_dice`
+
+如果未来要有弹窗、直接进玩法、发具体道具包，需要新增通用 executor，而不是给每个组合写独立方法。
+
+### Lucky Dice 选择
+
+`LuckyDiceFlowService.Select()` 当前做了三层筛选：
+
+1. `enabled`
+2. `playerLevel >= minLevel`
+3. `sourceFilter` 包含当前 `TriggerSource`
+
+筛选后按 `weight` 做随机。若没有可随机候选，会尝试 filtered 里的 `isDefault`；仍没有时返回普通奖励兜底标记 `NormalRewardFallback`。
+
+当前实现还没有独立的 cooldown/tutorial filter 类，字段和规格已预留，后续要做时应在这里扩展筛选链。
+
+### 结果槽
+
+Lucky Dice 随机只选一个 `resultKey`。展示槽由配置生成：
+
+```text
+slotCount = candidate.resultSlotCount
+         ?? luckyDiceSet.defaultResultSlotCount
+         ?? 3
+```
+
+第一版会把同一个 `resultKey` 重复填满槽位，例如 `rocket, rocket, rocket`。
+
+### 目标模式解析
+
+`TargetModeResolver` 用 `resultKey + targetKey` 查 `TargetModeConfig`，得到最终 `modeKey`。
+
+当前默认映射：
+
+- `rocket + slap_down -> slap_down_normal`
+- `thief + treasure_heist -> treasure_heist_normal`
+
+如果映射缺失，会返回 `MissingTargetMode`，不会静默吞掉。
+
+### 表现层
+
+`LuckyDiceDemoController` 是当前最小表现 demo：
+
+- 运行时创建 Canvas。
+- 展示 2 个普通骰子文本。
+- 命中 Lucky Dice 时展示 3 个特殊结果槽。
+- 根据 `LuckyDiceDemoSnapshot` 显示组合、规则、效果和目标模式。
+
+它现在使用文字模拟骰面和结果，尚未接入正式图片、动画、音效或目标玩法真实场景。
+
+## 给美术和策划的交付格式建议
+
+### 美术交付建议
+
+```text
+Art/LuckyDice/
+  DiceFaces/
+    dice_face_2.png
+    dice_face_3.png
+    dice_face_4.png
+    dice_face_5.png
+    dice_face_6.png
+    dice_face_clover.png
+  LuckyResults/
+    lucky_result_rocket.png
+    lucky_result_thief.png
+  UI/
+    lucky_slot_frame.png
+    lucky_title_panel.png
+    lucky_reward_panel.png
+  VFX/
+    vfx_clover_bonus.prefab
+    vfx_lucky_reveal.prefab
+  Audio/
+    sfx_dice_roll.wav
+    sfx_lucky_reveal.wav
+    sfx_target_enter.wav
+```
+
+### 策划配置表建议
+
+第一版建议拆成 4 张表或 4 个 JSON/ScriptableObject：
+
+| 表 | 主键 | 内容 |
+| --- | --- | --- |
+| `DiceSetConfig` | `diceSetId` | 骰子集合、数量、面池、默认槽数 |
+| `ComboRuleConfig` | `ruleId` | 普通组合规则、优先级、matcher、actions |
+| `LuckyDiceCandidateConfig` | `resultKey + targetKey` | Lucky Dice 候选、权重、启用条件、槽数 |
+| `TargetModeConfig` | `resultKey + targetKey` | 目标玩法模式映射 |
+
+程序当前已经有这些结构的本地默认版本；后续可以把默认硬编码迁移到 ScriptableObject 或 JSON。
+
+## 下一阶段需要收齐
+
+当前 demo core 已经足够验证基础链路。下一阶段如果要进入完整开发，需要美术和策划补齐以下内容：
+
+- 完整复刻竞品的托盘、飞入、白烟、粒子爆发全套动画拆解与资源。
+- `chest/bomb/key` 的完整玩法内容、入口配置、奖励结算和表现需求。
+- 复杂运营权重策略，包括活动期、新手期、冷却、保底、互斥和兜底。
+- Slap Down / Treasure Heist 的完整短玩法规则，而不仅是 `modeKey`。
+- 每个普通骰组合的行为需求说明，包括奖励、倍率、提示、是否触发 Lucky Dice。
+
+程序侧当前不建议为每个组合直接新增独立方法；策划需要提供的是“组合对应的玩法意图和参数”。程序会优先把这些意图配置到现有 matcher/action 体系中，只有现有通用 action 无法表达时，才新增新的通用 executor。