游戏叙事与剧情 / 系统课时

日志要记录哪些状态变化

日志要记录哪些状态变化

剧情状态异常往往发生在几秒甚至几帧之前,只记录“当前值”很难还原过程。本课设计一条可用于回溯的状态变更日志:每次变化都记录事件、旧值、新值、来源和时间,并补上状态键与版本,保证出现冲突时能追到具体写入者。

学习目标

  • 设计能够回答“谁在什么时候改了什么”的日志字段
  • 用结构化日志记录一次完整的状态变更
  • 避免日志缺字段、值过大和敏感信息泄漏

一条日志至少回答五个问题

有效的状态日志必须能回答:发生了什么事件、改的是哪个状态、修改前是什么、修改后是什么、修改来自哪里,以及发生时间。实际工程中再加上 version、会话或存档标识,排查覆盖问题会更快。

推荐至少保留这些字段:

字段 作用
event 说明触发动作,例如 quest.completed
stateKey 标识被修改的状态路径
oldValue 修改前的值
newValue 修改后的值
source 标识写入来源,如脚本、读档或网络同步
time 记录变更时间
version 判断新旧顺序,识别过期写入

不要只写“任务状态发生变化”。这种日志缺少旧值、新值和来源,即使能找到时间点,也无法判断变化是否合理。

用结构化日志而不是拼接句子

结构化 JSON 更适合搜索、聚合和机器分析。下面是一次任务状态从 active 变为 completed 的日志示例。它不是程序执行输出,而是日志数据结构;实际项目可由日志框架序列化生成。

json
{
  "event": "quest.completed",
  "stateKey": "quests.main-001.status",
  "oldValue": "active",
  "newValue": "completed",
  "source": "dialogue:merchant-07",
  "time": "2026-09-25T13:30:00Z",
  "version": 42
}

验证方法很直接:触发一次对应剧情事件后,日志系统应产生一条记录,并且 oldValue 与触发前状态一致、newValue 与触发后状态一致,source 能定位到实际写入入口。时间值和版本号会随运行变化,不应写死为测试断言。

在状态写入口统一记录

最容易漏日志的做法,是让每个剧情脚本自己决定是否打印。更可靠的方式是把记录逻辑放到统一的状态写入口,让所有修改都经过同一函数。

js
function setState(store, key, newValue, source) {
  // 在写入前捕获旧值,日志才能还原变化。
  const oldValue = store.values[key];
  const version = store.version + 1;
  const entry = {
    event: "state.changed",
    stateKey: key,
    oldValue,
    newValue,
    source,
    time: "<TIME>",
    version
  };

  // 状态写入和版本推进集中在同一个入口完成。
  store.values[key] = newValue;
  store.version = version;
  console.log(JSON.stringify(entry));
}

const store = {
  values: { "quests.main-001.status": "active" },
  version: 41
};

setState(store, "quests.main-001.status", "completed", "dialogue:merchant-07");

预期输出:

text
{"event":"state.changed","stateKey":"quests.main-001.status","oldValue":"active","newValue":"completed","source":"dialogue:merchant-07","time":"<TIME>","version":42}

示例中的 <TIME> 代表运行时实际时间。真实实现应由时间函数生成,而不是固定字符串;这里使用占位符是为了让预期结果可稳定对照。

日志要能用,也要控制成本

oldValue 和 newValue 不应无条件序列化整个剧情对象。对于大型背包、关系网或世界状态,只记录发生变化的字段,必要时附加对象 ID。这样既能定位问题,也能避免日志体积随着存档大小快速增长。

source 也要保持可检索,建议使用稳定格式,例如 load:slot-2、script:chapter-4-boss、network:sync,不要只写“系统”“剧情逻辑”这类模糊描述。若来源涉及用户输入或远端数据,还要避免直接写入口令、令牌和隐私字段。

当日志能够稳定串起“事件 → 旧值 → 新值 → 来源 → 时间 → 版本”这条链路时,状态冲突就可以从结果反推到写入动作;相比增加更多零散 console.log,统一结构化记录更适合长期维护和异常回溯。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

日志要记录哪些状态变化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通