cmr-mini/doc/archive/experience/内容体验层方案.md

游戏中文创体验层方案

文档版本：v1.0 最后更新：2026-04-02 08:28:05

1. 目标

为游戏过程中的文创内容建立一层独立承载能力，不把内容弹窗、图文卡片、讲解信息散落在：

• 规则层
• 页面层
• HUD 逻辑
• 反馈层

这层的目标是：

• 在正确时机触发内容体验
• 统一内容展示方式
• 可配置、可复用、可扩展
• 不破坏当前地图与规则主链

一句话：

把“中途内容体验”从临时弹窗提升为正式能力层。

---

2. 当前现状

当前项目已经具备一部分基础：

• control.displayContent
• UiEffectDirector.showContentCard(...)
• 页面层已有 contentCardVisible / contentCardTitle / contentCardBody
• 打点完成后可展示内容卡

这说明：

• 内容展示能力已经有雏形
• 但触发方式还偏单一
• 内容形式也还比较轻
• 还没有形成正式的“内容体验层”模型

---

3. 设计原则

3.1 内容体验不等于短反馈

短反馈仍然属于：

• 音效
• 震动
• HUD 提示
• 地图 pulse

文创体验属于更重的一层，应与 FeedbackDirector 区分。

3.2 内容体验不直接写死在规则里

规则层只负责：

• 是否触发
• 触发什么体验条目

规则层不负责：

• 页面怎么弹
• 卡片长什么样
• 是否带图片、音频、讲解按钮

3.3 内容体验必须配置驱动

以后不同活动、不同地图、不同玩法需要不同内容。

所以这层必须可配置：

• 哪个点触发
• 何时触发
• 弹什么
• 是否只弹一次
• 优先级如何

---

4. 建议的新层级

建议增加一层：

• ContentExperienceLayer

放在概念上与这些层并列：

• MapPresentation
• HUD
• Feedback
• ResultScene

职责：

• 接收体验触发
• 管理当前激活内容项
• 控制展示与关闭
• 向页面层输出当前体验模型

---

5. 建议的数据模型

5.1 ExperienceEntry

type ExperienceTrigger =
  | 'control_completed'
  | 'zone_entered'
  | 'session_finished'
  | 'manual'

type ExperienceDisplayMode =
  | 'content-card'
  | 'full-panel'
  | 'audio-guide'
  | 'unlock-card'

interface ExperienceEntry {
  id: string
  trigger: ExperienceTrigger
  controlId?: string
  zoneId?: string
  title: string
  body: string
  imageRef?: string
  audioRef?: string
  displayMode: ExperienceDisplayMode
  once: boolean
  priority: number
}

5.2 ExperienceRuntimeState

interface ExperienceRuntimeState {
  activeEntryId: string | null
  dismissedEntryIds: string[]
  consumedEntryIds: string[]
}

---

6. 配置建议

建议在配置中增加一段：

{
  "resources": {
    "contentEntries": {
      "cp-3-story": {
        "title": "校史地标",
        "body": "这里是校园历史演变的重要节点。",
        "imageRef": "content/campus-history-01.png",
        "displayMode": "content-card"
      }
    }
  },
  "game": {
    "experience": {
      "entries": [
        {
          "id": "cp-3-story",
          "trigger": "control_completed",
          "controlId": "control-3",
          "once": true,
          "priority": 10
        }
      ]
    }
  }
}

这意味着：

• 资源层管理内容资源
• 玩法配置决定何时触发

---

7. 触发来源

第一阶段建议支持 3 种触发：

7.1 打点完成触发

最适合当前项目，价值最高。

例如：

• 完成某个控制点后弹一张文创卡
• 开始点完成后弹赛事导览卡
• 终点完成后弹纪念卡

7.2 区域进入触发

适合后续：

• 地标介绍
• 迷雾探索
• 特定区域故事点

7.3 结算后解锁触发

适合后续与结算页联动：

• 收藏卡
• 奖章
• 文创奖励

---

8. 页面表现建议

第一阶段先做最小闭环，不追求复杂视觉。

8.1 第一阶段

支持：

• 当前已有的 content-card
• 标题
• 正文
• 关闭

8.2 第二阶段

再支持：

• 图片
• 按钮
• 章节式展开
• 音频讲解

---

9. 与当前架构的关系

规则层

负责：

• 触发某条体验事件

不负责：

• 具体展示细节

Feedback

继续负责：

• 短反馈
• 动效
• 音效

ContentExperienceLayer

负责：

• 中等时长的信息体验

页面层

负责：

• 渲染当前体验模型

---

10. 第一阶段最小实施范围

建议第一阶段只做：

1. control_completed -> experience entry
2. content-card 展示
3. once 语义
4. 手动关闭
5. 配置驱动

不要一上来做：

• 图片轮播
• 视频
• 复杂音频控制
• 多层交互

---

11. 推荐实施顺序

1. 定义 ExperienceEntry
2. 在配置解析层接 game.experience.entries
3. 在规则完成事件里派发体验触发
4. MapEngine 增加体验状态承载
5. 页面层继续复用当前 content-card
6. 再逐步升级 UI

---

12. 长期价值

这层建好后，后续可以自然承接：

• 文创卡片
• 地标解说
• 解锁收藏
• 故事节点
• 活动内品牌内容

它不只服务当前顺序赛/积分赛，而是服务整条产品体验链。

---

13. 结论

当前最正确的方向不是继续在页面里零散补内容弹窗，而是：

把游戏中途的文创与故事体验正式抽成一层独立的 ContentExperienceLayer。

第一阶段先用“控制点完成触发内容卡”跑通最小闭环，后面再逐步扩成完整体验系统。