refactor: simplify DocDialog and move documentation to markdown body

Simplify the `DocDialog` component by removing hardcoded property
tables and syntax blocks. Instead, rely on the raw markdown body
provided in the `DocEntry` to render documentation content. This
shifts the responsibility of formatting (syntax, props, etc.) from
the component to the individual markdown files, allowing for more
flexible and detailed documentation.
This commit is contained in:
2026-07-13 15:29:08 +08:00
parent 7cb28e631e
commit 99dd49b077
20 changed files with 362 additions and 316 deletions
+66 -39
View File
@@ -10,7 +10,7 @@ props:
desc: 在任意 .md 文档中使用 ```csv role=declare 代码块定义变量和标签
- name: 命令
type: —
desc: /set $key expression | /set $key #tag1|#tag2|#tag3
desc: /set $key expression | /set $key #tag1:count1;#tag2:count2
- name: 权限
type: —
desc: GM 和玩家均可设置变量
@@ -21,23 +21,25 @@ props:
变量系统允许你定义数值变量和标签,通过命令设置值,系统自动计算派生变量和标签效果。
核心概念:
- **变量**(`$name`):存储数值或标签,通过 `/set` 命令修改
- **标签**(`#tag`):当某个变量的值为 `#tag` 时,该标签被激活,触发相应的修饰效果
- **变量**(`$name`):存储数值或标签映射,通过 `/set` 命令修改
- **标签映射**(`#tag:count`):变量可以存储一个标签映射(如 `#warrior:2;#druid:1`),每个标签有一个计数值
- **标签修饰符**:当变量中的标签计数值达到阈值时,修饰符生效
- **声明**(`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,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` 引用、骰子、算术、函数 |
@@ -51,14 +53,18 @@ tag,key,expr
,$ac,10+$dex
```
**标签修饰符**(tag 非空):当 `#tag` 被激活时,`$key` 的当前值加上表达式的计算结果。
**标签修饰符**(tag 非空):当源变量的标签映射中 `#tag` 的计数值 ≥ `threshold` 时,`$key` 加上表达式的计算结果。修饰符按阈值独立激活。
```csv role=declare
tag,key,expr
#warrior,$mod_hp,20
#warrior,$mod_str,1
tag,threshold,key,expr
#warrior,1,$mod_hp,20
#warrior,2,$mod_str,1
```
上例中:
- `#warrior` 计数 ≥ 1 时,`$mod_hp` 获得 +20
- `#warrior` 计数 ≥ 2 时,`$mod_str` 获得 +1(需要更高等级)
## 表达式语法
支持以下表达式元素:
@@ -72,7 +78,7 @@ tag,key,expr
| 函数 | `floor(x)`, `ceil(x)`, `round(x)` | 取整函数 |
| 括号 | `(2+3)*4` | 分组 |
变量引用必须解析为数值,不能是标签值(`#warrior`)。如果引用的变量是标签类型,求值会报错。
变量引用必须解析为数值,不能是标签映射值(`#warrior:1`)。如果引用的变量是标签类型,求值会报错。
## 命令
@@ -81,7 +87,9 @@ tag,key,expr
| 命令 | 示例 | 说明 |
|---|---|---|
| `/set $key expr` | `/set $str 16` | 设置变量为数值 |
| `/set $key #tag` | `/set $class #warrior` | 设置变量为标签 |
| `/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` | 随机选择一个标签 |
### 设置数值
@@ -93,16 +101,23 @@ tag,key,expr
设置后,依赖 `$con` 和 `$dex` 的派生变量(如 `$hp`、`$ac`)会自动重新计算。
### 设置标签
### 设置标签映射
```
/set $class #warrior
```
当 `$class` 设置为 `#warrior` 时:
1. `#warrior` 标签被激活
2. 所有 `#warrior` 的修饰符生效:`$mod_hp += 20`,`$mod_str += 1`
3. 依赖这些变量的派生变量自动重新计算
等价于 `/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,两者的修饰符会同时生效(各自按阈值判断)。
### 随机标签
@@ -110,27 +125,39 @@ tag,key,expr
/set $class #warrior|#druid|#sorcerer|#wizard
```
从给定标签中随机选择一个设置为变量值。
从给定标签中随机选择一个,计数值为 1。
## 标签激活
标签的激活状态由变量的值决定:
标签的激活状态由变量中标签映射的计数值决定:
- 如果**任何**变量的值为 `#tag`,该标签被激活
- 如果**没有**变量的值为 `#tag`,该标签被停用
- 如果变量的标签映射中 `#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 面板顶部点击 **变量** 标签切换视图:
在 Journal 面板顶部点击 **变量** 标签切换到变量视图,显示所有已定义的变量及其当前值。
- **激活标签**:显示当前激活的标签、激活来源和修饰效果
- **声明变量**:显示由表达式定义的派生变量及其当前值
- **直接设置**:显示通过 `/set` 直接赋值的变量
- **标签变量**:显示当前值为标签的变量
- 每行显示变量名和当前值,标签类型变量以紫色高亮显示
- 鼠标悬停在变量行上,会弹出气泡显示:声明表达式(如有)和当前激活的标签修饰符(标签名、数值、来源变量)
## 文档模板
@@ -148,20 +175,20 @@ tag,key,expr
在文档中定义:
```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
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
/set $class #warrior:2
```
结果:
@@ -169,8 +196,8 @@ tag,key,expr
- `$dex = 12`
- `$hp = 14*5 + 20 = 90`
- `$ac = 10 + 12 = 22`
- `$mod_hp = 20`(来自 `#warrior` 修饰符)
- `$mod_str = 1`(来自 `#warrior` 修饰符)
- `$mod_hp = 20`(来自 `#warrior` 修饰符,阈值 1,计数 2 ≥ 1)
- `$mod_str = 1`(来自 `#warrior` 修饰符,阈值 2,计数 2 ≥ 2)
## 循环依赖