游戏叙事与剧情 / 系统课时
先定义剧情系统的执行契约
先定义剧情系统的执行契约
剧情节点一旦由多个编辑器、任务系统和运行时共同消费,最容易出问题的不是“少一种节点”,而是输入、输出和失败语义各说各话。本节把节点执行收敛成稳定契约,让调用方知道要提供什么、执行后能得到什么,以及异常发生时状态是否已经改变。
学习目标
- 定义节点执行所需的上下文、结果和状态变更边界
- 区分可恢复业务分支与真正的运行时错误
- 用统一接口约束不同节点类型,避免调用方写类型特判
契约先回答四个问题
一个可长期演进的剧情运行时,至少要对每次节点执行回答四件事:输入是什么、输出是什么、允许改变哪些状态、失败后调用方该怎么处理。不要把这些规则散落在每个节点实现里,否则新增对话、条件、任务或奖励节点时,调用方会不断增加特殊分支。
输入通常不是“整个游戏对象”,而是一次执行真正需要的上下文,例如当前节点、剧情变量快照和外部服务。输出则应描述下一步动作,而不是直接替调用方跳转场景。这样节点负责“计算结果”,运行时负责“提交结果”。

把输入和输出做成稳定数据结构
下面的 TypeScript 示例把“读取上下文”和“提交状态”分开。节点只能返回补丁与下一节点,不直接改写全局状态,因此同一套执行器可以统一记录日志、做回放或在提交前校验结果。
type StoryValue = string | number | boolean;
type ReadonlyStoryState = {
readonly variables: Readonly<Record<string, StoryValue>>;
};
interface ExecutionContext {
nodeId: string;
state: ReadonlyStoryState;
}
type ExecutionResult =
| {
status: "ok";
nextNodeId: string | null;
patch: Record<string, StoryValue>;
}
| {
status: "blocked";
reason: string;
};
interface NarrativeNode {
execute(context: ExecutionContext): ExecutionResult;
}
class SetFlagNode implements NarrativeNode {
constructor(
private readonly flag: string,
private readonly value: StoryValue,
private readonly nextNodeId: string | null
) {}
execute(context: ExecutionContext): ExecutionResult {
// 节点只计算结果,不直接改写 context.state。
if (context.nodeId.length === 0) {
return { status: "blocked", reason: "missing node id" };
}
return {
status: "ok",
nextNodeId: this.nextNodeId,
patch: { [this.flag]: this.value }
};
}
}
const node = new SetFlagNode("met_blacksmith", true, "dialogue-02");
const result = node.execute({
nodeId: "flag-01",
state: { variables: {} }
});
console.log(JSON.stringify(result));预期输出
{"status":"ok","nextNodeId":"dialogue-02","patch":{"met_blacksmith":true}}这里的关键不是具体类型名,而是职责边界:ExecutionContext 表示执行前可读取的数据,ExecutionResult 表示节点建议的结果,真正写入剧情状态的动作由外层运行时完成。
明确状态什么时候才算改变
如果节点在执行到一半时已经写入背包、任务进度或剧情变量,随后又抛出错误,调用方很难判断是否需要回滚。更稳妥的做法是让节点先产生“意图”,由运行时在结果有效后统一提交。
对于纯剧情变量,可以把变更表示成 patch;对于发奖、接任务等外部副作用,可以返回待执行命令,由专门适配器完成。契约要明确:节点返回 ok 前不得产生不可撤销副作用;如果业务必须先调用外部系统,则需要幂等键或补偿策略。
区分业务阻塞与系统错误
“玩家没有钥匙”通常不是异常,而是剧情条件没有满足;“任务服务超时”才更接近系统错误。两者如果都用 throw,运行时就无法决定是走备用分支、提示玩家,还是中断剧情并上报故障。
推荐让契约至少区分两类结果:可预期的业务结果用返回值表达,例如 blocked、waiting;不可预期的系统故障用异常或统一错误对象交给运行时处理。错误对象还应带稳定错误码,而不是只依赖文案,因为日志、测试和监控都需要可机器判断的标识。
用契约约束扩展,而不是约束剧情内容
稳定契约并不意味着所有节点只能有同一种业务字段。对话节点可以有文本和选项,条件节点可以有表达式,任务节点可以有任务标识;真正需要统一的是它们进入运行时后的执行形态。
当新增节点类型时,先检查它是否仍能遵守同一组输入、输出、状态提交和错误规则。只要调用方不需要新增 if nodeType === ... 才能正确执行,这份契约就在发挥作用。最终得到的是一个“节点实现可以持续增加,运行时主循环基本不变”的边界。