ttrpg-tools/src/doc-entries/journal-set.md

tag, icon, title, description, syntax, props

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

概述

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

核心概念：

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

代码块语法

以 yaml role=declare 代码块定义，正文为 YAML：

vars:
  $hp: $con*5 + $mod_hp
  $ac: 10 + $dex
tags:
  warrior:
    1:
      $mod_hp: 20
    2:
      $mod_str: 1

键	说明
vars	变量声明映射：$name: 表达式
tags	标签修饰符映射：标签名 → 阈值 → {$目标: 增量}

标签名可以带或不带 # 前缀。阈值是正整数：标签计数值达到该值时，修饰符生效。

数字会被当作数值，其余一律作为表达式文本（如 $con*5+$mod_hp）。

声明类型

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

vars:
  $hp: $con*5 + $mod_hp
  $ac: 10 + $dex

标签修饰符（tags）：当源变量的标签映射中 #tag 的计数值 ≥ 阈值时，$key 加上该值。同一标签的多个阈值会叠加，修饰符按阈值独立激活。

tags:
  warrior:
    1:
      $mod_hp: 20
    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 时，修饰符停用
• 标签激活时，其修饰符加到目标变量上
• 标签停用时，修饰符从目标变量中减去

阈值机制

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

tags:
  warrior:
    1:
      $mod_hp: 10
    3:
      $mod_hp: 20

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

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

变量视图

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

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

文档模板

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

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

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

完整示例

在文档中定义：

vars:
  $con: 10
  $dex: 12
  $hp: $con*5 + $mod_hp
  $ac: 10 + $dex
tags:
  warrior:
    1:
      $mod_hp: 20
    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：可设置所有变量
• 玩家：可设置变量
• 观察者：不能设置变量