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

Lucky Dice 资产与配置交付清单

文档目的

这份清单用于对齐美术、策划和程序在 Lucky Dice 第一版中的交付边界：

• 美术同学需要提供哪些可落地资产。
• 策划同学需要提供哪些规则、权重和玩法入口配置。
• 程序当前 core 已经如何实现，接下来完整开发还需要哪些外部输入。

当前实现以 LuckyDiceRollFlowService 为核心入口，Demo 表现层只做最小 UI 演示。也就是说，core 骨架已经足够承接后续开发；接下来重点不是继续扩 demo core，而是让美术和策划补齐完整表现、完整特殊结果、运营策略和目标短玩法内容。

当前玩法闭环

第一版核心链路如下：

玩家触发普通 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 骰扩展常用场景。

这意味着新增组合时通常只需要策划加配置，例如：

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。展示槽由配置生成：

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 显示组合、规则、效果和目标模式。

它现在使用文字模拟骰面和结果，尚未接入正式图片、动画、音效或目标玩法真实场景。

给美术和策划的交付格式建议

美术交付建议

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。