diff --git a/FishDice/Docs/Handoff/assets/big-fish-hidden-ui-effect.png b/FishDice/Docs/Handoff/assets/big-fish-hidden-ui-effect.png new file mode 100644 index 0000000..9105e13 Binary files /dev/null and b/FishDice/Docs/Handoff/assets/big-fish-hidden-ui-effect.png differ diff --git a/FishDice/Docs/Handoff/assets/fish-tide-dice-nohotspot-denoised.png b/FishDice/Docs/Handoff/assets/fish-tide-dice-nohotspot-denoised.png new file mode 100644 index 0000000..7dbe28d Binary files /dev/null and b/FishDice/Docs/Handoff/assets/fish-tide-dice-nohotspot-denoised.png differ diff --git a/FishDice/Docs/Handoff/assets/fish-tide-tap-nohotspot-denoised.png b/FishDice/Docs/Handoff/assets/fish-tide-tap-nohotspot-denoised.png new file mode 100644 index 0000000..48c9145 Binary files /dev/null and b/FishDice/Docs/Handoff/assets/fish-tide-tap-nohotspot-denoised.png differ diff --git a/FishDice/Docs/Handoff/assets/giant-shadow-drag-denoised.png b/FishDice/Docs/Handoff/assets/giant-shadow-drag-denoised.png new file mode 100644 index 0000000..b5f1f1d Binary files /dev/null and b/FishDice/Docs/Handoff/assets/giant-shadow-drag-denoised.png differ diff --git a/FishDice/Docs/Handoff/frames/main_01_double_clover.jpg b/FishDice/Docs/Handoff/frames/main_01_double_clover.jpg new file mode 100644 index 0000000..a768073 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_01_double_clover.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_02_clover_burst.jpg b/FishDice/Docs/Handoff/frames/main_02_clover_burst.jpg new file mode 100644 index 0000000..2000a2e Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_02_clover_burst.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_03_title_flash.jpg b/FishDice/Docs/Handoff/frames/main_03_title_flash.jpg new file mode 100644 index 0000000..4007c2b Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_03_title_flash.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_04_board_rise.jpg b/FishDice/Docs/Handoff/frames/main_04_board_rise.jpg new file mode 100644 index 0000000..afe22ea Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_04_board_rise.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_05_dice_enter.jpg b/FishDice/Docs/Handoff/frames/main_05_dice_enter.jpg new file mode 100644 index 0000000..1145fae Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_05_dice_enter.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_06_roll_mid.jpg b/FishDice/Docs/Handoff/frames/main_06_roll_mid.jpg new file mode 100644 index 0000000..04df97f Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_06_roll_mid.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_07_roll_settle.jpg b/FishDice/Docs/Handoff/frames/main_07_roll_settle.jpg new file mode 100644 index 0000000..295cbc8 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_07_roll_settle.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_08_first_lock.jpg b/FishDice/Docs/Handoff/frames/main_08_first_lock.jpg new file mode 100644 index 0000000..6704105 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_08_first_lock.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_09_final_lock.jpg b/FishDice/Docs/Handoff/frames/main_09_final_lock.jpg new file mode 100644 index 0000000..d36bb64 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_09_final_lock.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_10_reward_launch.jpg b/FishDice/Docs/Handoff/frames/main_10_reward_launch.jpg new file mode 100644 index 0000000..54e23a7 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_10_reward_launch.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_11_transition_title.jpg b/FishDice/Docs/Handoff/frames/main_11_transition_title.jpg new file mode 100644 index 0000000..db2d043 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_11_transition_title.jpg differ diff --git a/FishDice/Docs/Handoff/frames/main_12_target_mode.jpg b/FishDice/Docs/Handoff/frames/main_12_target_mode.jpg new file mode 100644 index 0000000..ad0bfe3 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/main_12_target_mode.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_a_01_double_clover.jpg b/FishDice/Docs/Handoff/frames/variant_a_01_double_clover.jpg new file mode 100644 index 0000000..3e2fb81 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_a_01_double_clover.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_a_02_board.jpg b/FishDice/Docs/Handoff/frames/variant_a_02_board.jpg new file mode 100644 index 0000000..6b59a04 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_a_02_board.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_a_03_locking.jpg b/FishDice/Docs/Handoff/frames/variant_a_03_locking.jpg new file mode 100644 index 0000000..e3d479d Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_a_03_locking.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_a_04_complete.jpg b/FishDice/Docs/Handoff/frames/variant_a_04_complete.jpg new file mode 100644 index 0000000..4912c5e Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_a_04_complete.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_a_05_slap_down.jpg b/FishDice/Docs/Handoff/frames/variant_a_05_slap_down.jpg new file mode 100644 index 0000000..524bcd8 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_a_05_slap_down.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_b_01_clover_burst.jpg b/FishDice/Docs/Handoff/frames/variant_b_01_clover_burst.jpg new file mode 100644 index 0000000..411d0dd Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_b_01_clover_burst.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_b_02_board.jpg b/FishDice/Docs/Handoff/frames/variant_b_02_board.jpg new file mode 100644 index 0000000..371bf98 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_b_02_board.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_b_03_locking.jpg b/FishDice/Docs/Handoff/frames/variant_b_03_locking.jpg new file mode 100644 index 0000000..0f07815 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_b_03_locking.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_b_04_reward.jpg b/FishDice/Docs/Handoff/frames/variant_b_04_reward.jpg new file mode 100644 index 0000000..ce932f9 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_b_04_reward.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_b_05_transition.jpg b/FishDice/Docs/Handoff/frames/variant_b_05_transition.jpg new file mode 100644 index 0000000..b44a06f Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_b_05_transition.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_c_01_double_clover.jpg b/FishDice/Docs/Handoff/frames/variant_c_01_double_clover.jpg new file mode 100644 index 0000000..96ef55b Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_c_01_double_clover.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_c_02_clover_burst.jpg b/FishDice/Docs/Handoff/frames/variant_c_02_clover_burst.jpg new file mode 100644 index 0000000..3422bcb Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_c_02_clover_burst.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_c_03_board.jpg b/FishDice/Docs/Handoff/frames/variant_c_03_board.jpg new file mode 100644 index 0000000..bf667a2 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_c_03_board.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_c_04_lock.jpg b/FishDice/Docs/Handoff/frames/variant_c_04_lock.jpg new file mode 100644 index 0000000..932cfde Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_c_04_lock.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_c_05_launch.jpg b/FishDice/Docs/Handoff/frames/variant_c_05_launch.jpg new file mode 100644 index 0000000..bc82f09 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_c_05_launch.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_01_daily_overlay.jpg b/FishDice/Docs/Handoff/frames/variant_d_01_daily_overlay.jpg new file mode 100644 index 0000000..289c272 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_01_daily_overlay.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_02_title.jpg b/FishDice/Docs/Handoff/frames/variant_d_02_title.jpg new file mode 100644 index 0000000..f02495d Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_02_title.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_03_board.jpg b/FishDice/Docs/Handoff/frames/variant_d_03_board.jpg new file mode 100644 index 0000000..9be1a78 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_03_board.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_04_locking.jpg b/FishDice/Docs/Handoff/frames/variant_d_04_locking.jpg new file mode 100644 index 0000000..a42e345 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_04_locking.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_05_complete.jpg b/FishDice/Docs/Handoff/frames/variant_d_05_complete.jpg new file mode 100644 index 0000000..9a2819c Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_05_complete.jpg differ diff --git a/FishDice/Docs/Handoff/frames/variant_d_06_transition.jpg b/FishDice/Docs/Handoff/frames/variant_d_06_transition.jpg new file mode 100644 index 0000000..4f648d5 Binary files /dev/null and b/FishDice/Docs/Handoff/frames/variant_d_06_transition.jpg differ diff --git a/FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.html b/FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.html new file mode 100644 index 0000000..5ed0739 --- /dev/null +++ b/FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.html @@ -0,0 +1,823 @@ + + + + + + FishDice Lucky Dice 资产与配置交付清单 + + + +
+

FishDice Lucky Dice 资产与配置交付清单

+

+ 参考目标是桌面上的 Dig&Roll 双四叶草 Lucky Dice 流程拆解页。当前 FishDice demo core 已经足够承接后续开发： + 双 Clover 触发 Lucky Dice、三格结果栏、rocket/thief 进入目标模式的逻辑已经跑通；现在需要美术和策划补齐完整表现、特殊结果、运营权重和短玩法规则。 +

+
+
Core 已够继续收外部输入，不继续扩文字 demo
+
3 格固定特殊骰结果栏是表现基准
+
x1 / x3 / x20倍率改变价值感，不改变结构
+
7.5-9s触发到转场的主要表现时长参考
+
+
+ +
+ + +
+

协作阻塞看板：这些不是程序 core 内部能补齐的内容

+
+
+

美术同学 需要交付

+
    +
  • 双四叶草触发：压暗、绿色四叶草爆发、标题强闪光。
    • +
  • 基础 UI 套件：背景遮罩、标题字、倍率牌、三格槽、红色托盘、奖励容器。
    • +
  • 骰子部件：普通骰体、2/3/4/5/6/Clover 面、Lucky 特殊骰体和五类特殊面。
    • +
  • Lucky Dice 三格结果栏、红色托盘、三颗特殊骰飞入和滚动。
    • +
  • 逐格锁定、奖励飞出、彩带/粒子、白烟转场。
    • +
  • rocket / thief / chest / bomb / key 五类结果图标和对应命中特效。
    • +
+
+
+

策划同学 需要交付

+
    +
  • 每个普通骰组合的行为说明：奖励、倍率、提示、是否触发 Lucky Dice。
    • +
  • chest / bomb / key 的完整玩法语义、奖励结算和失败/退出规则。
    • +
  • Slap Down / Treasure Heist 的完整短玩法规则。
    • +
  • 活动期、新手期、冷却、保底、互斥、兜底等运营权重策略。
    • +
+
+
+

程序/联调 承接方式

+
    +
  • 当前 core 已能输出 Roll、规则、Lucky Dice 选择和目标模式结果。
    • +
  • 优先把策划意图配置到现有 matcher/action 体系。
    • +
  • 接入美术时间轴与资源，形成真实 Lucky Dice 表现层。
    • +
  • 只有现有通用 action 无法表达时，才新增新的通用 executor。
    • +
+
+
+
+ +
+
LUCKY DICE
+
+
+
+
+
+
+
1
+
2
+
3
+
ROCKET REWARD
+
+ +
+

当前核心链路

+
+

普通 Roll

DiceRollService 按配置生成普通骰，ComboFactBuilder 转成结构化组合事实。

+

规则与 action

ComboRuleMatcher 按优先级命中规则，RollActionDispatcher 按 action type 执行。

+

Lucky Dice

双 Clover 触发候选筛选与权重随机，生成 3 格结果，再解析目标模式。

+
+ + + + + + + + + +
场景当前配置结果后续需要提供
数字 + 数字普通奖励真实奖励池、倍率、飞入表现。
数字 + Clover普通奖励 + Clover bonusbonus 数值、文案、特效、音效。
Clover + Clover触发 Lucky Dice完整双四叶草爆发、标题、托盘、三骰入场动画。
rocketslap_down_normalSlap Down 完整短玩法规则和表现。
thieftreasure_heist_normalTreasure Heist 完整短玩法规则和表现。
+
+ +
+

主流程帧图：双四叶草到 Slap Down

+
+
双四叶草落定
1. 双四叶草停在 DIG 按钮上方，仍保留地图状态和金币倍率。
+
四叶草粒子爆发
2. 背景压暗，绿色四叶草从中心向外爆发，先确认稀有触发。
+
Lucky Dice 标题闪光
3. 标题用强黄光和两颗四叶草骰做入口识别。
+
三格结果栏和托盘入场
4. 三格结果栏和红色托盘同时入场，顶部显示当前倍率。
+
三颗特殊骰飞入
5. 三颗特殊骰从屏幕边缘飞入，轨迹用金色粒子强调随机感。
+
骰子中段滚动
6. 骰子在托盘上滚动，结果栏暂时保持空位，悬念集中在三格。
+
骰子落稳
7. 骰子落稳，开始准备逐格点亮。
+
第一格锁定
8. 第一个结果被金色垂线拉入左槽，槽位高亮。
+
三个火箭结果锁定
9. 三格全部锁定为火箭，明确奖励类型。
+
火箭奖励飞出
10. 火箭奖励从托盘中心飞出并撒彩带，完成奖励兑现。
+
Slap Down 转场标题
11. 白色烟尘转场，进入 SLAP DOWN 标题。
+
Slap Down 玩法场景
12. 目标玩法落地到实验室场景，奖励动画没有停在结算面板。
+
+
+ +
+

变体对比

+ + + + + + + + +
来源倍率 / 结果流程差异对 FishDice 的要求
新手1 44.0s - 58.0sx1 / 三火箭 / Slap Down地图挖掘自然触发，火箭结果可复用。rocket 需要完整 Slap Down 内容和入口表现。
新手1 119.8s - 131.5sx1 / 盗贼 / Treasure Heist同一容器换结果图标和目标玩法，三格结构不变。thief 需要完整 Treasure Heist 内容和入口表现。
新手2 147.0s - 158.0sx3 / 三火箭活动场景触发，背景不同但弹窗层级沿用。触发源要可复用，不只绑定普通地图骰子。
新手2 444.0s - 455.0sx20 / 盗贼 / Treasure Heist从日常奖励弹窗叠出双四叶草。运营活动和弹窗源也要能进入同一 Lucky Dice 表现层。
+ +

Slap Down 变体

+
+
早期双四叶草
双四叶草落定。
+
早期 Lucky Dice 入口
进入 Lucky Dice 入口。
+
早期火箭锁定
火箭结果逐格锁定。
+
早期火箭完成
三火箭完成。
+
早期 Slap Down
转入 Slap Down。
+
+ +

Treasure Heist 与倍率变体

+
+
Treasure 变体双四叶草
Treasure 变体双四叶草落定。
+
Treasure 变体锁定
盗贼结果开始锁定。
+
Treasure Heist 转场
转入 Treasure Heist。
+
x3 盘面
x3 三格盘面。
+
x20 盘面
x20 三格盘面。
+
x20 Treasure Heist
x20 转入 Treasure Heist。
+
+
+ +
+
+

基础素材对照清单

+ 美术/UI 阻塞输入 +
+
+ 这部分不是“完整动画”的大项，而是所有动画和界面都依赖的底层素材。可以按参考帧逐项对齐：先把基础 UI、骰子部件、图标和状态补齐，程序再把它们接入现有 core 输出。 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
分类参考帧参考里有什么FishDice 需要提供当前差距
普通骰面main_01
variant_c_01		两颗 Clover 停在 DIG 按钮上方，仍保留地图、金币倍率和普通骰落点关系。普通骰体、2/3/4/5/6/Clover 六类面、落定态、高亮态、禁用或遮罩态。缺正式骰面缺骰体材质
基础 UI 界面main_02
main_03		触发后先压暗背景，再用 Lucky Dice 大标题、强黄光和两颗 Clover 做入口识别。全屏 dim mask、标题字、标题光效、入口装饰、弹入/闪白/淡出时序。缺触发界面缺标题资源
结果栏 UImain_04
variant_d_03		金边三格槽、顶部倍率 x1/x3/x20、空槽、锁定槽和高亮槽都在同一个结构里。三格结果栏 prefab、倍率牌、空槽/滚动/锁定/完成四种状态、槽位高亮特效。core 有 slotCount缺 UI 资产
托盘/容器main_04
main_06		红色托盘作为三颗 Lucky Dice 的滚动容器，带厚度、阴影和中心舞台感。红色托盘底图或模型、托盘阴影、骰子落点参考、入场/抬升/停留动画。缺托盘缺落点规范
Lucky 特殊骰main_05
main_07		三颗特殊骰从屏幕边缘飞入，在托盘中滚动，最终停在可读面。特殊骰体、特殊面贴图、飞入轨迹粒子、滚动帧、抖动帧、停稳帧。缺特殊骰体缺飞入轨迹
结果图标main_09
variant_b_03		rocket/thief 图标进入三格槽后逐格锁定，图标决定后续目标玩法。rocket、thief、chest、bomb、key 五类结果图标，含普通态、锁定态、飞出态。缺 chest/bomb/key缺状态图
奖励飞出main_10
variant_b_04		结果从托盘中心飞出，同时出现彩带、金币和奖励强调。奖励容器、飞出路径、彩带/金币粒子、命中特效、飞向目标入口的收束点。缺飞出资源缺路径点
白烟转场main_11
variant_d_06		白烟遮挡旧界面，露出 Slap Down 或 Treasure Heist 的目标玩法标题。白烟 VFX、目标玩法 title card、转场遮罩、进入玩法前后的保留/销毁规则。缺转场 VFX缺标题卡
目标玩法 UImain_12
variant_a_05		转入实验室/目标玩法场景，不停留在 Lucky Dice 结算面板。Slap Down、Treasure Heist、chest、bomb、key 对应玩法 UI、按钮、结算和返回入口。缺短玩法 UI缺规则定义
+
+ +
+
+

美术资产清单

+ 美术阻塞输入 +
+
+
触发确认先于结果。
双四叶草不是直接给奖励，而是先压暗、四叶草粒子爆发、标题闪光，告诉玩家稀有事件已发生。
+
三格结构稳定。
无论 x1、x3、x20，三颗特殊骰和三格锁定不变；倍率只改变价值感。
+
结果强绑定下一玩法。
三火箭进入 Slap Down，盗贼进入 Treasure Heist；奖励不是停在结算面板。
+
+ +

必须提供

+ + + + + + + + + + + + + + + + + +
模块资产规格命名建议
基础 UI全屏背景压暗层触发 Lucky Dice 时覆盖当前地图或活动界面ui_lucky_dim_mask
基础 UI倍率牌x1/x3/x20，可扩展更多倍率ui_lucky_multiplier_badge
普通骰子数字骰面2/3/4/5/6dice_face_2 到 dice_face_6
普通骰子基础骰体普通 Roll 使用，需支持数字面和 Clover 面贴图dice_body_normal
普通骰子Clover 骰面普通骰面中的特殊面dice_face_clover
触发表现绿色四叶草爆发压暗背景 + 中心爆发 + 四叶草粒子vfx_double_clover_burst
Lucky Dice标题与强黄光Lucky Dice 标题、闪光、两颗 Clover 标识ui_lucky_dice_title
Lucky Dice三格结果栏固定 3 格，支持倍率显示ui_lucky_result_board
Lucky Dice红色托盘托盘入场、骰子滚动承载ui_lucky_dice_tray
Lucky Dice特殊骰体三颗 Lucky Dice 使用，需支持飞入、滚动、落稳dice_body_lucky
Lucky Dice特殊结果图标rocket/thief/chest/bomb/keylucky_result_rocket 等
奖励表现奖励飞出容器结果从托盘中心飞出，支持金币/道具/玩法入口ui_lucky_reward_flyout
转场白烟转场从结果奖励飞出到目标玩法标题vfx_lucky_mode_transition
+
+ +
+
+

策划配置清单

+ 策划阻塞输入 +
+ + + + + + + + + + +
表/配置当前值或需要提供说明
DiceSetConfignormal_main：2 颗，面池 2,3,4,5,6,clover普通骰数量和面池必须来自配置。
ComboRuleConfigclover_clover -> trigger_lucky_dice双 Clover 的优先级要高于普通奖励。
LuckyDiceCandidateConfigresult、target、slot、weight、enabled、sourceFilter、default现有 rocket/thief 只是默认样例。
TargetModeConfigrocket -> slap_down_normal，thief -> treasure_heist_normalchest/bomb/key 也需要对应目标模式。
完整结果玩法chest/bomb/key 的规则、奖励、失败/退出、表现需求当前 core 能接候选，但语义还缺策划定义。
短玩法规则Slap Down / Treasure Heist 的入口、胜负、操作、结算、回主循环当前只解析到 modeKey，还不是完整短玩法。
+ +

复杂运营权重策略

+
+

活动期权重

活动 ID、起止条件、哪些 resultKey 提权、权重变化值。

+

新手期策略

第几次 Roll 固定结果、何时开放随机、教程模式如何映射。

+

冷却与保底

冷却时间、次数限制、连续未命中特殊结果后的提权或强制命中。

+
+
+ +
+

当前 Core 实现说明

+
+
LuckyDiceRuntimeFactory + -> DiceRollService + -> ComboRuleMatcher + -> RollActionDispatcher + -> LuckyDiceFlowService + -> TargetModeResolver
+
+

实现边界

+

外部调用 LuckyDiceRollFlowService.Execute() 得到完整 RollFlowResult。当前 Demo 使用文字模拟骰面和结果，没有接正式动画、音效或目标玩法场景。

+

程序侧仍优先把策划意图配置到现有 matcher/action 体系中，确实无法表达时才新增通用 executor。

+
+
+
当前 core 已够承载下一阶段开发。后续不是继续扩文字 demo，而是接入美术时序、真实资源、结果配置和短玩法内容。
+
+ +
+

下一阶段需要收齐

+ +
+
+ + + + diff --git a/FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.md b/FishDice/Docs/Handoff/lucky-dice-assets-config-checklist.md new file mode 100644 index 0000000..4290d15 --- /dev/null +++ b/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。