---
title: "变量与指令"
description: "世界文件里的变量对象、四种类型，以及 AI 在回复中写下用来改值的方括号指令。"
---

# 变量与指令

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

## 变量 Schema

```json
{
  "id": "health",
  "name": "Health",
  "type": "number",
  "defaultValue": 100,
  "min": 0,
  "max": 100,
  "description": "Player's physical health",
  "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]. To remove an ally, use a Behavior with an UpdateVariable JSON Patch action, or overwrite the whole array with [allies: set [...]]. Trust below 20 = may betray."
```

## ID 规范

- ID 在世界内必须唯一
- 由字母、数字、下划线组成的 ID 可以作为变量宏被访问 —— 例如 `player_health` 可在条目中通过 <code v-pre>{{player_health}}</code> 引用。**含 `-` 的 ID 不会被宏解析器匹配**，因此打算用双花括号宏引用的变量请用 `snake_case`（或 `camelCase`）。
- 变量指令解析器（AI 回复里用的方括号语法）支持 `-`，所以 `kebab-case` ID 在 `[player-health: +5]` 这类指令里仍然能正常工作。
- 避免使用保留字：`audio`、`user`、`char`、`time`、`date`
