# 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。