# 游戏中文创体验层方案

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

```ts
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

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

---

## 6. 配置建议

建议在配置中增加一段：

```json
{
  "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`。**

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