游戏叙事与剧情 / 系统课时
日志要记录哪些状态变化
日志要记录哪些状态变化
剧情状态异常往往发生在几秒甚至几帧之前,只记录“当前值”很难还原过程。本课设计一条可用于回溯的状态变更日志:每次变化都记录事件、旧值、新值、来源和时间,并补上状态键与版本,保证出现冲突时能追到具体写入者。
学习目标
- 设计能够回答“谁在什么时候改了什么”的日志字段
- 用结构化日志记录一次完整的状态变更
- 避免日志缺字段、值过大和敏感信息泄漏
一条日志至少回答五个问题
有效的状态日志必须能回答:发生了什么事件、改的是哪个状态、修改前是什么、修改后是什么、修改来自哪里,以及发生时间。实际工程中再加上 version、会话或存档标识,排查覆盖问题会更快。
推荐至少保留这些字段:
| 字段 | 作用 |
|---|---|
event |
说明触发动作,例如 quest.completed |
stateKey |
标识被修改的状态路径 |
oldValue |
修改前的值 |
newValue |
修改后的值 |
source |
标识写入来源,如脚本、读档或网络同步 |
time |
记录变更时间 |
version |
判断新旧顺序,识别过期写入 |
不要只写“任务状态发生变化”。这种日志缺少旧值、新值和来源,即使能找到时间点,也无法判断变化是否合理。
用结构化日志而不是拼接句子
结构化 JSON 更适合搜索、聚合和机器分析。下面是一次任务状态从 active 变为 completed 的日志示例。它不是程序执行输出,而是日志数据结构;实际项目可由日志框架序列化生成。
{
"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 能定位到实际写入入口。时间值和版本号会随运行变化,不应写死为测试断言。
在状态写入口统一记录
最容易漏日志的做法,是让每个剧情脚本自己决定是否打印。更可靠的方式是把记录逻辑放到统一的状态写入口,让所有修改都经过同一函数。
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");预期输出:
{"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,统一结构化记录更适合长期维护和异常回溯。