--- id: "kb-gd-033" title: "叙事架构代码实现指南" schema_type: "TechArticle" category: "game-development" language: "zh" confidence: "high" confidence_rationale: "游戏开发领域系统性知识，基于行业标准和实践经验" last_verified: "2026-04-28" generation_method: "human_only" derived_from_human_seed: true tags: ["narrative", "code", "architecture", "implementation"] summary: "叙事架构代码示例：Etudes系统、对话树、变量管理、分支剧情实现" primary_sources: - title: "游戏开发Wiki（个人知识库）" type: "knowledge_base" year: 2026 note: "基于行业实践和标准参考文献的系统性整理" secondary_sources: - title: "GDC Vault" type: "conference" year: 2026 url: "https://www.gdconf.com/" institution: "GDC" completeness: 0.85 related_entities: - "entity:game-development" ai_citations: last_citation_check: "2026-05-22" --- # 叙事架构代码实现指南 本文档提供游戏叙事系统的核心代码实现示例，覆盖 Etudes 层级化状态机、对话树、变量管理和分支剧情等关键模块。所有代码均可直接运行或稍作修改后集成到项目中。 --- ## 目录 1. [Etudes 系统（Owlcat Games）](#1-etudes-系统owlcat-games) 2. [对话系统代码结构](#2-对话系统代码结构) 3. [变量管理方案](#3-变量管理方案) 4. [分支剧情代码示例](#4-分支剧情代码示例) 5. [叙事工具集成](#5-叙事工具集成) --- ## 1. Etudes 系统（Owlcat Games） Owlcat Games 在《开拓者》系列中使用 Etudes 系统替代传统全局 Flag，管理超过 30,000 个叙事变量。Etudes 是层级化的状态机，通过优先级排序和冲突检测实现可控的叙事状态管理。 ### 1.1 核心概念：层级化状态机 与传统扁平的布尔 Flag 不同，Etudes 使用树状结构组织叙事状态。每个节点代表一个叙事片段或状态，子节点继承父节点的上下文。 ```csharp // Etudes系统核心数据模型（C#） using System; using System.Collections.Generic; using System.Linq; namespace NarrativeSystem.Etudes { /// /// Etude节点状态枚举 /// public enum EtudeState { Inactive, // 未激活（灰色） Pending, // 等待条件满足（橙色） Active // 已激活（绿色） } /// /// Etude优先级定义 /// 高优先级Etude可以覆盖低优先级的状态变更 /// public enum EtudePriority { Background = 0, // 背景叙事，最低优先级 Normal = 100, // 普通任务 Important = 200, // 重要剧情 Critical = 300, // 关键节点，最高优先级 Blocking = 400 // 阻塞级，暂停其他叙事 } /// /// Etude节点：叙事状态的基本单位 /// public class EtudeNode { public string Id { get; set; } // 唯一标识符 public string Name { get; set; } // 显示名称 public string Description { get; set; } // 描述 public EtudePriority Priority { get; set; } // 优先级 public EtudeState State { get; private set; } // 当前状态 public EtudeNode Parent { get; set; } // 父节点 public List Children { get; set; } // 子节点列表 public List Conditions { get; set; } // 激活条件 public List OnActivate { get; set; } // 激活时动作 public List OnDeactivate { get; set; } // 取消激活时动作 // 冲突规则：哪些Etude与此节点互斥 public List ConflictsWith { get; set; } public EtudeNode() { Children = new List(); Conditions = new List(); OnActivate = new List(); OnDeactivate = new List(); ConflictsWith = new List(); State = EtudeState.Inactive; } /// /// 评估当前节点是否应该激活 /// 同时检查父节点状态和自身条件 /// public bool Evaluate(EtudeManager manager) { // 如果父节点未激活，子节点不能激活 if (Parent != null && Parent.State != EtudeState.Active) return false; // 检查所有条件是否满足 return Conditions.All(c => c.Check(manager)); } /// /// 激活此Etude节点 /// public void Activate(EtudeManager manager) { if (State == EtudeState.Active) return; State = EtudeState.Active; foreach (var action in OnActivate) { action.Execute(manager); } } /// /// 取消激活此Etude节点 /// public void Deactivate(EtudeManager manager) { if (State == EtudeState.Inactive) return; // 递归取消激活所有子节点 foreach (var child in Children) { child.Deactivate(manager); } State = EtudeState.Inactive; foreach (var action in OnDeactivate) { action.Execute(manager); } } } /// /// 条件接口：所有激活条件必须实现 /// public interface IEtudeCondition { bool Check(EtudeManager manager); } /// /// 动作接口：激活/取消激活时执行的操作 /// public interface IEtudeAction { void Execute(EtudeManager manager); } } ``` ### 1.2 JSON 配置示例 Etudes 适合通过数据驱动配置，策划可以在 JSON 中定义复杂的叙事状态树。 ```json { "$schema": "etude-config-v1", "description": "第一章主线任务Etudes配置", "rootEtudes": [ { "id": "chapter_01", "name": "第一章：觉醒", "description": "游戏开场章节", "priority": "Normal", "conditions": [ { "type": "GameStarted", "value": true } ], "onActivate": [ { "type": "SetFlag", "key": "chapter", "value": 1 }, { "type": "UnlockMap", "mapId": "village" } ], "children": [ { "id": "c01_intro", "name": "开场动画", "priority": "Critical", "conditions": [ { "type": "EtudeActive", "etudeId": "chapter_01" } ], "onActivate": [ { "type": "PlayCutscene", "cutsceneId": "intro_01" } ], "children": [ { "id": "c01_talk_elder", "name": "与长老对话", "priority": "Important", "conditions": [ { "type": "CutsceneFinished", "cutsceneId": "intro_01" } ], "onActivate": [ { "type": "SpawnNPC", "npcId": "elder", "location": "village_center" }, { "type": "AddDialogueOption", "npcId": "elder", "dialogueId": "c01_greeting" } ] }, { "id": "c01_find_artifact", "name": "寻找古代遗物", "priority": "Important", "conditions": [ { "type": "DialogueCompleted", "dialogueId": "c01_greeting" } ], "onActivate": [ { "type": "AddQuest", "questId": "q01_artifact" }, { "type": "SpawnItem", "itemId": "ancient_artifact", "location": "cave_depths" } ] } ] }, { "id": "c01_secret_ending", "name": "隐藏结局触发", "priority": "Critical", "conditions": [ { "type": "FlagEquals", "key": "karma", "value": -100 }, { "type": "EtudeActive", "etudeId": "chapter_01" } ], "conflictsWith": ["c01_intro"], "onActivate": [ { "type": "TriggerEnding", "endingId": "secret_dark" } ] } ] } ] } ``` ### 1.3 优先级排序与冲突检测 ```csharp using System; using System.Collections.Generic; using System.Linq; namespace NarrativeSystem.Etudes { /// /// Etudes管理器：核心控制器 /// 每帧或每个叙事事件发生时重新评估所有Etude状态 /// public class EtudeManager { // 所有已注册的Etude节点 private Dictionary _etudes = new Dictionary(); // 全局变量存储 private Dictionary _globalFlags = new Dictionary(); // 冲突日志，用于调试 public List ConflictLogs { get; private set; } = new List(); /// /// 注册Etude节点到管理器 /// public void RegisterEtude(EtudeNode etude) { if (_etudes.ContainsKey(etude.Id)) { throw new ArgumentException($"Etude {etude.Id} 已存在！"); } _etudes[etude.Id] = etude; } /// /// 设置全局变量 /// public void SetFlag(string key, object value) { _globalFlags[key] = value; // 变量变更后重新评估所有Etude ReevaluateAll(); } /// /// 获取全局变量 /// public T GetFlag(string key) { if (_globalFlags.TryGetValue(key, out var value) && value is T typed) { return typed; } return default; } /// /// 核心评估方法 /// 1. 按优先级排序所有待激活Etude /// 2. 检测冲突 /// 3. 执行状态变更 /// public void ReevaluateAll() { // 收集所有可以激活的Etude（条件满足） var candidates = new List(); foreach (var etude in _etudes.Values) { if (etude.Evaluate(this)) { candidates.Add(etude); } else if (etude.State == EtudeState.Active) { // 如果已激活但条件不再满足，取消激活 etude.Deactivate(this); } } // 按优先级降序排序：高优先级先处理 candidates.Sort((a, b) => b.Priority.CompareTo(a.Priority)); // 已激活的Etude集合（用于冲突检测） var activatedIds = new HashSet(); ConflictLogs.Clear(); foreach (var candidate in candidates) { // 检查是否与已激活的Etude冲突 bool hasConflict = false; foreach (var conflictId in candidate.ConflictsWith) { if (activatedIds.Contains(conflictId)) { hasConflict = true; ConflictLogs.Add(new ConflictLog { EtudeA = candidate.Id, EtudeB = conflictId, Resolution = candidate.Priority >= _etudes[conflictId].Priority ? "高优先级覆盖" : "低优先级被跳过" }); // 如果当前优先级更高，覆盖冲突的Etude if (candidate.Priority >= _etudes[conflictId].Priority) { _etudes[conflictId].Deactivate(this); activatedIds.Remove(conflictId); } else { // 优先级低，跳过此候选 break; } } } if (!hasConflict || candidate.Priority >= candidate.ConflictsWith .Where(c => activatedIds.Contains(c)) .Select(c => _etudes[c].Priority) .DefaultIfEmpty(EtudePriority.Background) .Max()) { candidate.Activate(this); activatedIds.Add(candidate.Id); } } } } /// /// 冲突记录，用于可视化调试 /// public class ConflictLog { public string EtudeA { get; set; } public string EtudeB { get; set; } public string Resolution { get; set; } public DateTime Timestamp { get; set; } = DateTime.Now; } } ``` ### 1.4 可视化调试工具 ```python # Etudes 状态树可视化（Python + 命令行） # 可用于运行时调试，输出类似文件树的结构 # 绿色 = Active, 橙色 = Pending, 灰色 = Inactive from enum import Enum from typing import List, Dict, Optional from dataclasses import dataclass, field class EtudeState(Enum): INACTIVE = "inactive" PENDING = "pending" ACTIVE = "active" # ANSI 颜色代码 COLOR_MAP = { EtudeState.ACTIVE: "\033[32m", # 绿色 EtudeState.PENDING: "\033[33m", # 橙色 EtudeState.INACTIVE: "\033[90m", # 灰色 } RESET = "\033[0m" @dataclass class EtudeNode: id: str name: str state: EtudeState priority: int = 100 children: List['EtudeNode'] = field(default_factory=list) conflicts: List[str] = field(default_factory=list) class EtudeVisualizer: """Etudes 状态树可视化器""" def __init__(self, root_nodes: List[EtudeNode]): self.roots = root_nodes self.conflict_logs: List[Dict] = [] def _colorize(self, text: str, state: EtudeState) -> str: """根据状态给文本上色""" return f"{COLOR_MAP[state]}{text}{RESET}" def _render_node(self, node: EtudeNode, prefix: str = "", is_last: bool = True) -> str: """递归渲染单个节点""" connector = "└── " if is_last else "├── " state_icon = { EtudeState.ACTIVE: "[+]", EtudeState.PENDING: "[~]", EtudeState.INACTIVE: "[ ]", }[node.state] line = f"{prefix}{connector}{state_icon} {node.name} ({node.id})" colored_line = self._colorize(line, node.state) # 如果有冲突，附加警告 if node.conflicts and node.state == EtudeState.ACTIVE: conflict_info = f" [冲突: {', '.join(node.conflicts)}]" colored_line += self._colorize(conflict_info, EtudeState.PENDING) result = [colored_line] # 递归渲染子节点 child_prefix = prefix + (" " if is_last else "│ ") for i, child in enumerate(node.children): is_last_child = (i == len(node.children) - 1) result.append(self._render_node(child, child_prefix, is_last_child)) return "\n".join(result) def render(self) -> str: """渲染完整的Etudes状态树""" lines = [] lines.append("=" * 50) lines.append("Etudes 状态树可视化") lines.append(f"图例: {self._colorize('[+] 激活', EtudeState.ACTIVE)} | " f"{self._colorize('[~] 等待', EtudeState.PENDING)} | " f"{self._colorize('[ ] 未激活', EtudeState.INACTIVE)}") lines.append("=" * 50) for root in self.roots: lines.append(self._render_node(root)) lines.append("") # 输出冲突日志 if self.conflict_logs: lines.append("-" * 50) lines.append("冲突日志:") for log in self.conflict_logs: lines.append(f" [{log['timestamp']}] {log['a']} vs {log['b']}: {log['resolution']}") return "\n".join(lines) # ===== 使用示例 ===== if __name__ == "__main__": # 构建示例Etudes树 child1 = EtudeNode("c01_talk", "与长老对话", EtudeState.ACTIVE, priority=200) child2 = EtudeNode("c01_fight", "战斗事件", EtudeState.INACTIVE, priority=150) root = EtudeNode("chapter_01", "第一章：觉醒", EtudeState.ACTIVE, priority=100, children=[child1, child2], conflicts=["chapter_02"]) visualizer = EtudeVisualizer([root]) visualizer.conflict_logs = [ {"timestamp": "10:23:05", "a": "chapter_01", "b": "chapter_02", "resolution": "高优先级覆盖"} ] print(visualizer.render()) ``` **可视化输出示例：** ```text ================================================== Etudes 状态树可视化 图例: [+] 激活 | [~] 等待 | [ ] 未激活 ================================================== └── [+] 第一章：觉醒 (chapter_01) [冲突: chapter_02] ├── [+] 与长老对话 (c01_talk) └── [ ] 战斗事件 (c01_fight) -------------------------------------------------- 冲突日志: [10:23:05] chapter_01 vs chapter_02: 高优先级覆盖 ``` --- ## 2. 对话系统代码结构 ### 2.1 对话树数据结构 ```csharp // 对话树核心数据结构（C#） using System; using System.Collections.Generic; using System.Linq; namespace NarrativeSystem.Dialogue { /// /// 对话节点基类 /// 所有对话节点（文本、选择、条件、动作）的抽象基类 /// public abstract class DialogueNode { public string Id { get; set; } public string OwnerId { get; set; } // 说话者ID public List NextNodes { get; set; } = new List(); public List Conditions { get; set; } = new List(); /// /// 检查此节点是否可以显示 /// public virtual bool CanDisplay(IDialogueContext context) { return Conditions.All(c => c.Evaluate(context)); } /// /// 节点被访问时执行 /// public abstract void OnVisit(IDialogueContext context); } /// /// 文本节点：显示NPC对话文本 /// public class TextNode : DialogueNode { public string Text { get; set; } // 对话文本（支持本地化Key） public string Emotion { get; set; } // 情绪标签（影响立绘/动画） public float AutoAdvanceDelay { get; set; } // 自动推进延迟（-1表示手动） public override void OnVisit(IDialogueContext context) { context.DisplayText(OwnerId, Text, Emotion); if (AutoAdvanceDelay > 0) { context.ScheduleAdvance(AutoAdvanceDelay, NextNodes.FirstOrDefault()); } } } /// /// 玩家选择节点：提供分支选项 /// public class ChoiceNode : DialogueNode { public List Choices { get; set; } = new List(); public override void OnVisit(IDialogueContext context) { // 过滤掉不满足条件的选项 var availableChoices = Choices.Where(c => c.CanDisplay(context)).ToList(); context.DisplayChoices(availableChoices); } } /// /// 单个选项定义 /// public class DialogueChoice { public string Id { get; set; } public string Text { get; set; } public string Tooltip { get; set; } // 鼠标悬停提示 public List Conditions { get; set; } = new List(); public List Actions { get; set; } = new List(); public string NextNodeId { get; set; } public bool CanDisplay(IDialogueContext context) { return Conditions.All(c => c.Evaluate(context)); } } /// /// 动作节点：执行无副作用的叙事动作 /// public class ActionNode : DialogueNode { public List Actions { get; set; } = new List(); public override void OnVisit(IDialogueContext context) { foreach (var action in Actions) { action.Execute(context); } // 自动跳转到下一个节点 context.AdvanceTo(NextNodes.FirstOrDefault()); } } /// /// 条件节点：根据条件走向不同分支 /// public class BranchNode : DialogueNode { public List Branches { get; set; } = new List(); public string DefaultNodeId { get; set; } // 默认分支（无条件满足时） public override void OnVisit(IDialogueContext context) { foreach (var branch in Branches) { if (branch.Condition.Evaluate(context)) { context.AdvanceTo(branch.TargetNodeId); return; } } context.AdvanceTo(DefaultNodeId); } } public class ConditionalBranch { public DialogueCondition Condition { get; set; } public string TargetNodeId { get; set; } } } ``` ### 2.2 条件判断系统 ```csharp namespace NarrativeSystem.Dialogue { /// /// 条件接口：所有对话条件的基类 /// public abstract class DialogueCondition { public abstract bool Evaluate(IDialogueContext context); } /// /// 变量比较条件 /// public class VariableCondition : DialogueCondition { public string VariableName { get; set; } public ComparisonOperator Operator { get; set; } public object ExpectedValue { get; set; } public override bool Evaluate(IDialogueContext context) { var actualValue = context.GetVariable(VariableName); return CompareValues(actualValue, ExpectedValue, Operator); } private bool CompareValues(object actual, object expected, ComparisonOperator op) { if (actual == null || expected == null) return false; var comparable = Comparer.Default; int result = comparable.Compare(actual, expected); return op switch { ComparisonOperator.Equals => result == 0, ComparisonOperator.NotEquals => result != 0, ComparisonOperator.GreaterThan => result > 0, ComparisonOperator.LessThan => result < 0, ComparisonOperator.GreaterOrEqual => result >= 0, ComparisonOperator.LessOrEqual => result <= 0, _ => false }; } } /// /// 玩家背包物品检查 /// public class HasItemCondition : DialogueCondition { public string ItemId { get; set; } public int Count { get; set; } = 1; public override bool Evaluate(IDialogueContext context) { return context.GetItemCount(ItemId) >= Count; } } /// /// 关系值条件 /// public class RelationshipCondition : DialogueCondition { public string NpcId { get; set; } public ComparisonOperator Operator { get; set; } public int Value { get; set; } public override bool Evaluate(IDialogueContext context) { var relationship = context.GetRelationship(NpcId); return VariableCondition.CompareValues(relationship, Value, Operator); } } /// /// 复合条件：AND / OR / NOT /// public class CompositeCondition : DialogueCondition { public LogicOperator LogicOp { get; set; } public List SubConditions { get; set; } = new List(); public override bool Evaluate(IDialogueContext context) { return LogicOp switch { LogicOperator.And => SubConditions.All(c => c.Evaluate(context)), LogicOperator.Or => SubConditions.Any(c => c.Evaluate(context)), LogicOperator.Not => !SubConditions.FirstOrDefault()?.Evaluate(context) ?? true, _ => false }; } } public enum ComparisonOperator { Equals, NotEquals, GreaterThan, LessThan, GreaterOrEqual, LessOrEqual } public enum LogicOperator { And, Or, Not } } ``` ### 2.3 变量绑定与上下文 ```csharp namespace NarrativeSystem.Dialogue { /// /// 对话上下文接口：提供对话系统与游戏世界的桥梁 /// public interface IDialogueContext { // 变量访问 object GetVariable(string name); void SetVariable(string name, object value); // 玩家数据 int GetItemCount(string itemId); int GetRelationship(string npcId); // UI 交互 void DisplayText(string speakerId, string text, string emotion); void DisplayChoices(List choices); void AdvanceTo(string nodeId); void ScheduleAdvance(float delay, string nodeId); } /// /// 默认实现：对话上下文 /// public class DefaultDialogueContext : IDialogueContext { private readonly Dictionary _variables; private readonly IGameState _gameState; private readonly IDialogueUI _ui; public DefaultDialogueContext(IGameState gameState, IDialogueUI ui) { _gameState = gameState; _ui = ui; _variables = new Dictionary(); } public object GetVariable(string name) { // 优先从本地对话变量查找，再到全局游戏状态 if (_variables.TryGetValue(name, out var localValue)) return localValue; return _gameState.GetGlobalVariable(name); } public void SetVariable(string name, object value) { _variables[name] = value; // 同步到全局状态（如果需要持久化） _gameState.SetGlobalVariable(name, value); } public int GetItemCount(string itemId) => _gameState.Inventory.GetCount(itemId); public int GetRelationship(string npcId) => _gameState.Relationships.Get(npcId); public void DisplayText(string speakerId, string text, string emotion) { _ui.ShowText(speakerId, Localize(text), emotion); } public void DisplayChoices(List choices) { _ui.ShowChoices(choices.Select(c => new UIChoice { Text = Localize(c.Text), Tooltip = Localize(c.Tooltip), OnSelect = () => SelectChoice(c) }).ToList()); } private void SelectChoice(DialogueChoice choice) { // 执行选项附带的所有动作 foreach (var action in choice.Actions) { action.Execute(this); } AdvanceTo(choice.NextNodeId); } public void AdvanceTo(string nodeId) { if (!string.IsNullOrEmpty(nodeId)) { _ui.Clear(); _gameState.Dialogue.AdvanceToNode(nodeId); } else { _gameState.Dialogue.EndDialogue(); } } public void ScheduleAdvance(float delay, string nodeId) { _ui.ScheduleAfterDelay(delay, () => AdvanceTo(nodeId)); } private string Localize(string key) => _gameState.Localization.Get(key); } } ``` ### 2.4 对话数据 JSON 配置 ```json { "dialogueId": "dlg_elder_greeting", "participants": ["player", "elder"], "entryNode": "node_01", "nodes": { "node_01": { "type": "TextNode", "ownerId": "elder", "text": "TEXT_ELDER_GREETING", "emotion": "neutral", "nextNodes": ["node_02"] }, "node_02": { "type": "ChoiceNode", "choices": [ { "id": "choice_friendly", "text": "TEXT_CHOICE_FRIENDLY", "nextNodeId": "node_friendly", "actions": [ { "type": "ModifyRelationship", "npcId": "elder", "delta": 10 } ] }, { "id": "choice_rude", "text": "TEXT_CHOICE_RUDE", "nextNodeId": "node_rude", "actions": [ { "type": "ModifyRelationship", "npcId": "elder", "delta": -20 } ] }, { "id": "choice_quest", "text": "TEXT_CHOICE_QUEST", "conditions": [ { "type": "HasItem", "itemId": "ancient_artifact", "count": 1 } ], "nextNodeId": "node_quest_complete", "actions": [ { "type": "RemoveItem", "itemId": "ancient_artifact", "count": 1 }, { "type": "CompleteQuest", "questId": "q01_artifact" } ] } ] }, "node_friendly": { "type": "TextNode", "ownerId": "elder", "text": "TEXT_ELDER_FRIENDLY", "emotion": "happy", "nextNodes": ["node_end"] }, "node_rude": { "type": "TextNode", "ownerId": "elder", "text": "TEXT_ELDER_ANGRY", "emotion": "angry", "nextNodes": ["node_end"] }, "node_quest_complete": { "type": "TextNode", "ownerId": "elder", "text": "TEXT_ELDER_QUEST_DONE", "emotion": "surprised", "nextNodes": ["node_reward"] }, "node_reward": { "type": "ActionNode", "actions": [ { "type": "GiveItem", "itemId": "gold", "count": 100 }, { "type": "SetFlag", "key": "elder_quest_done", "value": true } ], "nextNodes": ["node_end"] }, "node_end": { "type": "ActionNode", "actions": [ { "type": "EndDialogue" } ], "nextNodes": [] } } } ``` --- ## 3. 变量管理方案 ### 3.1 全局 Flag 方法（基础版） ```python # 全局 Flag 管理器（Python） # 适用于小型项目，简单直接 from typing import Any, Dict, Optional, Callable, List from dataclasses import dataclass, field from datetime import datetime import json import os @dataclass class FlagChangeEvent: """Flag 变更事件记录""" flag_name: str old_value: Any new_value: Any timestamp: datetime source: str # 触发来源（对话、任务、脚本等） class GlobalFlagManager: """ 全局 Flag 管理器 适用场景：小型项目、原型开发 局限性：变量过多时难以维护，无命名空间隔离 """ def __init__(self): self._flags: Dict[str, Any] = {} self._listeners: Dict[str, List[Callable]] = {} self._history: List[FlagChangeEvent] = [] self._dirty = False # 是否有未保存的变更 def set(self, name: str, value: Any, source: str = "system") -> None: """设置Flag值""" old_value = self._flags.get(name) if old_value != value: self._flags[name] = value self._dirty = True # 记录变更历史 event = FlagChangeEvent(name, old_value, value, datetime.now(), source) self._history.append(event) # 通知监听器 self._notify(name, old_value, value) def get(self, name: str, default: Any = None) -> Any: """获取Flag值""" return self._flags.get(name, default) def toggle(self, name: str) -> bool: """切换布尔Flag""" current = bool(self.get(name, False)) self.set(name, not current, source="toggle") return not current def increment(self, name: str, delta: int = 1) -> int: """数值Flag自增""" current = int(self.get(name, 0)) new_value = current + delta self.set(name, new_value, source="increment") return new_value def add_listener(self, name: str, callback: Callable) -> None: """添加Flag变更监听器""" if name not in self._listeners: self._listeners[name] = [] self._listeners[name].append(callback) def _notify(self, name: str, old_val: Any, new_val: Any) -> None: """触发监听器回调""" for listener in self._listeners.get(name, []): try: listener(name, old_val, new_val) except Exception as e: print(f"[FlagManager] 监听器异常: {e}") def save(self, filepath: str) -> None: """持久化到JSON文件""" data = { "flags": self._flags, "history": [ { "flag": e.flag_name, "from": e.old_value, "to": e.new_value, "time": e.timestamp.isoformat(), "source": e.source } for e in self._history ] } with open(filepath, 'w', encoding='utf-8') as f: json.dump(data, f, ensure_ascii=False, indent=2) self._dirty = False def load(self, filepath: str) -> None: """从JSON文件加载""" if not os.path.exists(filepath): return with open(filepath, 'r', encoding='utf-8') as f: data = json.load(f) self._flags = data.get("flags", {}) self._dirty = False # ===== 使用示例 ===== if __name__ == "__main__": flags = GlobalFlagManager() # 基础操作 flags.set("player_level", 5, source="level_up") flags.set("has_met_elder", True, source="dialogue") # 数值操作 flags.increment("karma", -10) print(f"当前业力值: {flags.get('karma')}") # 监听变更 def on_karma_change(name, old, new): print(f"[事件] {name} 从 {old} 变为 {new}") flags.add_listener("karma", on_karma_change) flags.increment("karma", 5) # 触发回调 # 保存进度 flags.save("save_data.json") ``` ### 3.2 层级化状态机（进阶版） ```python # 层级化命名空间状态机（Python） # 适用于中型到大型项目，解决全局Flag混乱问题 from typing import Any, Dict, List, Optional, Set from dataclasses import dataclass, field from enum import Enum import copy class VariableType(Enum): """变量类型枚举，用于类型安全检查""" BOOL = "bool" INT = "int" FLOAT = "float" STRING = "string" VECTOR = "vector" # 向量/列表 @dataclass class VariableDefinition: """变量定义元数据""" name: str var_type: VariableType default_value: Any description: str = "" persistent: bool = True # 是否持久化保存 sync_to_ui: bool = False # 是否同步到UI class Namespace: """ 命名空间：隔离不同系统的变量 例如：quest.*, player.*, world.*, dialogue.* """ def __init__(self, name: str, parent: Optional['Namespace'] = None): self.name = name self.parent = parent self._variables: Dict[str, Any] = {} self._definitions: Dict[str, VariableDefinition] = {} self._children: Dict[str, 'Namespace'] = {} def define(self, definition: VariableDefinition) -> None: """注册变量定义（应在初始化时调用）""" self._definitions[definition.name] = definition self._variables[definition.name] = copy.deepcopy(definition.default_value) def set(self, name: str, value: Any) -> bool: """ 设置变量值，包含类型检查 返回是否设置成功 """ if name not in self._definitions: raise KeyError(f"变量 {self.name}.{name} 未定义，请先调用 define()") definition = self._definitions[name] if not self._type_check(value, definition.var_type): raise TypeError( f"变量 {self.name}.{name} 类型错误，" f"期望 {definition.var_type.value}，实际 {type(value)}" ) self._variables[name] = value return True def get(self, name: str) -> Any: """获取变量值，如不存在则向上查找父命名空间""" if name in self._variables: return self._variables[name] if self.parent: return self.parent.get(name) raise KeyError(f"变量 {name} 在命名空间 {self.name} 及其父空间中不存在") def get_child(self, name: str) -> 'Namespace': """获取或创建子命名空间""" if name not in self._children: self._children[name] = Namespace(f"{self.name}.{name}", parent=self) return self._children[name] def get_full_path(self, name: str) -> str: """获取变量完整路径""" return f"{self.name}.{name}" def list_all(self) -> Dict[str, Any]: """列出当前命名空间所有变量""" return dict(self._variables) @staticmethod def _type_check(value: Any, expected: VariableType) -> bool: """类型检查""" type_map = { VariableType.BOOL: bool, VariableType.INT: int, VariableType.FLOAT: (int, float), VariableType.STRING: str, VariableType.VECTOR: list, } return isinstance(value, type_map.get(expected, object)) class HierarchicalStateManager: """ 层级化状态管理器 组织形式：root -> player / world / quests / dialogue / etudes """ def __init__(self): self._root = Namespace("root") self._namespaces: Dict[str, Namespace] = {} self._setup_default_namespaces() def _setup_default_namespaces(self): """初始化默认命名空间结构""" # player 命名空间：玩家相关状态 player = self.create_namespace("player") player.define(VariableDefinition("level", VariableType.INT, 1, "玩家等级")) player.define(VariableDefinition("exp", VariableType.INT, 0, "经验值")) player.define(VariableDefinition("name", VariableType.STRING, "", "玩家名称")) # world 命名空间：世界状态 world = self.create_namespace("world") world.define(VariableDefinition("day", VariableType.INT, 1, "游戏天数")) world.define(VariableDefinition("time", VariableType.FLOAT, 8.0, "当前时间")) world.define(VariableDefinition("weather", VariableType.STRING, "sunny", "天气")) # quests 命名空间：任务状态（支持子命名空间） quests = self.create_namespace("quests") # dialogue 命名空间：对话记录 dialogue = self.create_namespace("dialogue") dialogue.define(VariableDefinition("last_speaker", VariableType.STRING, "", "最后对话NPC")) dialogue.define(VariableDefinition("choices_made", VariableType.VECTOR, [], "已做选择记录")) def create_namespace(self, path: str) -> Namespace: """创建命名空间，支持点号路径如 'quests.main'""" parts = path.split(".") current = self._root for part in parts: if part not in current._children: current._children[part] = Namespace(part, parent=current) current = current._children[part] self._namespaces[path] = current return current def get(self, full_path: str) -> Any: """ 通过完整路径获取变量值 格式：namespace.variable 或 namespace.child.variable """ parts = full_path.split(".") if len(parts) < 2: raise ValueError("路径格式错误，应为 'namespace.variable'") # 逐级查找命名空间 current = self._root for part in parts[:-1]: if part not in current._children: raise KeyError(f"命名空间 {part} 不存在") current = current._children[part] return current.get(parts[-1]) def set(self, full_path: str, value: Any) -> None: """通过完整路径设置变量值""" parts = full_path.split(".") if len(parts) < 2: raise ValueError("路径格式错误") current = self._root for part in parts[:-1]: if part not in current._children: raise KeyError(f"命名空间 {part} 不存在") current = current._children[part] current.set(parts[-1], value) def query(self, pattern: str) -> Dict[str, Any]: """ 按模式查询变量 例如：query("quests.*.status") 返回所有任务状态 """ results = {} # 简化的通配符匹配实现 for ns_path, namespace in self._namespaces.items(): for var_name, value in namespace.list_all().items(): full = f"{ns_path}.{var_name}" if ns_path else var_name if self._match_pattern(full, pattern): results[full] = value return results def _match_pattern(self, text: str, pattern: str) -> bool: """简单的通配符匹配""" import fnmatch return fnmatch.fnmatch(text, pattern) def export_namespace(self, path: str) -> Dict[str, Any]: """导出指定命名空间下所有变量（用于保存）""" if path not in self._namespaces: return {} return self._namespaces[path].list_all() # ===== 使用示例 ===== if __name__ == "__main__": manager = HierarchicalStateManager() # 设置玩家数据 manager.set("player.level", 5) manager.set("player.name", "亚瑟") # 设置世界状态 manager.set("world.day", 3) manager.set("world.weather", "rainy") # 动态创建任务子命名空间 q1 = manager.create_namespace("quests.q01_artifact") q1.define(VariableDefinition("status", VariableType.STRING, "active", "任务状态")) q1.define(VariableDefinition("progress", VariableType.INT, 0, "任务进度")) manager.set("quests.q01_artifact.status", "completed") manager.set("quests.q01_artifact.progress", 100) print(f"玩家等级: {manager.get('player.level')}") print(f"任务状态: {manager.get('quests.q01_artifact.status')}") ``` ### 3.3 持久化存储方案 ```csharp // 持久化存储：存档系统（C#） using System; using System.Collections.Generic; using System.IO; using System.Text.Json; using System.Text.Json.Serialization; namespace NarrativeSystem.Persistence { /// /// 存档数据容器 /// public class SaveGameData { [JsonPropertyName("version")] public int Version { get; set; } = 1; [JsonPropertyName("timestamp")] public DateTime Timestamp { get; set; } [JsonPropertyName("playTime")] public float PlayTimeSeconds { get; set; } [JsonPropertyName("variables")] public Dictionary Variables { get; set; } = new(); [JsonPropertyName("etudes")] public List Etudes { get; set; } = new(); [JsonPropertyName("quests")] public List Quests { get; set; } = new(); [JsonPropertyName("dialogueHistory")] public List DialogueHistory { get; set; } = new(); [JsonPropertyName("playerPosition")] public Vector3SaveData PlayerPosition { get; set; } [JsonPropertyName("currentScene")] public string CurrentScene { get; set; } } public class EtudeSaveData { [JsonPropertyName("id")] public string Id { get; set; } [JsonPropertyName("state")] public string State { get; set; } [JsonPropertyName("activationTime")] public DateTime? ActivationTime { get; set; } } public class QuestSaveData { [JsonPropertyName("id")] public string Id { get; set; } [JsonPropertyName("status")] public string Status { get; set; } [JsonPropertyName("objectives")] public List Objectives { get; set; } = new(); } public class ObjectiveSaveData { [JsonPropertyName("id")] public string Id { get; set; } [JsonPropertyName("completed")] public bool Completed { get; set; } [JsonPropertyName("progress")] public int Progress { get; set; } } public class DialogueHistoryEntry { [JsonPropertyName("dialogueId")] public string DialogueId { get; set; } [JsonPropertyName("nodeId")] public string NodeId { get; set; } [JsonPropertyName("choiceId")] public string ChoiceId { get; set; } [JsonPropertyName("timestamp")] public DateTime Timestamp { get; set; } } public class Vector3SaveData { [JsonPropertyName("x")] public float X { get; set; } [JsonPropertyName("y")] public float Y { get; set; } [JsonPropertyName("z")] public float Z { get; set; } } /// /// 存档管理器 /// public class SaveManager { private readonly string _saveDirectory; private readonly JsonSerializerOptions _jsonOptions; public SaveManager(string saveDirectory) { _saveDirectory = saveDirectory; _jsonOptions = new JsonSerializerOptions { WriteIndented = true, PropertyNamingPolicy = JsonNamingPolicy.CamelCase }; if (!Directory.Exists(_saveDirectory)) { Directory.CreateDirectory(_saveDirectory); } } /// /// 保存游戏 /// public void SaveGame(int slot, SaveGameData data) { data.Timestamp = DateTime.UtcNow; var filepath = GetSaveFilePath(slot); var json = JsonSerializer.Serialize(data, _jsonOptions); File.WriteAllText(filepath, json); } /// /// 加载游戏 /// public SaveGameData LoadGame(int slot) { var filepath = GetSaveFilePath(slot); if (!File.Exists(filepath)) { throw new FileNotFoundException($"存档槽 {slot} 不存在"); } var json = File.ReadAllText(filepath); return JsonSerializer.Deserialize(json, _jsonOptions); } /// /// 列出所有存档 /// public List ListSaves() { var saves = new List(); foreach (var file in Directory.GetFiles(_saveDirectory, "save_*.json")) { var slotStr = Path.GetFileNameWithoutExtension(file).Replace("save_", ""); if (int.TryParse(slotStr, out int slot)) { try { var data = LoadGame(slot); saves.Add(new SaveInfo { Slot = slot, Timestamp = data.Timestamp, PlayTime = TimeSpan.FromSeconds(data.PlayTimeSeconds), CurrentScene = data.CurrentScene }); } catch { /* 忽略损坏的存档 */ } } } return saves; } private string GetSaveFilePath(int slot) => Path.Combine(_saveDirectory, $"save_{slot}.json"); } public class SaveInfo { public int Slot { get; set; } public DateTime Timestamp { get; set; } public TimeSpan PlayTime { get; set; } public string CurrentScene { get; set; } } } ``` --- ## 4. 分支剧情代码示例 ### 4.1 简单分支（if-else） ```python # 简单分支剧情实现（Python） # 适用场景：少量分支、快速原型 def simple_branching_example(player_state): """ 简单的if-else分支示例 player_state: 包含玩家选择记录的字典 """ has_saved_village = player_state.get("saved_village", False) has_betrayed_king = player_state.get("betrayed_king", False) karma = player_state.get("karma", 0) # 第一幕：村庄事件 if has_saved_village: print("村民热情地迎接你，孩子们围上来索要糖果。") reward = "village_blessing" else: print("村庄一片废墟，幸存的村民用怨恨的眼神看着你。") reward = "guilt_memory" player_state["act1_reward"] = reward # 第二幕：王座厅 if has_betrayed_king: print("王座厅戒备森严，国王拒绝接见叛徒。") if karma < -50: print("卫兵冲上来逮捕你！") return "arrest_ending" else: print("国王微笑着向你点头。") if karma > 50: print("国王授予你贵族头衔。") player_state["noble_title"] = True return "continue" # 更优雅的数据驱动版本 BRANCH_TABLE = { "village_event": { "conditions": [ {"if": "saved_village", "then": "village_saved_branch"}, {"if": "burned_village", "then": "village_burned_branch"}, ], "default": "village_neutral_branch" }, "village_saved_branch": { "text": "村民热情地迎接你，孩子们围上来索要糖果。", "rewards": ["village_blessing", "+10_karma"], "next": "throne_room" }, "village_burned_branch": { "text": "村庄一片废墟，幸存的村民用怨恨的眼神看着你。", "rewards": ["guilt_memory", "-20_karma"], "next": "throne_room" }, "village_neutral_branch": { "text": "村庄宁静如常，似乎没人注意到你的到来。", "next": "throne_room" } } def evaluate_branch(branch_id, player_state): """评估分支表，返回对应的剧情内容""" branch = BRANCH_TABLE.get(branch_id) if not branch: return None # 检查是否有条件分支 conditions = branch.get("conditions", []) for cond in conditions: flag = cond["if"] if player_state.get(flag, False): return evaluate_branch(cond["then"], player_state) # 返回默认分支 default_id = branch.get("default") if default_id: return evaluate_branch(default_id, player_state) return branch ``` ### 4.2 复杂分支（状态机） ```csharp // 复杂分支剧情状态机（C#） // 适用场景：多结局RPG、复杂叙事网络 using System; using System.Collections.Generic; using System.Linq; namespace NarrativeSystem.Branching { /// /// 故事状态机：管理复杂分支剧情 /// public class StoryStateMachine { private readonly Dictionary _states; private StoryState _currentState; private readonly HashSet _visitedStates; private readonly List _transitionHistory; // 全局变量存储 private readonly Dictionary _variables; // 结局注册表 private readonly Dictionary _endings; public StoryStateMachine() { _states = new Dictionary(); _visitedStates = new HashSet(); _transitionHistory = new List(); _variables = new Dictionary(); _endings = new Dictionary(); } /// /// 注册故事状态 /// public void RegisterState(StoryState state) { _states[state.Id] = state; } /// /// 注册结局 /// public void RegisterEnding(EndingDefinition ending) { _endings[ending.Id] = ending; } /// /// 初始化状态机，进入起始状态 /// public void Start(string initialStateId) { if (!_states.TryGetValue(initialStateId, out _currentState)) { throw new ArgumentException($"初始状态 {initialStateId} 不存在"); } EnterState(_currentState); } /// /// 推进剧情：根据当前状态和变量条件进行转移 /// public void Tick() { if (_currentState == null) return; // 执行当前状态的OnUpdate _currentState.OnUpdate(this); // 检查所有出边转移条件 foreach (var transition in _currentState.Transitions) { if (transition.CanTransition(this)) { ExecuteTransition(transition); return; } } } /// /// 玩家做出选择 /// public void MakeChoice(string choiceId) { var choice = _currentState?.Choices.FirstOrDefault(c => c.Id == choiceId); if (choice == null) return; // 执行选择附带的效果 foreach (var effect in choice.Effects) { effect.Apply(this); } // 记录选择 RecordChoice(choiceId); // 转移到选择指定的下一状态 if (!string.IsNullOrEmpty(choice.TargetStateId)) { TransitionTo(choice.TargetStateId); } } private void ExecuteTransition(StoryTransition transition) { var fromId = _currentState?.Id; TransitionTo(transition.TargetStateId); _transitionHistory.Add(new StoryTransition { FromStateId = fromId, ToStateId = transition.TargetStateId, TriggerType = transition.TriggerType, Timestamp = DateTime.UtcNow }); } private void TransitionTo(string stateId) { if (!_states.TryGetValue(stateId, out var nextState)) { // 检查是否是结局 if (_endings.TryGetValue(stateId, out var ending)) { TriggerEnding(ending); return; } throw new ArgumentException($"目标状态 {stateId} 不存在"); } // 退出当前状态 _currentState?.OnExit(this); // 进入新状态 _currentState = nextState; EnterState(_currentState); } private void EnterState(StoryState state) { _visitedStates.Add(state.Id); state.OnEnter(this); } private void TriggerEnding(EndingDefinition ending) { ending.OnTrigger(this); _currentState = null; // 状态机结束 } // 变量操作 public void SetVariable(string key, object value) => _variables[key] = value; public T GetVariable(string key) => _variables.TryGetValue(key, out var v) ? (T)v : default; public bool HasVisited(string stateId) => _visitedStates.Contains(stateId); public IReadOnlyList GetHistory() => _transitionHistory; private void RecordChoice(string choiceId) { var choices = GetVariable>("_choices") ?? new List(); choices.Add(choiceId); SetVariable("_choices", choices); } } /// /// 故事状态节点 /// public class StoryState { public string Id { get; set; } public string Name { get; set; } public string Description { get; set; } // 自动转移条件（无需玩家选择） public List Transitions { get; set; } = new List(); // 玩家可做的选择 public List Choices { get; set; } = new List(); // 状态生命周期回调 public Action OnEnter { get; set; } = _ => { }; public Action OnUpdate { get; set; } = _ => { }; public Action OnExit { get; set; } = _ => { }; } /// /// 状态转移定义 /// public class StoryTransition { public string TargetStateId { get; set; } public TransitionTriggerType TriggerType { get; set; } public Func Condition { get; set; } public DateTime Timestamp { get; set; } public string FromStateId { get; set; } public string ToStateId { get; set; } public bool CanTransition(StoryStateMachine machine) => Condition?.Invoke(machine) ?? true; } /// /// 玩家选择定义 /// public class PlayerChoice { public string Id { get; set; } public string Text { get; set; } public string Tooltip { get; set; } public List Effects { get; set; } = new List(); public string TargetStateId { get; set; } public Func VisibilityCondition { get; set; } = _ => true; } /// /// 选择效果 /// public class ChoiceEffect { public EffectType Type { get; set; } public Dictionary Parameters { get; set; } = new Dictionary(); public void Apply(StoryStateMachine machine) { switch (Type) { case EffectType.SetVariable: machine.SetVariable((string)Parameters["key"], Parameters["value"]); break; case EffectType.ModifyRelationship: // 实现关系值修改 break; case EffectType.AddItem: // 实现添加物品 break; case EffectType.TriggerEvent: // 实现事件触发 break; } } } public class EndingDefinition { public string Id { get; set; } public string Name { get; set; } public string Description { get; set; } public EndingType Type { get; set; } public Action OnTrigger { get; set; } } public enum TransitionTriggerType { Automatic, Conditional, Event } public enum EffectType { SetVariable, ModifyRelationship, AddItem, TriggerEvent } public enum EndingType { Good, Bad, Neutral, Secret, True } } ``` ### 4.3 延迟反馈实现 ```python # 延迟反馈系统（Python） # 实现"早期的选择在后期产生回响"的设计目标 import time from typing import Dict, List, Callable, Any from dataclasses import dataclass, field from datetime import datetime, timedelta @dataclass class DelayedConsequence: """ 延迟后果：记录一个将在未来某个条件满足时触发的效果 """ consequence_id: str trigger_condition: Dict[str, Any] # 触发条件 effects: List[Dict[str, Any]] # 触发后的效果列表 source_choice: str # 来源于哪个选择 description: str = "" expires_after: int = -1 # 多少秒后过期（-1表示不过期） created_at: datetime = field(default_factory=datetime.now) triggered: bool = False class DelayedFeedbackSystem: """ 延迟反馈系统 设计思路： - 玩家做出选择时，不一定立即看到所有后果 - 某些后果被注册为"延迟后果"，在特定条件满足时触发 - 条件可以是：到达某章节、进入某地图、与某NPC对话等 """ def __init__(self): self._pending: List[DelayedConsequence] = [] self._history: List[DelayedConsequence] = [] self._handlers: Dict[str, Callable] = {} self._event_count = 0 # 用于追踪游戏内"时间" def register_handler(self, effect_type: str, handler: Callable): """注册效果处理器""" self._handlers[effect_type] = handler def add_consequence(self, consequence: DelayedConsequence): """添加延迟后果""" self._pending.append(consequence) print(f"[延迟反馈] 注册后果: {consequence.description}") def tick(self, current_state: Dict[str, Any]): """ 每帧或每个叙事节点检查一次 current_state: 当前游戏状态快照 """ self._event_count += 1 to_remove = [] for consequence in self._pending: if consequence.triggered: continue # 检查是否过期 if consequence.expires_after > 0: elapsed = (datetime.now() - consequence.created_at).total_seconds() if elapsed > consequence.expires_after: to_remove.append(consequence) continue # 检查触发条件 if self._check_condition(consequence.trigger_condition, current_state): self._trigger(consequence, current_state) to_remove.append(consequence) for c in to_remove: self._pending.remove(c) def _check_condition(self, condition: Dict[str, Any], state: Dict[str, Any]) -> bool: """检查条件是否满足""" condition_type = condition.get("type") if condition_type == "chapter_reached": return state.get("current_chapter") == condition["chapter"] elif condition_type == "location_entered": return state.get("current_location") == condition["location"] elif condition_type == "npc_met": met_npcs = state.get("met_npcs", []) return condition["npc"] in met_npcs elif condition_type == "flag_set": return state.get(condition["flag"]) == condition["value"] elif condition_type == "event_count": return self._event_count >= condition["count"] elif condition_type == "and": return all(self._check_condition(c, state) for c in condition["conditions"]) elif condition_type == "or": return any(self._check_condition(c, state) for c in condition["conditions"]) return False def _trigger(self, consequence: DelayedConsequence, state: Dict[str, Any]): """触发后果效果""" consequence.triggered = True self._history.append(consequence) print(f"\n[延迟反馈触发] {consequence.description}") for effect in consequence.effects: effect_type = effect["type"] handler = self._handlers.get(effect_type) if handler: handler(effect, state) else: print(f" [效果] {effect_type}: {effect}") def get_pending(self) -> List[DelayedConsequence]: """获取待触发的后果列表（用于调试UI）""" return [c for c in self._pending if not c.triggered] def get_history(self) -> List[DelayedConsequence]: """获取已触发的历史记录""" return self._history # ===== 使用示例：早期选择，后期回响 ===== def demo_delayed_feedback(): system = DelayedFeedbackSystem() # 注册效果处理器 def handle_dialogue(effect, state): print(f" -> 触发对话: {effect['dialogue_id']}") def handle_flag(effect, state): state[effect["key"]] = effect["value"] print(f" -> 设置变量: {effect['key']} = {effect['value']}") system.register_handler("show_dialogue", handle_dialogue) system.register_handler("set_flag", handle_flag) # 模拟游戏状态 game_state = { "current_chapter": 1, "current_location": "village", "met_npcs": [], "karma": 0 } # 第1章：玩家在村庄做出选择——偷了商人的钱 print("=" * 50) print("[第1章] 玩家偷了商人的钱...") system.add_consequence(DelayedConsequence( consequence_id="stolen_money_echo", trigger_condition={ "type": "chapter_reached", "chapter": 3 }, effects=[ {"type": "show_dialogue", "dialogue_id": "merchant_revenge"}, {"type": "set_flag", "key": "merchant_hates_you", "value": True} ], source_choice="steal_from_merchant", description="第1章偷钱的行为在第3章被商人记住" )) # 第2章：正常推进 print("\n[第2章] 推进剧情...") game_state["current_chapter"] = 2 system.tick(game_state) # 无触发 # 第3章：延迟反馈触发！ print("\n[第3章] 到达首都...") game_state["current_chapter"] = 3 game_state["current_location"] = "capital" system.tick(game_state) # 触发商人复仇 if __name__ == "__main__": demo_delayed_feedback() ``` ### 4.4 多结局管理 ```python # 多结局管理系统（Python） # 根据玩家全程的选择组合计算最终结局 from typing import Dict, List, Callable, Optional from dataclasses import dataclass from enum import Enum class EndingTier(Enum): """结局层级""" NORMAL = "normal" GOOD = "good" BAD = "bad" SECRET = "secret" TRUE_END = "true_end" @dataclass class Ending: """结局定义""" ending_id: str title: str description: str tier: EndingTier conditions: List[Dict] # 解锁条件 epilogue_text: str = "" class MultipleEndingManager: """ 多结局管理器 核心机制： 1. 每个结局有一组条件（变量值、选择记录、 visited状态等） 2. 结局按优先级排序（秘密结局 > 真结局 > 好/坏结局 > 普通结局） 3. 支持多条件组合：AND（必须全部满足）或 OR（满足任一） """ def __init__(self): self._endings: Dict[str, Ending] = {} self._priority_order = [ EndingTier.TRUE_END, EndingTier.SECRET, EndingTier.GOOD, EndingTier.BAD, EndingTier.NORMAL ] def register_ending(self, ending: Ending): """注册结局""" self._endings[ending.ending_id] = ending def calculate_ending(self, player_state: Dict) -> Optional[Ending]: """ 根据玩家状态计算最终结局 返回优先级最高的满足条件的结局 """ candidates = [] for ending in self._endings.values(): if self._check_ending_conditions(ending.conditions, player_state): candidates.append(ending) if not candidates: return None # 按优先级排序，返回最高优先级 candidates.sort(key=lambda e: self._priority_order.index(e.tier)) return candidates[0] def _check_ending_conditions(self, conditions: List[Dict], state: Dict) -> bool: """检查结局条件是否满足""" for cond in conditions: if not self._evaluate_condition(cond, state): return False return True def _evaluate_condition(self, cond: Dict, state: Dict) -> bool: """评估单个条件""" cond_type = cond.get("type") if cond_type == "flag_equals": return state.get(cond["flag"]) == cond["value"] elif cond_type == "flag_gte": return state.get(cond["flag"], 0) >= cond["value"] elif cond_type == "flag_lte": return state.get(cond["flag"], 0) <= cond["value"] elif cond_type == "choice_made": choices = state.get("choices_made", []) return cond["choice_id"] in choices elif cond_type == "all_choices": choices = state.get("choices_made", []) return all(c in choices for c in cond["choice_ids"]) elif cond_type == "any_choice": choices = state.get("choices_made", []) return any(c in choices for c in cond["choice_ids"]) elif cond_type == "visited_state": visited = state.get("visited_states", []) return cond["state_id"] in visited elif cond_type == "not": return not self._evaluate_condition(cond["condition"], state) return False def preview_endings(self, player_state: Dict) -> List[Dict]: """ 预览：显示当前状态下各结局的解锁进度 用于游戏中的"结局收集"UI """ previews = [] for ending in self._endings.values(): total = len(ending.conditions) met = sum(1 for c in ending.conditions if self._evaluate_condition(c, player_state)) previews.append({ "ending_id": ending.ending_id, "title": ending.title, "tier": ending.tier.value, "progress": f"{met}/{total}", "unlocked": met == total, "percentage": (met / total * 100) if total > 0 else 0 }) return sorted(previews, key=lambda x: x["percentage"], reverse=True) # ===== 使用示例：多结局配置 ===== def setup_endings(): manager = MultipleEndingManager() # 真结局：最严格的条件 manager.register_ending(Ending( ending_id="true_end", title="世界守护者", description="你拯救了所有人，包括你的敌人。", tier=EndingTier.TRUE_END, conditions=[ {"type": "flag_gte", "flag": "karma", "value": 80}, {"type": "all_choices", "choice_ids": ["spare_boss", "save_village", "redeem_rival"]}, {"type": "visited_state", "state_id": "secret_garden"}, {"type": "flag_equals", "flag": "true_artifact_restored", "value": True} ], epilogue_text="在光芒中，世界获得了新生..." )) # 好结局 manager.register_ending(Ending( ending_id="good_end", title="英雄归来", description="你成为了人们口中的英雄。", tier=EndingTier.GOOD, conditions=[ {"type": "flag_gte", "flag": "karma", "value": 30}, {"type": "flag_equals", "flag": "boss_defeated", "value": True} ], epilogue_text="王座上，新的传说开始了..." )) # 坏结局 manager.register_ending(Ending( ending_id="bad_end", title="孤独的王座", description="你获得了力量，但失去了所有。", tier=EndingTier.BAD, conditions=[ {"type": "flag_lte", "flag": "karma", "value": -30}, {"type": "flag_equals", "flag": "boss_defeated", "value": True} ], epilogue_text="王座冰冷，无人分享..." )) # 秘密结局 manager.register_ending(Ending( ending_id="secret_end", title="幕后黑手", description="原来你才是最终的幕后操纵者。", tier=EndingTier.SECRET, conditions=[ {"type": "choice_made", "choice_id": "join_dark_cult"}, {"type": "flag_equals", "flag": "betrayed_all", "value": True}, {"type": "flag_equals", "flag": "secret_ritual_done", "value": True} ], epilogue_text="在阴影中，你露出了微笑..." )) # 普通结局（保底） manager.register_ending(Ending( ending_id="normal_end", title="旅程的终点", description="冒险结束，生活继续。", tier=EndingTier.NORMAL, conditions=[ {"type": "flag_equals", "flag": "game_completed", "value": True} ] )) return manager # 模拟结算 if __name__ == "__main__": manager = setup_endings() # 玩家A：走真结局路线 player_a = { "karma": 90, "choices_made": ["spare_boss", "save_village", "redeem_rival", "help_stranger"], "visited_states": ["secret_garden", "capital", "dungeon"], "true_artifact_restored": True, "game_completed": True } ending = manager.calculate_ending(player_a) print(f"玩家A结局: {ending.title} [{ending.tier.value}]") # 预览所有结局进度 print("\n结局收集进度:") for preview in manager.preview_endings(player_a): status = "已解锁" if preview["unlocked"] else f"{preview['progress']}" print(f" [{preview['tier']}] {preview['title']}: {status}") ``` --- ## 5. 叙事工具集成 ### 5.1 articy:draft X API 集成 ```csharp // articy:draft X 运行时集成（C# / Unity） // articy 导出为 JSON 或 Unity Plugin 后，通过以下接口加载 using System; using System.Collections.Generic; using System.IO; using System.Linq; using Newtonsoft.Json; using Newtonsoft.Json.Linq; namespace NarrativeSystem.Integrations.Articy { /// /// articy:draft X 导出数据加载器 /// public class ArticyDataLoader { private JObject _root; private Dictionary _nodes; private Dictionary _dialogues; /// /// 从 articy 导出的 JSON 文件加载 /// public void LoadFromJson(string filepath) { var json = File.ReadAllText(filepath); _root = JObject.Parse(json); _nodes = new Dictionary(); _dialogues = new Dictionary(); ParsePackages(); } private void ParsePackages() { var packages = _root["Packages"] as JArray; foreach (var pkg in packages) { ParseModels(pkg["Models"] as JArray); } } private void ParseModels(JArray models) { foreach (var model in models) { var type = model["Type"]?.ToString(); var id = model["Id"]?.ToString(); switch (type) { case "Dialogue": _dialogues[id] = ParseDialogue(model); break; case "DialogueFragment": _nodes[id] = ParseFragment(model); break; case "Hub": _nodes[id] = ParseHub(model); break; case "Jump": _nodes[id] = ParseJump(model); break; } } } private ArticyDialogue ParseDialogue(JToken model) { return new ArticyDialogue { Id = model["Id"].ToString(), TechnicalName = model["TechnicalName"].ToString(), DisplayName = model["DisplayName"]?.ToString(), // 解析输入/输出引脚连接 InputPins = ParsePins(model["InputPins"] as JArray), OutputPins = ParsePins(model["OutputPins"] as JArray) }; } private ArticyFragment ParseFragment(JToken model) { return new ArticyFragment { Id = model["Id"].ToString(), TechnicalName = model["TechnicalName"].ToString(), Text = model["Text"]?.ToString(), StageDirections = model["StageDirections"]?.ToString(), Speaker = model["Speaker"]?.ToString(), InputPins = ParsePins(model["InputPins"] as JArray), OutputPins = ParsePins(model["OutputPins"] as JArray) }; } private List ParsePins(JArray pins) { if (pins == null) return new List(); return pins.Select(p => new ArticyPin { Id = p["Id"]?.ToString(), Text = p["Text"]?.ToString(), Connections = (p["Connections"] as JArray)?.Select(c => c["Target"]?.ToString()).ToList() ?? new List() }).ToList(); } public ArticyDialogue GetDialogue(string id) => _dialogues.GetValueOrDefault(id); public ArticyNode GetNode(string id) => _nodes.GetValueOrDefault(id); } // articy 数据模型 public class ArticyNode { public string Id { get; set; } public string TechnicalName { get; set; } public List InputPins { get; set; } = new List(); public List OutputPins { get; set; } = new List(); } public class ArticyDialogue : ArticyNode { public string DisplayName { get; set; } } public class ArticyFragment : ArticyNode { public string Text { get; set; } public string StageDirections { get; set; } public string Speaker { get; set; } } public class ArticyHub : ArticyNode { } public class ArticyJump : ArticyNode { public string Target { get; set; } } public class ArticyPin { public string Id { get; set; } public string Text { get; set; } public List Connections { get; set; } = new List(); } } ``` ### 5.2 ink (Inkle) 脚本集成 ```csharp // ink 运行时集成（C#） // 使用官方 ink-engine-runtime 包：Install-Package Ink-engine-runtime using Ink.Runtime; using System; using System.Collections.Generic; using System.IO; using System.Linq; namespace NarrativeSystem.Integrations.Ink { /// /// Ink 故事包装器 /// public class InkStoryRunner { private Story _story; private readonly Dictionary> _externalFunctions; public InkStoryRunner(string jsonFilePath) { var json = File.ReadAllText(jsonFilePath); _story = new Story(json); _externalFunctions = new Dictionary>(); } /// /// 注册外部函数供 ink 脚本调用 /// ink 中使用：~ my_function(param) /// public void BindExternalFunction(string name, Func func) { _story.BindExternalFunction(name, func); } public void BindExternalFunction(string name, Func func) { _story.BindExternalFunction(name, func); } /// /// 推进故事：获取当前段落文本 /// public string Continue() { if (_story.canContinue) { return _story.Continue(); } return null; } /// /// 当前是否有选项 /// public bool HasChoices => _story.currentChoices.Count > 0; /// /// 获取当前可选选项 /// public List GetCurrentChoices() { return _story.currentChoices.Select(c => new InkChoice { Index = c.index, Text = c.text, OriginalChoice = c }).ToList(); } /// /// 做出选择 /// public void ChooseChoiceIndex(int index) { _story.ChooseChoiceIndex(index); } /// /// 设置 ink 变量 /// public void SetVariable(string name, object value) { _story.variablesState[name] = value; } /// /// 获取 ink 变量 /// public object GetVariable(string name) { return _story.variablesState[name]; } /// /// 观察变量变更 /// public void ObserveVariable(string name, Action callback) { _story.ObserveVariable(name, (varName, newValue) => callback(varName, newValue)); } /// /// 故事是否结束 /// public bool IsEnded => !_story.canContinue && !HasChoices; /// /// 获取当前标签（用于触发游戏事件） /// ink 中使用：# trigger_event: battle_boss /// public List CurrentTags => _story.currentTags ?? new List(); } public class InkChoice { public int Index { get; set; } public string Text { get; set; } public object OriginalChoice { get; set; } } } ``` ```ink // 示例 ink 脚本（.ink 文件） // ink 是 Inkle Studios 开发的叙事脚本语言 // === 变量定义 === VAR karma = 0 VAR has_artifact = false VAR elder_trust = 50 // === knots（章节/段落） === -> elder_meeting === elder_meeting === # location: village_center # music: peaceful 长老看着你，眼神中带着审视。 * [恭敬地打招呼] ~ elder_trust += 10 长老微微点头："年轻人，你很有礼貌。" -> elder_quest_offer * [直接索要奖励] ~ elder_trust -= 20 ~ karma -= 5 长老皱眉："无礼！我们还没有正式认识。" -> elder_cold * {has_artifact} [展示古代遗物] 长老瞪大了眼睛："这...这是传说中的圣物！" ~ elder_trust = 100 -> elder_artifact_reaction === elder_quest_offer === "村子的东边出现了怪物，你愿意帮忙吗？" * [接受任务] ~ karma += 5 太好了，我会给你丰厚的报酬。 -> quest_accepted * [拒绝] ~ elder_trust -= 10 好吧...我们找别人。 -> village_leave === elder_cold === { elder_trust < 30: 长老转身不再理你。 # trigger_event: elder_ignores_player - else: 虽然不满，长老还是保持了礼貌。 } -> village_leave === quest_accepted === // 这里可以使用 ink 的线程和拼接功能 你接受了任务，准备前往东边的森林。 # trigger_event: spawn_forest_monsters -> END === village_leave === 你离开了村庄。 -> END === elder_artifact_reaction === 长老激动地握住你的手... // 特殊剧情分支 -> END ``` ### 5.3 Yarn Spinner 集成 ```csharp // Yarn Spinner 集成（Unity / C#） // 使用 Yarn Spinner Unity 包 using System; using System.Collections.Generic; using System.Threading.Tasks; using UnityEngine; using Yarn; using Yarn.Unity; namespace NarrativeSystem.Integrations.YarnSpinner { /// /// Yarn Spinner 对话系统桥接 /// public class YarnDialogueBridge : MonoBehaviour { [SerializeField] private DialogueRunner dialogueRunner; [SerializeField] private DialogueUI dialogueUI; // 游戏状态引用 private IGameState _gameState; private void Start() { // 注册命令（Yarn 中的 <>） RegisterCommands(); // 注册函数（Yarn 中的 {function()}） RegisterFunctions(); // 监听变量变更 dialogueRunner.VariableStorage.OnVariableChange += OnVariableChanged; } private void RegisterCommands() { // <> dialogueRunner.AddCommandHandler( "give_item", (itemId, count) => _gameState.Inventory.Add(itemId, count) ); // <> dialogueRunner.AddCommandHandler( "set_relationship", (npcId, value) => _gameState.Relationships.Set(npcId, value) ); // <> dialogueRunner.AddCommandHandler( "trigger_event", (eventId) => _gameState.Events.Trigger(eventId) ); // <> dialogueRunner.AddCommandHandler( "fade_in", async (duration) => await ScreenFader.FadeIn(duration) ); // <> dialogueRunner.AddCommandHandler( "wait", async (seconds) => await Task.Delay(TimeSpan.FromSeconds(seconds)) ); } private void RegisterFunctions() { // {has_item("sword")} dialogueRunner.AddFunction("has_item", HasItem); // {get_relationship("elder")} dialogueRunner.AddFunction("get_relationship", GetRelationship); // {random_range(1, 100)} dialogueRunner.AddFunction("random_range", RandomRange); } private bool HasItem(string itemId) { return _gameState.Inventory.Has(itemId); } private int GetRelationship(string npcId) { return _gameState.Relationships.Get(npcId); } private int RandomRange(int min, int max) { return UnityEngine.Random.Range(min, max + 1); } private void OnVariableChanged(string name, Yarn.IVariableStorage.Value value) { // 同步 Yarn 变量到游戏状态 _gameState.SetVariable($"yarn.{name}", ConvertYarnValue(value)); } private object ConvertYarnValue(Yarn.IVariableStorage.Value value) { return value.type switch { Yarn.IVariableStorage.Type.Number => value.numberValue, Yarn.IVariableStorage.Type.String => value.stringValue, Yarn.IVariableStorage.Type.Bool => value.boolValue, _ => null }; } /// /// 启动 Yarn 对话 /// public void StartDialogue(string nodeName) { if (dialogueRunner.IsDialogueRunning) { dialogueRunner.Stop(); } // 同步游戏变量到 Yarn SyncVariablesToYarn(); dialogueRunner.StartDialogue(nodeName); } private void SyncVariablesToYarn() { // 将游戏状态中的变量注入 Yarn foreach (var kvp in _gameState.GetAllVariables()) { var yarnName = kvp.Key.Replace("yarn.", ""); switch (kvp.Value) { case int i: dialogueRunner.VariableStorage.SetValue(yarnName, (float)i); break; case float f: dialogueRunner.VariableStorage.SetValue(yarnName, f); break; case string s: dialogueRunner.VariableStorage.SetValue(yarnName, s); break; case bool b: dialogueRunner.VariableStorage.SetValue(yarnName, b); break; } } } } } ``` ```yarn // 示例 Yarn 脚本（.yarn 文件） // Yarn Spinner 使用类似 Markdown 的语法 // === 节点定义 === title: ElderGreeting tags: #location:village #npc:elder --- <> 长老：你又来了，有什么事吗？ <> 长老：欢迎来到我们的村庄，旅行者。 <> <> -> 我想接一些任务 <> -> 我想了解一下这里的历史 <= 5>> 长老：既然你已经有一定实力了，我可以告诉你关于古代遗迹的事... <> <> <> 长老：你还太年轻了，等变强一些再来吧。 <> <> -> { $has_artifact } 我找到了这个古代遗物 长老：天啊！我以为这只是传说！ <> <> <> -> 再见 长老：愿风指引你的道路。 <> === // === 另一个节点 === title: QuestBoard --- 任务公告板上贴着几张泛黄的纸： -> [清理东边的狼群]（推荐等级：3） <> 你觉得自己还不够强大... -> 还是算了 <> <> 你接下了委托。 <> <> -> [寻找丢失的项链] 一个简单的小任务。 <> <> === ``` ### 5.4 Twine 导出与解析 ```python # Twine (Harlowe/SugarCube) 故事解析器（Python） # Twine 导出为 HTML 后，可以提取其中的故事数据 from html.parser import HTMLParser from dataclasses import dataclass, field from typing import Dict, List, Optional import re import json @dataclass class TwinePassage: """Twine 段落节点""" pid: str name: str text: str tags: List[str] = field(default_factory=list) links: List[str] = field(default_factory=list) # [[链接文本->目标]] position: tuple = (0, 0) # 编辑器中的位置 class TwineHtmlParser(HTMLParser): """ 解析 Twine 导出的 HTML 文件 Twine 使用 标签存储故事数据 """ def __init__(self): super().__init__() self.story_name = "" self.story_data = "" self.passages: List[TwinePassage] = [] self._current_passage = None self._in_passage = False self._capture_data = False def handle_starttag(self, tag, attrs): attrs_dict = dict(attrs) if tag == "tw-storydata": self.story_name = attrs_dict.get("name", "") self.story_data = attrs_dict.get("options", "") elif tag == "tw-passagedata": self._in_passage = True self._current_passage = { "pid": attrs_dict.get("pid", ""), "name": attrs_dict.get("name", ""), "tags": attrs_dict.get("tags", "").split() if attrs_dict.get("tags") else [], "position": ( int(attrs_dict.get("position", "0,0").split(",")[0]), int(attrs_dict.get("position", "0,0").split(",")[1]) ) if "position" in attrs_dict else (0, 0), "text": "" } def handle_endtag(self, tag): if tag == "tw-passagedata" and self._current_passage: text = self._current_passage["text"] links = self._extract_links(text) passage = TwinePassage( pid=self._current_passage["pid"], name=self._current_passage["name"], text=text, tags=self._current_passage["tags"], links=links, position=self._current_passage["position"] ) self.passages.append(passage) self._in_passage = False self._current_passage = None def handle_data(self, data): if self._in_passage and self._current_passage is not None: self._current_passage["text"] += data def _extract_links(self, text: str) -> List[str]: """提取 Twine 链接语法：[[目标]] 或 [[文本->目标]] 或 [[目标|文本]]""" pattern = r'\[\[(.*?)\]\]' matches = re.findall(pattern, text) targets = [] for match in matches: # 处理 "文本->目标" 或 "目标|文本" 格式 if '->' in match: targets.append(match.split('->')[-1].strip()) elif '|' in match: targets.append(match.split('|')[0].strip()) else: targets.append(match.strip()) return targets class TwineToCustomConverter: """ 将 Twine 故事转换为自定义 JSON 格式 便于导入到自定义游戏引擎 """ def convert(self, parser: TwineHtmlParser) -> dict: passages = {} for p in parser.passages: passages[p.name] = { "id": p.pid, "text": p.text, "tags": p.tags, "links": [ { "target": link, "conditions": [] # Twine 基础版无内置条件 } for link in p.links ], "position": p.position } return { "source": "twine", "story_name": parser.story_name, "format": "custom-v1", "entry_point": parser.passages[0].name if parser.passages else "", "passages": passages } def convert_with_macros(self, parser: TwineHtmlParser) -> dict: """ 增强版本：解析 SugarCube 宏命令 支持 (if:), (set:), (goto:) 等 """ passages = {} for p in parser.passages: parsed = self._parse_macros(p.text) passages[p.name] = { "id": p.pid, "text": parsed["display_text"], "tags": p.tags, "conditions": parsed["conditions"], "variable_ops": parsed["set_ops"], "links": parsed["links"], "position": p.position } return { "source": "twine-sugarcube", "story_name": parser.story_name, "format": "custom-v1", "entry_point": parser.passages[0].name if parser.passages else "", "passages": passages } def _parse_macros(self, text: str) -> dict: """解析 SugarCube 宏""" result = { "display_text": text, "conditions": [], "set_ops": [], "links": [] } # 解析 (set: $var to value) set_pattern = r'\(set:\s*\$(\w+)\s+to\s+([^)]+)\)' for match in re.finditer(set_pattern, text): result["set_ops"].append({ "variable": match.group(1), "value": self._parse_value(match.group(2).strip()) }) # 解析 (if: $var > value)[内容] if_pattern = r'\(if:\s*([^)]+)\)\[(.*?)\]' for match in re.finditer(if_pattern, text, re.DOTALL): result["conditions"].append({ "expression": match.group(1).strip(), "content": match.group(2).strip() }) # 重新提取纯文本（去除宏） clean_text = re.sub(r'\([^)]+\)', '', text) clean_text = re.sub(r'\[.*?\]', '', clean_text, flags=re.DOTALL) result["display_text"] = clean_text.strip() # 提取链接 link_pattern = r'\[\[(.*?)\]\]' for match in re.finditer(link_pattern, text): link_text = match.group(1) if '->' in link_text: target = link_text.split('->')[-1].strip() elif '|' in link_text: target = link_text.split('|')[0].strip() else: target = link_text.strip() result["links"].append(target) return result def _parse_value(self, val_str: str): """解析字符串值为 Python 类型""" val_str = val_str.strip().strip('"').strip("'") if val_str.lower() == "true": return True if val_str.lower() == "false": return False try: if "." in val_str: return float(val_str) return int(val_str) except ValueError: return val_str # ===== 使用示例 ===== if __name__ == "__main__": # 模拟 Twine 导出的 HTML 内容 sample_html = """ 你站在一个分岔路口。 [[向左走->Forest]] [[向右走->Village]] 森林里很暗，你听到了奇怪的声音。 (set: $fear to $fear + 1) [[继续深入->DeepForest]] [[返回->Start]] 村民们热情地欢迎了你。 (if: $visited_village)[欢迎回来！] (set: $visited_village to true) [[离开->Start]] """ parser = TwineHtmlParser() parser.feed(sample_html) print(f"故事名: {parser.story_name}") print(f"段落数: {len(parser.passages)}") for p in parser.passages: print(f"\n--- {p.name} [{p.pid}] ---") print(f"标签: {p.tags}") print(f"链接: {p.links}") print(f"文本:\n{p.text[:200]}...") # 转换为自定义格式 converter = TwineToCustomConverter() custom_format = converter.convert_with_macros(parser) print("\n\n转换后的 JSON:") print(json.dumps(custom_format, ensure_ascii=False, indent=2)) ``` --- ## 6. 综合示例：小型叙事系统完整实现 以下是一个可运行的最小完整示例，整合了上述多个概念。 ```python # mini_narrative_system.py # 最小可运行叙事系统：整合 Etudes + 对话树 + 分支 + 变量 from typing import Dict, List, Optional, Callable, Any from dataclasses import dataclass, field from enum import Enum import json # ===== 核心枚举 ===== class NodeState(Enum): INACTIVE = 0 ACTIVE = 1 COMPLETED = 2 class Priority(Enum): LOW = 1 NORMAL = 2 HIGH = 3 CRITICAL = 4 # ===== 数据模型 ===== @dataclass class NarrativeNode: """叙事节点（简化版 Etude）""" id: str name: str priority: Priority = Priority.NORMAL state: NodeState = NodeState.INACTIVE required_flags: Dict[str, Any] = field(default_factory=dict) set_flags_on_enter: Dict[str, Any] = field(default_factory=dict) children: List[str] = field(default_factory=list) dialogue_entry: Optional[str] = None conflicts: List[str] = field(default_factory=list) @dataclass class DialogueEntry: """对话条目""" id: str speaker: str text: str choices: List['DialogueChoice'] = field(default_factory=list) auto_jump: Optional[str] = None @dataclass class DialogueChoice: """玩家选择""" text: str target_dialogue: Optional[str] = None target_node: Optional[str] = None # 选择后跳转到叙事节点 set_flags: Dict[str, Any] = field(default_factory=dict) # ===== 核心系统 ===== class MiniNarrativeSystem: """ 最小叙事系统 整合：Etudes式状态管理 + 对话树 + 变量系统 """ def __init__(self): self.flags: Dict[str, Any] = {} self.nodes: Dict[str, NarrativeNode] = {} self.dialogues: Dict[str, DialogueEntry] = {} self.current_node: Optional[NarrativeNode] = None self.current_dialogue: Optional[DialogueEntry] = None self.choice_history: List[str] = [] self.event_log: List[str] = [] def register_node(self, node: NarrativeNode): self.nodes[node.id] = node def register_dialogue(self, dialogue: DialogueEntry): self.dialogues[dialogue.id] = dialogue def set_flag(self, key: str, value: Any): old = self.flags.get(key) self.flags[key] = value self.event_log.append(f"[Flag] {key}: {old} -> {value}") def get_flag(self, key: str, default=None): return self.flags.get(key, default) def evaluate_nodes(self): """评估所有节点，激活满足条件的""" candidates = [] for node in self.nodes.values(): if node.state == NodeState.COMPLETED: continue if self._check_conditions(node.required_flags): candidates.append(node) # 按优先级排序 candidates.sort(key=lambda n: n.priority.value, reverse=True) # 激活最高优先级且不冲突的 activated = [] for node in candidates: if any(conflict in activated for conflict in node.conflicts): continue activated.append(node.id) if node.state == NodeState.INACTIVE: self._activate_node(node) def _check_conditions(self, conditions: Dict[str, Any]) -> bool: for key, expected in conditions.items(): if self.flags.get(key) != expected: return False return True def _activate_node(self, node: NarrativeNode): node.state = NodeState.ACTIVE self.event_log.append(f"[Node] 激活: {node.name} ({node.id})") # 设置进入标志 for k, v in node.set_flags_on_enter.items(): self.set_flag(k, v) # 如果有关联对话，自动进入 if node.dialogue_entry and node.dialogue_entry in self.dialogues: self.current_node = node self.start_dialogue(node.dialogue_entry) def start_dialogue(self, dialogue_id: str): if dialogue_id not in self.dialogues: return self.current_dialogue = self.dialogues[dialogue_id] self._render_dialogue() def _render_dialogue(self): if not self.current_dialogue: return d = self.current_dialogue print(f"\n{'='*40}") print(f"[{d.speaker}]") print(f"{d.text}") print(f"{'='*40}") if d.auto_jump: print(f"(自动跳转至: {d.auto_jump})") self._jump_to(d.auto_jump) return if d.choices: for i, choice in enumerate(d.choices, 1): print(f" {i}. {choice.text}") def select_choice(self, index: int): """玩家选择选项（0-based index）""" if not self.current_dialogue: return choices = self.current_dialogue.choices if index < 0 or index >= len(choices): return choice = choices[index] self.choice_history.append(choice.text) self.event_log.append(f"[Choice] 选择: {choice.text}") # 应用选择效果 for k, v in choice.set_flags.items(): self.set_flag(k, v) # 跳转 if choice.target_dialogue: self._jump_to(choice.target_dialogue) elif choice.target_node: self.current_dialogue = None self._activate_node(self.nodes[choice.target_node]) else: self.current_dialogue = None # 对话结束，重新评估节点 self.evaluate_nodes() def _jump_to(self, target: str): if target in self.dialogues: self.start_dialogue(target) elif target in self.nodes: self.current_dialogue = None self._activate_node(self.nodes[target]) def complete_current_node(self): """完成当前节点""" if self.current_node: self.current_node.state = NodeState.COMPLETED self.event_log.append(f"[Node] 完成: {self.current_node.name}") self.current_node = None self.evaluate_nodes() def save(self) -> str: """导出为 JSON 存档""" data = { "flags": self.flags, "node_states": {nid: n.state.value for nid, n in self.nodes.items()}, "choice_history": self.choice_history, "event_log": self.event_log } return json.dumps(data, ensure_ascii=False, indent=2) # ===== 使用示例：完整流程 ===== def demo_full_system(): sys = MiniNarrativeSystem() # 注册叙事节点 sys.register_node(NarrativeNode( id="intro", name="开场", priority=Priority.CRITICAL, dialogue_entry="dlg_intro" )) sys.register_node(NarrativeNode( id="village_quest", name="村庄任务", priority=Priority.NORMAL, required_flags={"intro_completed": True}, dialogue_entry="dlg_village" )) sys.register_node(NarrativeNode( id="forest_quest", name="森林任务", priority=Priority.NORMAL, required_flags={"intro_completed": True}, dialogue_entry="dlg_forest", conflicts=["village_quest"] # 与村庄任务互斥 )) # 注册对话 sys.register_dialogue(DialogueEntry( id="dlg_intro", speaker="旁白", text="你醒来在一个陌生的房间里。门开着，外面似乎有声音。", choices=[ DialogueChoice( text="走出去看看", target_dialogue="dlg_outside", set_flags={"intro_completed": True} ), DialogueChoice( text="先在房间里搜索", target_dialogue="dlg_search_room" ) ] )) sys.register_dialogue(DialogueEntry( id="dlg_search_room", speaker="旁白", text="你发现了一把生锈的钥匙，但没有其他有价值的东西。", choices=[ DialogueChoice( text="走出去", target_dialogue="dlg_outside", set_flags={"intro_completed": True, "has_key": True} ) ] )) sys.register_dialogue(DialogueEntry( id="dlg_outside", speaker="旁白", text="你来到外面。左边是村庄，右边是森林。", choices=[ DialogueChoice( text="去村庄", target_node="village_quest" ), DialogueChoice( text="去森林", target_node="forest_quest" ) ] )) sys.register_dialogue(DialogueEntry( id="dlg_village", speaker="村长", text="欢迎，旅行者！我们正被狼群困扰，你能帮忙吗？", choices=[ DialogueChoice( text="接受任务", set_flags={"quest_wolves": "accepted"} ), DialogueChoice( text="拒绝", set_flags={"quest_wolves": "refused"} ) ] )) sys.register_dialogue(DialogueEntry( id="dlg_forest", speaker="神秘声音", text="森林深处传来低语...你确定要继续吗？", choices=[ DialogueChoice( text="深入探索", set_flags={"forest_explored": True} ), DialogueChoice( text="退回去", target_dialogue="dlg_outside" ) ] )) # 启动系统 print("=" * 50) print("启动叙事系统演示") print("=" * 50) sys.evaluate_nodes() # 模拟玩家交互 # 在实际游戏中，这些来自UI输入 sys.select_choice(1) # 先搜索房间 sys.select_choice(0) # 走出去 sys.select_choice(0) # 去村庄 sys.select_choice(0) # 接受任务 print("\n" + "=" * 50) print("事件日志:") print("=" * 50) for log in sys.event_log: print(log) print("\n" + "=" * 50) print("存档数据:") print("=" * 50) print(sys.save()) if __name__ == "__main__": demo_full_system() ``` --- ## 总结 本文档覆盖了游戏叙事架构的五个核心领域： | 模块 | 关键技术 | 适用规模 | |------|----------|----------| | Etudes 系统 | 层级化状态机、优先级排序、冲突检测 | 大型RPG | | 对话系统 | 节点树、条件判断、变量绑定 | 通用 | | 变量管理 | 全局Flag、命名空间、持久化 | 通用 | | 分支剧情 | 状态机、延迟反馈、多结局 | 叙事驱动游戏 | | 工具集成 | articy、ink、Yarn、Twine | 通用 | **选型建议：** - **小型项目/原型**：直接用 JSON + 简单状态机，或集成 Twine - **中型项目**：使用 ink 或 Yarn Spinner，自研轻量状态机 - **大型项目**：参考 Etudes 架构，自研层级化状态管理，或集成 articy:draft X --- ## 参考来源 - Owlcat Games: GDC 2026 — Managing 30,000+ Narrative Variables - Inkle Studios: ink 脚本语言官方文档 (https://github.com/inkle/ink) - Yarn Spinner: 官方文档 (https://docs.yarnspinner.dev/) - articy:draft X: 官方开发者文档 - Twine: Harlowe / SugarCube 格式规范