@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/.claude/agents/refs/framework-5-component-filter.md

@@ -0,0 +1,252 @@
+# 5-Component Filter 框架 — 机制好玩度快速检验
+
+## 原始来源
+
+- **出处**：https://mcpmarket.com/zh/tools/skills/game-design-framework
+- **性质**：这是一个 Claude Code Skill 中提出的实战框架，并非学术论文。它综合了多个游戏设计理论（MDA、Game Feel 等），形成了一套**快速可操作**的机制评估工具。
+- **关联理论**：
+  - Steve Swink 的 Game Feel 6 组件（Response 对应"实时控制"，Satisfaction 对应"多汁性"）
+  - MDA 框架的 Aesthetics 层（Motivation 对应"目标情感"，Fit 对应"整体一致性"）
+  - Nielsen 的可用性启发式（Clarity 对应"系统可见性"和"匹配现实世界"）
+
+---
+
+## 一、核心思想
+
+5-Component Filter 是一个**快速评估清单**，用于在设计和迭代阶段检验每一个游戏机制是否"好玩"。
+
+它的核心问题是：
+
+> **"这个机制通过了以下 5 项检查吗？如果任一项不通过，它就不会好玩。"**
+
+---
+
+## 二、5 个组件详解
+
+### 组件 1：Clarity（清晰度）
+
+> **核心问题：玩家在 3 秒内能看懂怎么玩吗？**
+
+| 维度             | 检查点                                                |
+| ---------------- | ----------------------------------------------------- |
+| **视觉可见性**   | 可操作对象是否视觉突出？能否一眼分辨什么能点/不能点？ |
+| **动作可猜测性** | 不看教程，玩家能猜到该做什么吗？                      |
+| **反馈明确性**   | 操作后发生了什么——成功还是失败——是否立刻清晰？        |
+| **状态可读性**   | 当前游戏状态（分数、剩余步数、进度）是否随时可读？    |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 零教程可上手，3 秒内理解玩法 |
+| ⭐⭐ | 需要 1 次提示或试错后理解 |
+| ⭐ | 需要文字教程或多次试错 |
+| ❌ | 5 秒后仍不知道该做什么 |
+
+**Playable Ad 中的硬约束**：
+
+> 在 Playable Ad 中，Clarity 是**生死线**。玩家不会花超过 3 秒去"学"一个广告。如果不能即刻理解，就会关闭。
+
+**常见修复手段**：
+
+- 手指引导动画（指示首次操作）
+- 高亮可操作区域
+- 第一步设计为"不可能失败"
+- 减少首屏信息量
+
+---
+
+### 组件 2：Motivation（动机）
+
+> **核心问题：玩家为什么想做这个动作？**
+
+| 维度           | 检查点                               |
+| -------------- | ------------------------------------ |
+| **目标可见性** | 玩家是否知道自己在朝什么目标努力？   |
+| **进度感**     | 每次操作后是否感到"离目标更近了"？   |
+| **奖励预期**   | 玩家是否期待下一个动作会带来好结果？ |
+| **紧迫感**     | 是否有时间/步数/空间等约束驱动行动？ |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 玩家主动想做、停不下来 |
+| ⭐⭐ | 知道该做什么但没有强烈冲动 |
+| ⭐ | 被动执行，缺乏内在驱动力 |
+| ❌ | "为什么我要做这个？" |
+
+**设计策略**：
+
+| 策略         | 机制示例                               | 适用场景   |
+| ------------ | -------------------------------------- | ---------- |
+| **可见目标** | 进度条、目标分数、"消除 30 个红色方块" | 所有类型   |
+| **短期奖励** | 每次匹配后的分数弹出、金币收集动画     | 休闲消除   |
+| **紧迫感**   | 倒计时、步数限制、上升的障碍           | 增加挑战感 |
+| **好奇心**   | 翻转显示隐藏图案、解锁新内容预览       | 探索发现类 |
+| **差一点感** | 失败时显示"还差 2 个就赢了！"          | 转化驱动   |
+
+---
+
+### 组件 3：Response（响应性）
+
+> **核心问题：操作后 100ms 内有反馈吗？**
+
+| 维度       | 检查点                               |
+| ---------- | ------------------------------------ |
+| **即时性** | 触摸/点击后有即时视觉+听觉反馈吗？   |
+| **多通道** | 反馈是否同时涵盖视觉+听觉（+触觉）？ |
+| **比例性** | 反馈强度是否与动作重要性成正比？     |
+| **一致性** | 相同操作的反馈是否每次都一致？       |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 每次操作都有多通道即时反馈，爽快利落 |
+| ⭐⭐ | 有反馈但单通道或有延迟感 |
+| ⭐ | 部分操作无反馈或反馈不一致 |
+| ❌ | 操作后没有任何可感知的变化 |
+
+**这与 Steve Swink 的 Game Feel 直接对应**：
+
+- 100ms 阈值 → 来自 Swink 的"实时控制"组件
+- 多通道反馈 → 来自 Swink 的"润色"组件
+- 比例性 → 来自 Swink 的"多汁性"组件
+
+**快速检查表**：
+
+```
+□ 点击有按下缩放效果？
+□ 松手有弹起动画？
+□ 匹配成功有消除动画？
+□ 消除有音效？
+□ 连击有升级反馈？
+□ 失败有挫败感反馈（但不惩罚）？
+□ 每一帧都有东西在动？
+```
+
+---
+
+### 组件 4：Satisfaction（满足感）
+
+> **核心问题：每次成功操作有"爽"的感觉吗？**
+
+| 维度           | 检查点                                         |
+| -------------- | ---------------------------------------------- |
+| **"啊哈"时刻** | 操作结果是否超出玩家预期？（如意外的连锁消除） |
+| **感官奖励**   | 成功是否伴随视觉+听觉的"爆发"？                |
+| **成长曲线**   | 随着游戏进行，满足感是否在升级？               |
+| **对比度**     | 成功与未成功之间的反馈差距是否足够大？         |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 每次成功都想"再来一次"，有近乎上瘾的满足感 |
+| ⭐⭐ | 成功有正反馈但缺乏"wow"时刻 |
+| ⭐ | 成功与失败的感觉差距不大 |
+| ❌ | 成功了也没什么特别感觉 |
+
+**满足感的层级设计**（对应 Juice 的"连击升级"）：
+
+```
+Level 1（单次匹配）  → 小粒子 + 轻音效
+Level 2（连击 ×2）   → 更多粒子 + 音高上升 + 飘字
+Level 3（连击 ×3）   → 屏幕震动 + 大粒子 + 连击文字
+Level 4（超级连击）   → 全屏特效 + 慢动作 + 欢呼声
+```
+
+> **关键洞察**：满足感 = Response（响应性）× Surprise（惊喜度）。同样的响应如果每次都完全一样，会逐渐麻木。适度的随机性和升级机制维持满足感。
+
+---
+
+### 组件 5：Fit（契合度）
+
+> **核心问题：这个机制与整体风格搭吗？**
+
+| 维度               | 检查点                                 |
+| ------------------ | -------------------------------------- |
+| **与主题一致**     | 机制是否与游戏的视觉主题和世界观匹配？ |
+| **与其他机制协同** | 这个机制是否与其他机制产生有趣的交互？ |
+| **与目标受众匹配** | 机制的复杂度是否适合目标玩家？         |
+| **与平台特性适配** | 机制是否利用了平台的特有输入方式？     |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 机制与整体风格浑然一体、不可分割 |
+| ⭐⭐ | 机制与整体搭配，但有可改进空间 |
+| ⭐ | 机制感觉像是"外挂"上去的 |
+| ❌ | 明显与游戏整体格格不入 |
+
+**Fit 的检查维度扩展**：
+
+| 契合维度   | 好的例子                   | 坏的例子                 |
+| ---------- | -------------------------- | ------------------------ |
+| 主题契合   | 果冻消除游戏用"弹弹弹"动画 | 中世纪骑士游戏用霓虹粒子 |
+| 节奏契合   | 休闲消除的慢节奏配柔和配乐 | 放松游戏用高速闪烁特效   |
+| 复杂度契合 | 休闲广告用单指操作         | 休闲广告用 5 步组合操作  |
+| 平台契合   | 移动端用滑动/点击          | 移动端用双指旋转缩放     |
+
+---
+
+## 三、5-Component Filter 的使用方法
+
+### 方法 1：单机制评估卡
+
+评估一个具体的游戏机制（如"滑动交换两个相邻方块"）：
+
+```
+机制名称: [交换消除]
+┌──────────────┬────────┬─────────────────────────┐
+│ Component    │ Score  │ Notes                   │
+├──────────────┼────────┼─────────────────────────┤
+│ Clarity      │ ⭐⭐⭐  │ 滑动方向=交换方向，直觉  │
+│ Motivation   │ ⭐⭐⭐  │ 可见的目标分数+步数限制  │
+│ Response     │ ⭐⭐    │ 缺少消除音效，需补充     │
+│ Satisfaction │ ⭐⭐    │ 连锁反馈不够强烈         │
+│ Fit          │ ⭐⭐⭐  │ 与糖果主题完美搭配       │
+└──────────────┴────────┴─────────────────────────┘
+最低分: Response (⭐⭐) & Satisfaction (⭐⭐)
+优先改进: 添加消除音效 + 增强连锁视觉反馈
+```
+
+### 方法 2：多机制对比
+
+在 Brainstorm 阶段比较多个候选机制：
+
+```
+          Clarity  Motivation  Response  Satisfaction  Fit   Total
+方案A-滑动交换  ⭐⭐⭐     ⭐⭐⭐       ⭐⭐       ⭐⭐        ⭐⭐⭐   13
+方案B-点击选取  ⭐⭐      ⭐⭐        ⭐⭐⭐      ⭐⭐        ⭐⭐    11
+方案C-拖拽放置  ⭐⭐      ⭐⭐⭐       ⭐⭐       ⭐⭐⭐       ⭐⭐    12
+```
+
+### 方法 3：迭代检查点
+
+在开发过程中定期使用，特别是：
+
+1. **Brainstorm 后**：评估概念是否有基本的好玩潜力
+2. **原型完成后**：第一次可玩版本的快速健检
+3. **Juice 添加后**：确认 Juice 是否真的提升了各项分数
+4. **最终交付前**：确保没有组件被遗漏
+
+---
+
+## 四、快速诊断表
+
+当 QA 或玩家说"不好玩"但说不清原因时，用此表逐项排查：
+
+| 玩家的模糊反馈          | 最可能的缺失组件 | 优先修复方向                       |
+| ----------------------- | ---------------- | ---------------------------------- |
+| "不知道该干什么"        | Clarity          | 加引导动画、高亮可操作区           |
+| "没意思" / "为什么要玩" | Motivation       | 加可见目标、紧迫感、奖励预览       |
+| "操作没感觉" / "卡卡的" | Response         | 加即时反馈、音效、缓动动画         |
+| "赢了也没什么感觉"      | Satisfaction     | 加连击反馈、胜利演出、对比度       |
+| "感觉怪怪的" / "不搭"   | Fit              | 检查主题一致性、节奏匹配、平台适配 |
+
+---
+
+## 五、参考资源
+
+- 🔗 **框架来源**：[Game Design & Mechanics Framework (MCP Market)](https://mcpmarket.com/zh/tools/skills/game-design-framework)
+- 📕 **Clarity 理论基础**：Jakob Nielsen 的 [10 Usability Heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/)
+- 📕 **Response 理论基础**：Steve Swink 的 [Game Feel (2008)](https://www.taylorfrancis.com/books/mono/10.1201/9781482267334/game-feel-steve-swink)
+- 📕 **Motivation 理论基础**：MDA 框架的 [Aesthetics Taxonomy](https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research)

package/project-template-v2/.claude/agents/refs/framework-game-feel-juice.md

@@ -0,0 +1,266 @@
+# Game Feel & Game Juice 框架
+
+## 原始来源
+
+### 理论基石
+
+- **书籍**：Steve Swink (2008). _Game Feel: A Game Designer's Guide to Virtual Sensation_. Morgan Kaufmann.
+  - 详细解读：https://www.gamejuice.co.uk/articles/swink-6-components-game-feel
+
+### 经典演讲
+
+- **Juice it or Lose it** (2012) — Martin Jonasson & Petri Purho，Nordic Game Indie Night
+  - 解读：https://www.gamejuice.co.uk/articles/juice-it-or-lose-it-lessons
+- **The Art of Screenshake** (2013) — Jan Willem Nijman (Vlambeer), INDIGO Classes
+  - 中文解读：https://blog.chosenconcept.dev/tw/posts/2022/11/0012-the-art-of-screenshake/
+
+### 综合参考
+
+- Making Games 'Juicy'：https://abagames.github.io/joys-of-small-game-development-en/make_game_juicy.html
+- Game Feel 资源汇总：https://marcosecchi.github.io/resources/pages/gamedesign_game-feel.html
+
+---
+
+## 一、什么是 Game Feel？
+
+Game Feel（游戏手感）是指**玩家在操控游戏时感受到的无形触感**——为什么同样是"跳跃"，《超级马里奥》的跳跃就是比其他游戏"更舒服"？Game Feel 就是对这种差异的系统性解释。
+
+Steve Swink 在 2008 年的同名著作中首次将 Game Feel 系统化为 **6 个组件**，为"什么让游戏玩起来感觉好"提供了可分析、可诊断的结构框架。
+
+> **Game Feel 不是一个配方，而是一把测量工具和一套诊断语言。**
+
+---
+
+## 二、Steve Swink 的 6 个 Game Feel 组件
+
+### 组件 1：Real-Time Control（实时控制）
+
+**定义**：玩家必须能**直接**操控虚拟对象，且输入获得**即时**响应。
+
+**关键阈值**：
+
+- **100ms**：超过此延迟，大脑不再认为这是"直接控制"，而像是在"下达命令等执行"
+- **一致性 > 速度**：不稳定的 80ms 延迟比稳定的 100ms 感觉更糟
+
+**常见问题及修复**：
+| 问题 | 原因 | 修复方式 |
+|------|------|---------|
+| 操控迟钝 | 输入延迟过高 | 减少帧延迟，优化输入管线 |
+| 动作"卡住" | 必须等动画播完才能响应 | 输入缓存、动画取消、设置可打断帧 |
+| 感觉不灵敏 | 帧率不稳定 | 固定物理步长，与渲染帧率解耦 |
+
+### 组件 2：Simulated Space（空间模拟）
+
+**定义**：游戏世界必须遵循**内部一致**的物理规则（重量、动量、碰撞、重力）。
+
+物理可以夸张，**但必须可预测**。
+
+**核心原则**：
+
+- 不可预测的物理让人愤怒——不是因为"不真实"，而是因为"无法建立心理模型"
+- 模拟必须延伸到玩家能互动的所有事物
+
+**经典案例**：
+
+- **《蔚蓝》(Celeste)**：物理完全不真实（空中冲刺违反物理定律），但内部绝对一致，玩家能精准预测落点
+- **反例**：角色有时被击退 3 格有时 5 格，没有可见原因 → 玩家困惑
+
+### 组件 3：Polish（润色）
+
+**定义**：游戏性非严格必需、但能让体验更丰富的修饰层——粒子、屏幕震动、音效、动画细节、拖尾等。
+
+这就是大众常说的 **"Juice"**。
+
+**⚠️ 关键顺序**：
+
+> **润色排在第三位，不是第一位。** 它是**放大器**——放大已经感觉良好的空间模拟。如果底层模拟很弱，润色只会让弱点更刺眼。
+
+**一致性要求**：
+
+- 特效必须形成一种"语言"——屏幕震动在不同语境下不能意思矛盾
+- 润色层应是有统一语法的系统，而非随意堆砌
+
+### 组件 4：Metaphor（隐喻）
+
+**定义**：虚拟对象与玩家**现实物理理解**之间的连接。
+
+玩家带着一生的物理体验来玩游戏。当虚拟互动与真实物理感觉共鸣时，会产生近乎潜意识的"正确感"。
+
+**示例**：
+| 隐喻匹配 | 效果 |
+|---------|------|
+| 重物落地→低沉轰鸣+屏幕微震 | ✅ 符合物理直觉，感觉"对" |
+| 爆头→清脆尖锐声+短衰减 | ✅ 高冲击碰撞的真实声学特征 |
+| 仙女魔杖→榴弹发射器声效 | ❌ 隐喻破裂，反馈与世界矛盾 |
+
+### 组件 5：Juiciness（多汁性）
+
+**定义**：**最小输入产生最大输出**的特质。游戏对每个动作给予不成比例的丰厚反馈。
+
+**核心理念**：让玩家每一个微小操作都感到"有力量、有效果"。
+
+**⚠️ 需要层级**：
+
+- 每次操作都全屏爆炸 → 反而削弱了真正重大事件的冲击力
+- 正确做法：**小动作小奖励，大动作大奖励**，建立清晰的反馈层级
+
+**玩具测试**（源自马里奥 64 团队）：
+
+> 在没有关卡、没有敌人的空房间里，光是跑、跳、操作，是否就已经令人满足？如果是，你就拥有了 Juiciness。
+
+### 组件 6：Mastery（学习与精通）
+
+**定义**：随着玩家内化操控、开始流畅行动，手感随时间**不断加深**的掌控感。
+
+**深度 vs 天花板**：
+
+- 操控系统必须足够深，让精通能持续产生新能力
+- 操控太浅 → 很快触及天花板 → 玩家失去兴趣
+- 精通创造**心流**——这是长期留存的核心
+
+> **对 Playable Ad 的特殊考量**：15 秒内无法实现深度精通，但可以设计"可感知的操控深度"——让玩家觉得"如果我再玩一会儿，我能做得更好"，这正是转化的驱动力。
+
+---
+
+## 三、Game Feel 诊断工具
+
+当游戏"感觉不对"时，按组件逐一排查：
+
+| 症状                  | 对应组件   | 诊断方向                               |
+| --------------------- | ---------- | -------------------------------------- |
+| 操控迟钝、无响应      | ① 实时控制 | 查输入延迟、动画打断帧、响应时机       |
+| 移动不可预测、轻飘    | ② 空间模拟 | 查物理一致性、重力曲线、动量传递       |
+| 有特效但仍觉无力      | ③ 润色     | 查反馈通道是否同步、反馈语言是否一致   |
+| 技术正确但情感平淡    | ④ 隐喻     | 查反馈是否匹配世界逻辑和玩家物理直觉   |
+| 动作缺乏震撼力        | ⑤ 多汁性   | 查反馈的规模和种类与动作重要性是否匹配 |
+| 老手停止进步/失去兴趣 | ⑥ 精通     | 控制系统有天花板，阻碍了技巧表达       |
+
+**组件间的依赖关系**：
+
+```
+① 实时控制 ← 基础。没有它，⑥精通不可能
+② 空间模拟 ← ③润色的基座。模拟弱则润色制造混乱
+④ 隐喻    ← 绑定整个系统。没有它，所有反馈情感空洞
+```
+
+---
+
+## 四、Game Juice 实操清单
+
+Juice 是 Game Feel 中"润色"和"多汁性"组件的具体实现手段。以下综合了 **Juice it or Lose it** 演讲和 **The Art of Screenshake** 演讲中的所有技术：
+
+### 4.1 视觉反馈
+
+| #   | 技术                             | 描述                      | 示例                  |
+| --- | -------------------------------- | ------------------------- | --------------------- |
+| 1   | **Squash & Stretch（挤压拉伸）** | 物体弹跳/碰撞时的形变动画 | 球落地时压扁再弹起    |
+| 2   | **Screen Shake（屏幕震动）**     | 碰撞/消除时的短暂画面抖动 | 消除方块时轻震 0.1 秒 |
+| 3   | **Particles（粒子特效）**        | 碰撞/消除时喷射的粒子     | 方块消除时碎片飞溅    |
+| 4   | **Flash/Blink（闪白/闪烁）**     | 受击/激活时的短暂颜色变化 | 敌人被打中闪白 1 帧   |
+| 5   | **Color Change（颜色变化）**     | 根据状态变化调整颜色      | HP 低时角色变红       |
+| 6   | **Trail（拖尾）**                | 移动物体留下的轨迹        | 子弹拖出光轨          |
+| 7   | **Muzzle Flash（枪口焰）**       | 发射/释放时的源头特效     | 射击时枪口闪火        |
+| 8   | **Impact VFX（命中特效）**       | 击中目标时的视觉标记      | 命中时溅射火花        |
+| 9   | **Permanence（永久痕迹）**       | 保留战斗/操作的视觉痕迹   | 地上留有碎片          |
+
+### 4.2 动画与运动
+
+| #   | 技术                                   | 描述                  | 示例                     |
+| --- | -------------------------------------- | --------------------- | ------------------------ |
+| 10  | **Tweening/Easing（缓动）**            | 所有运动使用缓动曲线  | 方块落下用 easeOutBounce |
+| 11  | **Anticipation（预备动作）**           | 大动作前的蓄力姿势    | 跳跃前先蹲下             |
+| 12  | **Follow-through（随动）**             | 动作完成后的惯性延续  | 挥剑后手臂的回摆         |
+| 13  | **Knockback（击退）**                  | 碰撞后的位移反应      | 敌人被击中后弹飞         |
+| 14  | **Recoil（后坐力）**                   | 施力者自身的反作用    | 射击时枪向上弹跳         |
+| 15  | **Bigger Projectiles（更大的投射物）** | 弹药/投射物比实际更大 | 子弹放大到清晰可见       |
+
+### 4.3 时间操控
+
+| #   | 技术                                  | 描述                   | 示例                   |
+| --- | ------------------------------------- | ---------------------- | ---------------------- |
+| 16  | **Hit Stop/Freeze Frame（打击暂停）** | 命中瞬间的极短暂冻结   | 打击时停顿 2-3 帧      |
+| 17  | **Slow Motion（慢动作）**             | 关键时刻降低时间流速   | 最后一击进入 0.3x 慢放 |
+| 18  | **Speed Up（加速）**                  | 常规行为加速以保持节奏 | 子弹速度翻倍           |
+
+### 4.4 镜头
+
+| #   | 技术                            | 描述                   | 示例                         |
+| --- | ------------------------------- | ---------------------- | ---------------------------- |
+| 19  | **Camera Lerp（镜头平滑跟随）** | 镜头像弹簧一样柔和追踪 | 角色移动时镜头延迟 0.1s 跟随 |
+| 20  | **Camera Kick（镜头推动）**     | 有方向性的镜头偏移     | 射击时镜头向射击反方向微推   |
+| 21  | **Zoom（缩放）**                | 关键时刻拉近/推远      | 大规模消除时镜头微微拉远     |
+
+### 4.5 音效
+
+| #   | 技术                            | 描述                   | 示例                        |
+| --- | ------------------------------- | ---------------------- | --------------------------- |
+| 22  | **Impact SFX（打击音效）**      | 碰撞/消除时的声音      | 清脆的"啪"声                |
+| 23  | **Pitch Variation（音高变化）** | 连续操作的音高递增     | 连续消除从低音到高音        |
+| 24  | **Layered SFX（分层音效）**     | 多个声音叠加成丰满效果 | 爆炸 = 低频轰+中频碎+高频嘶 |
+| 25  | **BGM Reactive（音乐响应）**    | 背景音乐响应游戏事件   | 连击时 BGM 加鼓点           |
+
+### 4.6 情感反馈
+
+| #   | 技术                             | 描述                    | 示例                           |
+| --- | -------------------------------- | ----------------------- | ------------------------------ |
+| 26  | **Floating Text（飘字）**        | 动作结果的数字/文字弹出 | "+100" 向上飘出                |
+| 27  | **Celebration（庆祝演出）**      | 达成成就时的夸张表演    | 全消时烟花+欢呼声              |
+| 28  | **Expressions（表情）**          | 角色/物体显示情感反应   | 被选中的方块"瞪大眼睛"         |
+| 29  | **Combo Escalation（连击升级）** | 连续成功的反馈逐级增强  | Normal → Great → Amazing → MAX |
+
+---
+
+## 五、Juice 实施优先级
+
+根据 "Juice it or Lose it" 的核心建议：
+
+### 第一步：音效（成本最低、见效最快）
+
+一个好的打击/消除音效就能让操作感提升 50%。
+
+### 第二步：缓动动画
+
+将所有 `linear` 运动替换为 `easeOut` / `easeInOut`，瞬间提升品质感。
+
+### 第三步：层层叠加
+
+依次加入粒子 → 屏幕震动 → 慢动作 → 颜色变化……
+
+### 核心法则
+
+> **"More is more. Add more juice, then add more."**（多就是多。加更多 Juice，然后再加更多。）
+
+但要记住 Steve Swink 的警告：
+
+> **Juice 是放大器，不是遮瑕膏。** 底层 Game Feel（实时控制+空间模拟）必须先到位。
+
+---
+
+## 六、累积效应
+
+Juice 技术单独使用效果有限，但**累积叠加**产生质变：
+
+```
+裸机制                          → 🫤 能玩但乏味
++ 音效                          → 😐 稍好
++ 音效 + 粒子                    → 🙂 开始有感觉
++ 音效 + 粒子 + 屏幕震动          → 😀 体验明显提升
++ 音效 + 粒子 + 屏幕震动 + 慢动作  → 😆 开始上瘾
++ 以上全部 + 连击升级 + 飘字       → 🤩 停不下来
+```
+
+**整体远大于部分之和。**
+
+---
+
+## 七、参考资源汇总
+
+| 类型    | 名称                          | 链接                                                                                                     |
+| ------- | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
+| 📕 书籍 | Game Feel (Steve Swink, 2008) | [Taylor & Francis](https://www.taylorfrancis.com/books/mono/10.1201/9781482267334/game-feel-steve-swink) |
+| 🎤 演讲 | Juice it or Lose it (2012)    | [GameJuice 解读](https://www.gamejuice.co.uk/articles/juice-it-or-lose-it-lessons)                       |
+| 🎤 演讲 | The Art of Screenshake (2013) | [中文解读](https://blog.chosenconcept.dev/tw/posts/2022/11/0012-the-art-of-screenshake/)                 |
+| 📝 文章 | 6 Components of Game Feel     | [GameJuice](https://www.gamejuice.co.uk/articles/swink-6-components-game-feel)                           |
+| 📝 文章 | Making Games 'Juicy'          | [abagames](https://abagames.github.io/joys-of-small-game-development-en/make_game_juicy.html)            |
+| 🔗 汇总 | Game Feel Resources           | [marcosecchi](https://marcosecchi.github.io/resources/pages/gamedesign_game-feel.html)                   |
+| 🎮 案例 | Celeste & Forgiveness         | Celeste 如何用宽容度提升 Game Feel                                                                       |

package/project-template-v2/.claude/agents/refs/framework-mda.md

@@ -0,0 +1,147 @@
+# MDA 框架 — Mechanics, Dynamics, Aesthetics
+
+## 原始来源
+
+- **论文**：Hunicke, R., LeBlanc, M., & Zubek, R. (2004). _MDA: A Formal Approach to Game Design and Game Research_. AAAI Workshop – Technical Report.
+- **原文 PDF**：https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research
+- **Semantic Scholar**：https://www.semanticscholar.org/paper/MDA-%3A-A-Formal-Approach-to-Game-Design-and-Game-Hunicke-Leblanc/2b134e5c46eec50f69c702c0b4aa29687d5d8fba
+- **解读**：https://educationalgamedesign.com/mechanics-dynamics-and-aesthetics-mda-framework-by-hunicke-leblanc-and-zubek.html
+
+---
+
+## 一、核心思想
+
+MDA 框架将游戏拆解为三个相互关联的层次，提供了一种**形式化的语言**来分析和设计游戏。其最核心的洞察是：
+
+> **设计者自下而上（规则 → 行为 → 情感），玩家自上而下（情感 → 行为 → 规则）。**
+
+设计者编写规则（Mechanics），规则在运行时产生动态行为（Dynamics），动态行为引发玩家的情感体验（Aesthetics）。但玩家的感知方向正好相反——他们首先感受到"好不好玩"（Aesthetics），然后才注意到行为模式和底层规则。
+
+```
+设计者视角：  Mechanics  →  Dynamics  →  Aesthetics
+                 ↑ 你直接控制    ↑ 你间接影响    ↑ 你的最终目标
+
+玩家视角：    Aesthetics  →  Dynamics  →  Mechanics
+                 ↑ 首先感受到     ↑ 然后注意到    ↑ 最后才理解
+```
+
+---
+
+## 二、三层详解
+
+### 层次 1：Mechanics（机制）
+
+**定义**：游戏的组件、规则、算法和数据结构。
+
+这是设计者能**直接控制**的部分。包括：
+
+- 玩家可以执行的**动作/动词**（点击、滑动、放置、交换……）
+- 游戏运行的**规则和算法**（匹配判定、分数计算、消除逻辑……）
+- 底层的**数据结构**（棋盘矩阵、牌组列表、状态机……）
+
+**示例**（三消游戏）：
+| 机制要素 | 具体内容 |
+|---------|---------|
+| 动作 | 交换两个相邻方块 |
+| 匹配规则 | ≥3 个同色方块连成一线即消除 |
+| 重力 | 消除后上方方块下落填补空位 |
+| 分数算法 | 基础分 × 连击倍率 |
+
+### 层次 2：Dynamics（动态）
+
+**定义**：当机制被执行、玩家开始游戏后**涌现**的运行时行为。
+
+这是设计者只能**间接影响**的部分。Dynamics 是 Mechanics 的"运行时行为"——你设计了规则，但规则在实际游戏中会产生你未必预料到的交互模式和策略。
+
+**示例**（三消游戏）：
+| 动态行为 | 来源机制 |
+|---------|---------|
+| 连锁消除（一次消除引发新的匹配） | 重力 + 匹配规则的组合 |
+| 玩家优先寻找大规模消除而非小匹配 | 分数算法的倍率激励 |
+| 在有限步数下出现的紧迫感 | 步数限制 + 分数目标 |
+| 特殊方块的策略性保留 | 特殊方块生成规则 + 其清除范围 |
+
+### 层次 3：Aesthetics（美学/情感）
+
+**定义**：游戏旨在引发的**情感体验**。
+
+这是设计者的**最终目标**——让玩家"感觉好"。MDA 框架给出了一个经典的 **8 种乐趣分类法**，不是说游戏必须包含所有类型，而是帮助设计者明确自己的游戏主要瞄准哪几种情感。
+
+---
+
+## 三、8 种乐趣分类（Aesthetics Taxonomy）
+
+| #   | 类型     | 英文       | 关键词               | 描述                                                                     |
+| --- | -------- | ---------- | -------------------- | ------------------------------------------------------------------------ |
+| 1   | **感官** | Sensation  | 视听冲击、特效满足   | 通过视觉、听觉等感官刺激获得的愉悦。华丽的特效、悦耳的音效、流畅的动画。 |
+| 2   | **幻想** | Fantasy    | 代入、扮演、想象     | 让玩家代入一个虚构角色或世界，体验日常不可能的事情。                     |
+| 3   | **叙事** | Narrative  | 故事推进、情节展开   | 通过故事的展开和发展，给玩家"追剧"般的参与感。                           |
+| 4   | **挑战** | Challenge  | 克服困难、成就感     | 面对障碍、克服困难后获得的成就感。难度曲线和技巧门槛是关键。             |
+| 5   | **社交** | Fellowship | 合作、竞争、社区     | 与他人互动、合作或竞争带来的社交愉悦。                                   |
+| 6   | **探索** | Discovery  | 发现、惊喜、揭秘     | 发现新区域、新道具、隐藏内容时的惊喜和好奇心满足。                       |
+| 7   | **表达** | Expression | 自我展现、创造       | 玩家通过游戏系统表达自我的自由度（如捏脸、建筑、选择路线）。             |
+| 8   | **消遣** | Submission | 放空、无脑、消磨时间 | "关掉脑子"的轻松愉悦，让玩家放松地消磨时间。                             |
+
+---
+
+## 四、在 Playable Ad 中的适用度评估
+
+Playable Ad 的典型场景是 **15-30 秒**、**单人**、**即点即玩**、**以转化为目标**。基于这些约束：
+
+| 乐趣类型               | 适用度     | 原因                                             |
+| ---------------------- | ---------- | ------------------------------------------------ |
+| **Sensation（感官）**  | ⭐⭐⭐⭐⭐ | 核心。视听反馈是 15 秒内让玩家"爽"的最快途径。   |
+| **Challenge（挑战）**  | ⭐⭐⭐⭐⭐ | 核心。"差一点就赢了"的挫折感是转化的最大驱动力。 |
+| **Submission（消遣）** | ⭐⭐⭐⭐   | 非常适合休闲消除类。"无脑但上瘾"的循环。         |
+| **Discovery（探索）**  | ⭐⭐⭐     | 适合翻转、解谜类。发现匹配/路径的"啊哈"时刻。    |
+| **Fantasy（幻想）**    | ⭐⭐       | 时间太短难以建立深度代入，但简单的主题包装可以。 |
+| **Expression（表达）** | ⭐⭐       | 时间太短难以展开，但简单的选择（如选角色）可以。 |
+| **Narrative（叙事）**  | ⭐         | 几乎不适用。15 秒无法讲好一个故事。              |
+| **Fellowship（社交）** | ⭐         | 几乎不适用。Playable Ad 是单人体验。             |
+
+### 设计启发问题
+
+在 Brainstorm 阶段，可以用以下问题引导设计方向：
+
+1. **"这个游戏主要打哪 2-3 种乐趣？"** — 确定主攻方向
+2. **"玩家在第 5 秒会感受到什么情感？"** — 确保开头有足够的 hook
+3. **"15 秒内能体验到至少一次完整的情感循环吗？"** — 确保时长内有完整体验
+4. **"失败时玩家会觉得'差一点就行了'还是'完全没懂'？"** — 诊断挑战性设计是否到位
+
+---
+
+## 五、MDA 的设计方法论
+
+### 从 Aesthetics 出发倒推设计
+
+MDA 框架最有价值的用法不是从 M 推到 A，而是**从 A 反推到 M**：
+
+```
+1. 确定目标情感（Aesthetics）
+   → "我希望玩家感到满足感 + 轻度挑战"
+
+2. 设想需要的动态行为（Dynamics）
+   → "连锁消除带来满足感，有限步数带来挑战"
+
+3. 设计支撑这些行为的规则（Mechanics）
+   → "重力填充 + 匹配规则产生连锁；步数限制产生紧迫"
+```
+
+### 用 MDA 诊断问题
+
+当游戏"感觉不对"时，MDA 提供了诊断路径：
+
+| 症状                   | 可能的问题层    | 诊断方向                                            |
+| ---------------------- | --------------- | --------------------------------------------------- |
+| "好看但无聊"           | Aesthetics 缺失 | 你瞄准了什么情感？Sensation 有了但 Challenge 没有？ |
+| "有策略深度但没人想玩" | Dynamics 问题   | 涌现行为是否有趣？玩家能发现策略吗？                |
+| "概念好但执行差"       | Mechanics 问题  | 规则是否能产生你想要的 Dynamics？                   |
+
+---
+
+## 六、参考资源
+
+- 📄 **原始论文** (2004)：[ResearchGate](https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research)
+- 📖 **知乎中文翻译**：[MDA 框架详解](https://zhuanlan.zhihu.com/p/402577913)
+- 🎓 **教育版解读**：[Educational Game Design](https://educationalgamedesign.com/mechanics-dynamics-and-aesthetics-mda-framework-by-hunicke-leblanc-and-zubek.html)
+- 🛠️ **设计工具箱**：[Game Design Toolkit - MDA Framework](https://tkdev.dss.cloud/gamedesign/toolkit/mda-framework/)