template/docs/intermediate/flags.md

Flag 变量

Flag 系统（state.flags）是数据端提供的全局可存档变量。任何需要跨事件、跨楼层保留的简单状态，都可以存进 Flag；它会随存档一起保存与恢复。

字段

Flag 中的每一项是一个字段（IFlagCommonField），字段名与值一一对应。字段对象提供 set(value)（设置值）、add(value)（对数字值增减）与 get()（取值）。一般不需要直接操作字段对象，用下面的系统接口即可。

全部接口

IFlagSystem 提供如下接口：

接口	说明
occupied(field)	判断字段是否被占用
setField(field, value)	以指定值插入字段，返回字段对象
getField(field)	取字段对象，不存在返回 null
getOrInsert(field, defaultValue)	取字段，不存在则以默认值创建
getOrInsertComputed(field, defaultValue)	同上，但默认值由函数惰性计算
deleteField(field)	删除字段
setFieldValue(field, value)	设置字段的值
addFieldValue(field, value)	对数字字段增减
getFieldValue(field)	取字段的值，不存在返回 undefined
getFieldValueDefaults(field, defaultValue)	取字段的值，不存在则以默认值创建并返回

getOrInsertComputed 只在字段确实不存在时才执行默认值函数，适合默认值计算量较大的场景。getFieldValue 没有默认值，需要默认值时用 getFieldValueDefaults。

state.flags.setFieldValue('door-open', true);
const open = state.flags.getFieldValue('door-open');

state.flags.addFieldValue('kill-count', 1);
const count = state.flags.getFieldValueDefaults('kill-count', 0);

使用建议

Flag 会进入存档，因此不建议滥用：不再需要的变量应及时用 deleteField 删除，否则它会一直留在存档里。能用局部状态或对象自身数据表达的，就不必放进 Flag。

if (!state.flags.occupied('temp-flag')) {
    state.flags.setFieldValue('temp-flag', 1);
}

// 用完后删除，避免残留进存档
state.flags.deleteField('temp-flag');

Flag 常与游戏关键动作配合使用，例如在钩子中读写，见钩子。

示例：记录开关与计数

// 记录一个开关
state.flags.setFieldValue('boss-defeated', true);

// 记录一个计数
const times = state.flags.getOrInsert('open-count', 0);
times.add(1);

想从 state 出发找到 Flag 对象，见数据端总览。