249 lines
7.0 KiB
Markdown
249 lines
7.0 KiB
Markdown
# 14 · 叙事系统规范
|
||
|
||
> **所属文档集** [← 返回索引](./README.md)
|
||
> **摘要**：对话系统、世界标记、NPC 状态管理与三结局触发逻辑。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [叙事设计原则](#1-叙事设计原则)
|
||
2. [对话系统](#2-对话系统)
|
||
3. [世界标记系统](#3-世界标记系统)
|
||
4. [NPC 状态管理](#4-npc-状态管理)
|
||
5. [任务系统](#5-任务系统)
|
||
6. [结局触发系统](#6-结局触发系统)
|
||
7. [叙事事件目录](#7-叙事事件目录)
|
||
|
||
---
|
||
|
||
## 1. 叙事设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **环境叙事优先** | 通过场景、图鉴和道具描述讲述故事，减少强制对话 |
|
||
| **非线性探索** | 玩家可按任意顺序解锁叙事内容 |
|
||
| **状态感知** | NPC 的对话随玩家进程改变（不重复同一句话）|
|
||
| **数据驱动** | 所有对话树、条件和触发均为数据，不硬编码 |
|
||
|
||
---
|
||
|
||
## 2. 对话系统
|
||
|
||
### 2.1 对话数据模型
|
||
|
||
```
|
||
DataModel DialogueData {
|
||
dialogueId : ID
|
||
speakerId : ID // NPC ID 或 "player"
|
||
──────────────────────────────────
|
||
nodes : List<DialogueNode>
|
||
entryNodeId : ID // 起始节点
|
||
}
|
||
|
||
DataModel DialogueNode {
|
||
nodeId : ID
|
||
type : DialogueNodeType // Text / Choice / Condition / Action
|
||
──────────────────────────────────
|
||
// type = Text:
|
||
text : Optional<String> // 支持本地化 Key
|
||
portrait : Optional<PortraitID>
|
||
nextNodeId : Optional<ID> // null = 对话结束
|
||
|
||
// type = Choice:
|
||
choices : Optional<List<DialogueChoice>>
|
||
|
||
// type = Condition:
|
||
condition : Optional<DialogueCondition>
|
||
trueNodeId : Optional<ID>
|
||
falseNodeId : Optional<ID>
|
||
|
||
// type = Action:
|
||
action : Optional<DialogueAction>
|
||
nextNodeId : Optional<ID>
|
||
}
|
||
|
||
DataModel DialogueChoice {
|
||
choiceText : String
|
||
nextNodeId : ID
|
||
availableCondition: Optional<DialogueCondition> // null=始终显示
|
||
}
|
||
```
|
||
|
||
### 2.2 对话条件类型
|
||
|
||
```
|
||
DataModel DialogueCondition {
|
||
conditionType : DialogueConditionType
|
||
targetId : Optional<ID>
|
||
value : Optional<Number>
|
||
}
|
||
```
|
||
|
||
| 条件类型 | 说明 |
|
||
|---------|------|
|
||
| `HasAbility` | 玩家已解锁某能力 |
|
||
| `HasItem` | 玩家持有某物品 |
|
||
| `WorldFlagTrue` | 某世界标记为 true |
|
||
| `QuestStageIs` | 某任务处于指定阶段 |
|
||
| `BossDefeated` | 某 Boss 已被击败 |
|
||
| `FirstVisit` | 玩家第一次和此 NPC 对话 |
|
||
|
||
### 2.3 对话动作类型
|
||
|
||
| 动作类型 | 说明 |
|
||
|---------|------|
|
||
| `SetWorldFlag` | 设置世界标记 |
|
||
| `GiveItem` | 给予物品 |
|
||
| `GiveGeo` | 给予 Geo |
|
||
| `UnlockAbility` | 解锁能力 |
|
||
| `AdvanceQuest` | 推进任务阶段 |
|
||
| `PlayCutscene` | 播放过场动画 |
|
||
|
||
---
|
||
|
||
## 3. 世界标记系统
|
||
|
||
### 3.1 世界标记规范
|
||
|
||
```
|
||
WorldFlags: Map<String, Boolean>
|
||
```
|
||
|
||
- 存储于 `ProgressionSaveData.worldFlags`
|
||
- Key 为字符串，建议命名格式：`区域_事件_描述`（如 `region1_boss_firstEncounter`）
|
||
- 标记只能设为 true，不支持撤销（设计保证单向性）
|
||
- 叙事系统、门控系统、AI 系统均可读取世界标记
|
||
|
||
### 3.2 设置世界标记的来源
|
||
|
||
| 来源 | 说明 |
|
||
|------|------|
|
||
| 对话动作 `SetWorldFlag` | 对话选择/到达某节点时触发 |
|
||
| 门控开启 | 某些门控开启时自动设置 |
|
||
| Boss 死亡 | OnBossDefeated 事件触发时自动设置 |
|
||
| 收集品拾取 | 特定关键收集品触发 |
|
||
| 手动触发器 | 场景中的触发区域触碰时 |
|
||
|
||
---
|
||
|
||
## 4. NPC 状态管理
|
||
|
||
### 4.1 NPC 数据模型
|
||
|
||
```
|
||
DataModel NPCData {
|
||
npcId : ID
|
||
displayName : String
|
||
──────────────────────────────────
|
||
locations : List<NPCLocationEntry> // NPC 在不同阶段的位置
|
||
dialogueVersions: List<NPCDialogueVersion> // 不同进程阶段的对话
|
||
}
|
||
|
||
DataModel NPCLocationEntry {
|
||
condition : Optional<DialogueCondition> // 满足时位于此处（null=默认）
|
||
roomId : ID
|
||
position : Vector2
|
||
}
|
||
|
||
DataModel NPCDialogueVersion {
|
||
condition : Optional<DialogueCondition> // 满足时使用此对话（null=默认）
|
||
dialogueId : ID
|
||
priority : Integer // 多个条件同时满足时取最高优先级
|
||
}
|
||
```
|
||
|
||
### 4.2 对话版本选取规则
|
||
|
||
```
|
||
玩家与 NPC 交互时:
|
||
|
||
枚举 NPCData.dialogueVersions（按 priority 降序）
|
||
→ 找第一个 condition 满足（或 condition 为 null）的版本
|
||
→ 使用该版本的 dialogueId 开始对话
|
||
|
||
若无任何版本满足 → 使用默认兜底对话（"......"）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 任务系统
|
||
|
||
### 5.1 任务数据模型
|
||
|
||
```
|
||
DataModel QuestData {
|
||
questId : ID
|
||
displayName : String
|
||
description : String
|
||
──────────────────────────────────
|
||
stages : List<QuestStageData>
|
||
rewardOnComplete: Optional<QuestReward>
|
||
}
|
||
|
||
DataModel QuestStageData {
|
||
stageIndex : Integer
|
||
description : String
|
||
completionCondition: DialogueCondition // 推进到下一阶段的条件
|
||
}
|
||
|
||
DataModel QuestReward {
|
||
geoAmount : Optional<Integer>
|
||
itemIds : List<ID>
|
||
abilityId : Optional<ID>
|
||
worldFlagsToSet : List<String>
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 结局触发系统
|
||
|
||
### 6.1 结局条件回顾
|
||
|
||
（详细条件见 [09_ProgressionSystem.md](09_ProgressionSystem.md) 第 5 节）
|
||
|
||
| 结局 | 类型 | 核心条件 |
|
||
|------|------|---------|
|
||
| 结局 A | 普通 | 击败最终 Boss |
|
||
| 结局 B | 完全 | Boss 全清 + 主线剧情完整 + 关键 NPC 任务 |
|
||
| 结局 C | 隐藏 | 结局 B + 隐藏世界标记序列激活 |
|
||
|
||
### 6.2 结局判定流程
|
||
|
||
```
|
||
最终 Boss 死亡时:
|
||
|
||
检查结局 C 条件（最严格）
|
||
├─ 满足 → 触发结局 C
|
||
└─ 不满足 →
|
||
|
||
检查结局 B 条件
|
||
├─ 满足 → 触发结局 B
|
||
└─ 不满足 → 触发结局 A
|
||
|
||
触发结局 X:
|
||
→ 发出 OnEndingTriggered 事件（endingType）
|
||
→ 播放对应过场动画序列
|
||
→ 记录到 SaveData（endingUnlocked）
|
||
→ 游戏结束流程
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 叙事事件目录
|
||
|
||
| 事件 | 触发时机 | 载荷 |
|
||
|------|---------|------|
|
||
| `OnDialogueStarted` | 开始对话 | `dialogueId, npcId` |
|
||
| `OnDialogueNodeReached` | 到达对话节点 | `nodeId` |
|
||
| `OnDialogueChoiceMade` | 玩家做出选择 | `choiceIndex, nextNodeId` |
|
||
| `OnDialogueEnded` | 对话结束 | `dialogueId` |
|
||
| `OnWorldFlagSet` | 世界标记变更 | `flagKey` |
|
||
| `OnQuestStarted` | 任务开始 | `questId` |
|
||
| `OnQuestAdvanced` | 任务推进 | `questId, newStage` |
|
||
| `OnQuestCompleted` | 任务完成 | `questId` |
|
||
| `OnEndingTriggered` | 结局触发 | `endingType` |
|
||
| `OnCutsceneStarted` | 过场动画开始 | `cutsceneId` |
|
||
| `OnCutsceneEnded` | 过场动画结束 | `cutsceneId` |
|