变量与指令

变量是世界的游戏状态。AI 每轮读取当前值，并在其回复中写入方括号指令来更新它们。

变量 Schema

{
  "id": "health",
  "name": "Health",
  "type": "number",
  "defaultValue": 100,
  "min": 0,
  "max": 100,
  "description": "Player's physical health",
  "category": "stat",
  "behaviorRules": "0 = death. 1-20 = critical. 20-50 = wounded. 50-80 = bruised. 80-100 = healthy. Decrease on physical damage: punch -5 to -10, slash -15 to -25, fall -20 to -40. Rest +5, healing +10 to +30. Max change per turn: 30."
}

变量类型

number

带可选最小/最大边界的数值。

指令语法：

[health: set 50]       → 设置为 50
[health: +10]          → 加 10（别名：add）
[health: -15]          → 减 15（别名：subtract）
[health: *2]           → 乘以 2（别名：multiply）
[gold: 100]            → 隐式设置（无运算符）

string

文本值。

指令语法：

[location: set "dark forest"]
[mood: set "suspicious"]
[notes: append " Found a clue."]

boolean

布尔标志（true/false）。

指令语法：

[has-key: toggle]        → 翻转 true ↔ false
[met-elder: set true]
[quest-active: set false]

json

复杂结构——对象和数组。支持嵌套点路径更新。

指令语法：

[inventory: push {"name": "Iron Sword", "damage": 10}]
[inventory: delete 0]
[inventory: set [{"name": "Potion", "qty": 3}]]

[npcs.aria.affinity: +5]
[npcs.aria.mood: set "happy"]
[npcs: merge {"aria": {"trust": 80}}]
[quest-log: push {"id": "q1", "status": "active"}]
[config: delete "deprecated-key"]

点路径操作：

• [root.nested.field: op value] — 更新 JSON 变量中的嵌套字段
• 如果中间对象不存在，会自动创建
• 数组索引访问：[inventory.0.durability: -1]

所有操作

操作	适用类型	语法	行为
set	全部	[id: set value] 或 [id: value]	替换值
add / +	number	[id: +10] 或 [id: add 10]	增加
subtract / -	number	[id: -5] 或 [id: subtract 5]	减少
multiply / *	number	[id: *2] 或 [id: multiply 2]	倍增
toggle	boolean	[id: toggle]	翻转 true/false
append	string	[id: append " text"]	拼接
merge	json（对象）	[id: merge {"key": "val"}]	浅合并
push	json（数组）	[id: push "item"] 或 [id: push {...}]	追加到数组
delete	json	[id: delete "key"] 或 [id: delete 0]	删除键/索引

音频指令

音频通过单独的指令格式触发：

[audio: track-id play]
[audio: track-id stop]
[audio: track-id crossfade 2.5]
[audio: track-id volume 0.5]
[audio: track-id play chain:next-track]

行为规则

behaviorRules 字段是纯文本，会被注入到 AI 的系统提示中作为 <behavior-rules> 块。它教导 AI 何时以及如何更新变量。

有效的行为规则应包含：

• 每个数值范围在叙事中的含义
• 什么事件触发变化（以及变化方向）
• 幅度指导（变化多少）
• 限制（每轮最大变化量、绝对边界）
• 与其他变量的关联关系

示例 — 复杂 JSON 变量：

"behaviorRules": "Array of party members. Push new object when recruiting: {\"name\": \"...\", \"class\": \"...\", \"trust\": 50}. Update trust via dot-path: [allies.0.trust: +5]. Remove via index: [allies: delete 0]. Trust < 20 = may betray."

变量分类

注意： category 被 Studio AI 工具接受，用于组织目的，但它不是世界 Schema 的一部分，在验证时会被剥离。它不会出现在 Zod Schema 中。

分类	典型用途
stat	生命值、法力值、耐力、等级
inventory	物品、装备、资源
resource	金币、能量、食物、材料
flag	任务完成、已见 NPC、已发现地点
relationship	NPC 好感度、阵营声望、信任度
custom	其他任何内容

ID 规范

• 使用 kebab-case：player-health、day-count、npc-trust
• ID 在世界内必须唯一
• ID 会成为宏名称：变量 player-health 可在条目中通过 {{player-health}} 访问
• 避免使用保留字：audio、user、char、time、date