---
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:count1;#tag2:count2
  - name: 权限
    type: —
    desc: GM 和玩家均可设置变量
---

## 概述

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

核心概念：
- **变量**（`$name`）：存储数值或标签映射，通过 `/set` 命令修改
- **标签映射**（`#tag:count`）：变量可以存储一个标签映射（如 `#warrior:2;#druid:1`），每个标签有一个计数值
- **标签修饰符**：当变量中的标签计数值达到阈值时，修饰符生效
- **声明**（`declare`）：在 `role=declare` 代码块中定义派生变量和标签修饰符

## 代码块语法

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

| 列 | 说明 |
|---|---|
| `tag` | 标签名（空表示普通变量声明） |
| `threshold` | 激活阈值（可选，默认 `1`）。标签计数值 ≥ 阈值时激活 |
| `key` | 变量名，以 `$` 开头 |
| `expr` | 表达式，支持数字、`$var` 引用、骰子、算术、函数 |

### 声明类型

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

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

**标签修饰符**（tag 非空）：当源变量的标签映射中 `#tag` 的计数值 ≥ `threshold` 时，`$key` 加上表达式的计算结果。修饰符按阈值独立激活。

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

上例中：
- `#warrior` 计数 ≥ 1 时，`$mod_hp` 获得 +20
- `#warrior` 计数 ≥ 2 时，`$mod_str` 获得 +1（需要更高等级）

## 表达式语法

支持以下表达式元素：

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

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

## 命令

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

| 命令 | 示例 | 说明 |
|---|---|---|
| `/set $key expr` | `/set $str 16` | 设置变量为数值 |
| `/set $key #tag` | `/set $class #warrior` | 设置单个标签（等价 `#warrior:1`） |
| `/set $key #tag:count` | `/set $class #warrior:3` | 设置标签及计数值 |
| `/set $key #t1:c1;#t2:c2` | `/set $class #warrior:2;#druid:1` | 设置多个标签 |
| `/set $key #a\|#b\|#c` | `/set $class #w\|#d\|#s` | 随机选择一个标签 |

### 设置数值

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

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

### 设置标签映射

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

等价于 `/set $class #warrior:1`。当 `$class` 的 `#warrior` 计数 ≥ 1 时：
1. `#warrior` 修饰符中阈值 ≤ 1 的生效
2. 如 `$mod_hp += 20`，依赖 `$mod_hp` 的派生变量自动重新计算

**多标签示例：**

```
/set $class #warrior:2;#druid:1
```

变量 `$class` 同时拥有 `#warrior` 计数 2 和 `#druid` 计数 1，两者的修饰符会同时生效（各自按阈值判断）。

### 随机标签

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

从给定标签中随机选择一个，计数值为 1。

## 标签激活

标签的激活状态由变量中标签映射的计数值决定：

- 如果变量的标签映射中 `#tag` 的计数值 = 0（或不存在），该标签停用
- 计数值 ≥ 修饰符的 `threshold` 时，该修饰符激活
- 计数值 < `threshold` 时，修饰符停用
- 标签激活时，其修饰符**加到**目标变量上
- 标签停用时，修饰符**从**目标变量中减去

### 阈值机制

阈值允许同一标签产生不同层级的效果：

```csv role=declare
tag,threshold,key,expr
#warrior,1,$mod_hp,10
#warrior,3,$mod_hp,20
```

- `#warrior` 计数 1-2：`$mod_hp` +10
- `#warrior` 计数 ≥ 3：`$mod_hp` +30（两个修饰符叠加）

一个变量可以存储多个标签（标签映射），支持多职业、混合属性等场景。

## 变量视图

在 Journal 面板顶部点击 **变量** 标签切换到变量视图，显示所有已定义的变量及其当前值。

- 每行显示变量名和当前值，标签类型变量以紫色高亮显示
- 鼠标悬停在变量行上，会弹出气泡显示：声明表达式（如有）和当前激活的标签修饰符（标签名、数值、来源变量）

## 文档模板

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

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

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

## 完整示例

在文档中定义：

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

在 Journal 中输入：

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

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

## 循环依赖

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

## 权限

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