---
tag: journal-set
icon: 🔢
title: 变量系统
description: 在文档中声明变量和标签，通过 /set 命令设置变量值，自动计算派生变量和标签效果。
syntax: '```csv role=declare'
props:
  - name: 定义文件
    type: —
    desc: 在任意 .md 文档中使用 ```csv role=declare 代码块定义变量和标签
  - name: 命令
    type: —
    desc: /set $key expression | /set $key #tag1|#tag2|#tag3
  - name: 权限
    type: —
    desc: GM 和玩家均可设置变量
---

## 概述

变量系统允许你定义数值变量和标签，通过命令设置值，系统自动计算派生变量和标签效果。

核心概念：
- **变量**（`$name`）：存储数值或标签，通过 `/set` 命令修改
- **标签**（`#tag`）：当某个变量的值为 `#tag` 时，该标签被激活，触发相应的修饰效果
- **声明**（`declare`）：在 `role=declare` 代码块中定义派生变量和标签修饰符

## 代码块语法

```csv role=declare
tag,key,expr
,$hp,$con*5+$mod_hp
,$ac,10+$dex
#warrior,$mod_hp,20
#warrior,$mod_str,1
```

| 列 | 说明 |
|---|---|
| `tag` | 标签名（空表示普通变量声明） |
| `key` | 变量名，以 `$` 开头 |
| `expr` | 表达式，支持数字、`$var` 引用、骰子、算术、函数 |

### 声明类型

**普通声明**（tag 为空）：`$key` 是一个派生变量，其值由表达式计算。当依赖变量变化时自动重新计算。

```csv role=declare
tag,key,expr
,$hp,$con*5+$mod_hp
,$ac,10+$dex
```

**标签修饰符**（tag 非空）：当 `#tag` 被激活时，`$key` 的当前值加上表达式的计算结果。

```csv role=declare
tag,key,expr
#warrior,$mod_hp,20
#warrior,$mod_str,1
```

## 表达式语法

支持以下表达式元素：

| 元素 | 示例 | 说明 |
|---|---|---|
| 数字 | `10`, `3.5` | 整数或小数 |
| 变量引用 | `$str`, `$mod_hp` | 引用其他变量的值 |
| 骰子 | `3d6`, `2d8kh1` | 每次求值时重新掷骰 |
| 算术 | `+ - * /` | 四则运算 |
| 函数 | `floor(x)`, `ceil(x)`, `round(x)` | 取整函数 |
| 括号 | `(2+3)*4` | 分组 |

变量引用必须解析为数值，不能是标签值（`#warrior`）。如果引用的变量是标签类型，求值会报错。

## 命令

所有命令在 Journal 输入框中输入：

| 命令 | 示例 | 说明 |
|---|---|---|
| `/set $key expr` | `/set $str 16` | 设置变量为数值 |
| `/set $key #tag` | `/set $class #warrior` | 设置变量为标签 |
| `/set $key #a\|#b\|#c` | `/set $class #w\|#d\|#s` | 随机选择一个标签 |

### 设置数值

```
/set $con 14
/set $dex 12
```

设置后，依赖 `$con` 和 `$dex` 的派生变量（如 `$hp`、`$ac`）会自动重新计算。

### 设置标签

```
/set $class #warrior
```

当 `$class` 设置为 `#warrior` 时：
1. `#warrior` 标签被激活
2. 所有 `#warrior` 的修饰符生效：`$mod_hp += 20`，`$mod_str += 1`
3. 依赖这些变量的派生变量自动重新计算

### 随机标签

```
/set $class #warrior|#druid|#sorcerer|#wizard
```

从给定标签中随机选择一个设置为变量值。

## 标签激活

标签的激活状态由变量的值决定：

- 如果**任何**变量的值为 `#tag`，该标签被激活
- 如果**没有**变量的值为 `#tag`，该标签被停用
- 标签激活时，其修饰符**加到**目标变量上
- 标签停用时，修饰符**从**目标变量中减去

一个变量只能存储一个值类型：数值或标签，不能同时存储两者。

## 变量视图

在 Journal 面板顶部点击 **变量** 标签切换视图：

- **激活标签**：显示当前激活的标签、激活来源和修饰效果
- **声明变量**：显示由表达式定义的派生变量及其当前值
- **直接设置**：显示通过 `/set` 直接赋值的变量
- **标签变量**：显示当前值为标签的变量

## 文档模板

在 markdown 文章中使用 `{{$key}}` 语法显示变量的实时值：

```
当前生命值：{{$hp}}
护甲等级：{{$ac}}
```

变量值会随着 Journal 流中的 `/set` 命令实时更新。

## 完整示例

在文档中定义：

```csv role=declare
tag,key,expr
,$con,10
,$dex,12
,$hp,$con*5+$mod_hp
,$ac,10+$dex
#warrior,$mod_hp,20
#warrior,$mod_str,1
```

在 Journal 中输入：

```
/set $con 14
/set $class #warrior
```

结果：
- `$con = 14`
- `$dex = 12`
- `$hp = 14*5 + 20 = 90`
- `$ac = 10 + 12 = 22`
- `$mod_hp = 20`（来自 `#warrior` 修饰符）
- `$mod_str = 1`（来自 `#warrior` 修饰符）

## 循环依赖

系统在加载声明时检测循环依赖。如果声明之间存在循环引用（如 `$a = $b + 1`, `$b = $a + 1`），会抛出错误提示。

## 权限

- **GM**：可设置所有变量
- **玩家**：可设置变量
- **观察者**：不能设置变量