---
title: "规则与反应"
description: "世界文件里的行为对象：带 when、conditions、then 的反应，旧版 rules 格式，触发器、运算符和效果。"
---

# 规则与响应

新卡片建议使用 `reactions`（`when`、`conditions`、`then`）。`rules`（`trigger`、`actions`）是仍受支持的旧格式。行为编辑器会同时显示两种格式，修改行为时会保留原来的触发设置并转换旧规则。同一个行为不要同时放进两个数组，否则会执行两次。

规则在回合之间基于事件自动触发。它们处理精确的游戏机制，无需 AI 参与。

## 规则 Schema

```json
{
  "id": "low-health-warning",
  "name": "Low Health Warning",
  "description": "Warn the player when health is critical",
  "trigger": {
    "type": "variable-crossed",
    "variableId": "health",
    "direction": "drops-below",
    "threshold": 20
  },
  "conditions": [],
  "conditionLogic": "all",
  "actions": [
    {
      "type": "notify-player",
      "style": "warning",
      "message": "Your vision blurs. You're barely standing."
    },
    {
      "type": "inject-directive",
      "directiveId": "critical-health",
      "content": "The player is near death. Describe their physical deterioration — stumbling, blurred vision, trembling hands.",
      "position": "after_char",
      "persistent": true
    }
  ],
  "priority": 50,
  "enabled": true,
  "cooldownTurns": null,
  "maxFireCount": null
}
```

## 触发器类型

| 类型 | 字段 | 触发时机 |
|------|------|---------|
| `variable-crossed` | `variableId`、`direction`（`rises-above` \| `drops-below`）、`threshold` | 变量越过阈值时 |
| `state-change` | `variableId`（可选） | 任何变量发生变化时（或指定变量变化时） |
| `turn-count` | `atTurn`（number）、`everyNTurns`（number） | 在特定回合数时，或每隔 N 回合 |
| `session-start` | — | 新会话的第一条消息 |
| `keyword` | `keywords[]` | 玩家消息包含任何关键词 |
| `ai-keyword` | `keywords[]` | AI 回复包含任何关键词 |
| `every-turn` | — | 每个回合之后 |
| `action` | `actionId`（string） | 特定动作被执行时（例如来自自定义 UI 按钮） |
| `manual` | — | 仅在被另一个规则触发时才执行 |

## 条件

可选的状态检查，规则触发前必须通过：

```json
"conditions": [
  {
    "variableId": "story-phase",
    "operator": "eq",
    "value": "act2"
  },
  {
    "variableId": "health",
    "operator": "gt",
    "value": 0
  }
]
```

运算符：`eq`、`neq`、`gt`、`lt`、`gte`、`lte`、`contains`

`conditionLogic`：`"all"`（AND）或 `"any"`（OR）

## 动作类型

### `modify-variable`
修改变量的值。
```json
{
  "type": "modify-variable",
  "variableId": "hunger",
  "operation": "subtract",
  "value": 5
}
```
操作：`set`、`add`、`subtract`、`multiply`、`toggle`、`append`、`merge`、`push`、`delete`

### `inject-directive`
为后续回合向 AI 的提示词中添加指令。
```json
{
  "type": "inject-directive",
  "directiveId": "romance-mode",
  "content": "The character has developed feelings. Write romantic tension naturally.",
  "position": "after_char",
  "persistent": true
}
```
位置选项：`top`、`before_char`、`after_char`、`auto`、`depth`、`bottom`

`persistent: true` 使指令持续有效直到被明确移除。`persistent: false`（默认）= 一次性，一轮后移除。

`duration`：可选数值。设置后，指令会在 N 轮后自动移除。

### `remove-directive`
移除之前注入的指令。
```json
{
  "type": "remove-directive",
  "directiveId": "romance-mode"
}
```

### `notify-player`
显示弹窗通知。
```json
{
  "type": "notify-player",
  "style": "warning",
  "message": "You're running low on supplies."
}
```
样式：`info`、`achievement`、`warning`、`danger`

### `play-audio`
触发音频音轨。
```json
{
  "type": "play-audio",
  "trackId": "bgm-battle",
  "action": "play"
}
```

### `toggle-entry`
启用或禁用知识库条目。
```json
{
  "type": "toggle-entry",
  "entryId": "secret-lore",
  "enabled": true
}
```

### `toggle-rule`
启用或禁用另一条规则（链式反应）。
```json
{
  "type": "toggle-rule",
  "ruleId": "phase-2-triggers",
  "enabled": true
}
```

### `send-context`
在下一轮向 AI 发送一次性上下文消息。
```json
{
  "type": "send-context",
  "message": "The player just triggered a hidden event. React accordingly.",
  "role": "system"
}
```
`role`：`"system"`（默认）或 `"user"` — 决定上下文如何注入到对话中。

## 规则选项

| 字段 | 类型 | 描述 |
|------|------|------|
| `priority` | number | 值越高越先触发，当多条规则同时触发时生效（默认：0） |
| `cooldownTurns` | number \| null | 两次触发之间的最小回合数 |
| `maxFireCount` | number \| null | 该规则总共可触发的次数（null = 无限） |
| `enabled` | boolean | 可被其他规则切换 |

## Reactions（事件模式系统）

Reactions 是一套更新、更灵活的规则系统，基于通用事件模式：

```json
{
  "id": "zone-enter-forest",
  "name": "Enter Forest",
  "when": {
    "eventType": "spatial:zone-enter",
    "zone": "forest"
  },
  "conditions": [],
  "conditionLogic": "all",
  "then": [
    {
      "type": "set",
      "path": "weather",
      "value": "foggy"
    },
    {
      "type": "set",
      "path": "@audio.ambient",
      "value": "forest-ambient",
      "operation": "set"
    },
    {
      "type": "emit",
      "event": { "type": "spatial:ambience-changed" }
    }
  ]
}
```

### 系统效果路径

Reactions 可以通过 `@` 路径操作系统功能：

| 路径 | 效果 |
|------|------|
| `@audio.bgm` | 播放 BGM 音轨 |
| `@audio.sfx` | 播放音效 |
| `@audio.ambient` | 播放环境音 |
| `@audio.stop` | 停止音轨 |
| `@prompt.directive.<id>` | 注入/移除指令 |
| `@prompt.entry.<id>` | 切换条目可见性 |
| `@prompt.context` | 一次性上下文消息 |
| `@rules.disabled.<id>` | 切换规则的启用/禁用状态 |
| `@ui.notification` | 显示弹窗通知 |
| `@ai.request` | 触发 AI 生成 |
| `@ai.context` | 为下一条 AI 消息添加上下文 |

## 每轮生成的事件

在 AI 回复之后，以下事件会被发出并与所有规则/reactions 进行匹配：

1. `message:user` — 玩家的消息（包含用于关键词匹配的内容）
2. `message:ai` — AI 的回复（包含用于关键词匹配的内容）
3. `turn:complete` — 回合结束（包含回合计数）
4. `state:changed` — 每个发生变化的变量各一个事件（包含 variableId、oldValue、newValue）
