docs(declare): document the YAML declare format
Update the journal-set doc entry, the CLI diagnostic table, and the authoring skill, along with the in-app empty-state hint and the var message comment.
This commit is contained in:
hyper
@@ -60,7 +60,7 @@ Fenced blocks are dispatched by the `role=` attribute in the info string:
|
||||
|---|---|
|
||||
| ` ```csv role=spark-table ` | Body is CSV; replaced with `:md-table[./csv_<hash>]`. First column header must be a dice formula (`d6`, `2d6+1`, …). |
|
||||
| ` ```markdown role=spark-table ` | Body is a GFM pipe table; converted to CSV, then same as above. |
|
||||
| ` ```csv role=declare ` | Defines reactive variables / tag modifiers. Block is stripped. |
|
||||
| ` ```yaml role=declare ` | YAML `vars:` / `tags:` maps defining reactive variables and tag modifiers. Block is stripped. |
|
||||
| ` ```<lang> role=file ` | Body stored as text content, block stripped, referenced by its derived id. |
|
||||
| ` ```yaml role=tag ` | Kept intact; rendered as a custom element from YAML (`tag:`, `body:`, …). |
|
||||
| ` ```<lang> ` (no role) | Rendered as a normal visible code block. |
|
||||
@@ -109,7 +109,7 @@ Warnings are usually real too:
|
||||
| Code | Meaning |
|
||||
|---|---|
|
||||
| `TTTK-R002` | spark-table first header is not a dice formula |
|
||||
| `TTTK-R004` | `role=declare` row skipped (empty `key` or `expr`) |
|
||||
| `TTTK-R004` | `role=declare` block declares nothing |
|
||||
| `TTTK-C002` | reference resolves to an unexpected file type |
|
||||
| `TTTK-L002` | `#section` matches no heading |
|
||||
| `TTTK-A001` | icon missing under `assets/` |
|
||||
|
||||
+2
-2
@@ -115,8 +115,8 @@ content/adventures/hollow-mill/adventure.md
|
||||
| `TTTK-D002` | error | 属性块畸形（例如未加引号的值中含空格） |
|
||||
| `TTTK-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） |
|
||||
| `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 |
|
||||
| `TTTK-R003` | error | `role=declare` 解析失败（缺少 `key`/`expr` 等） |
|
||||
| `TTTK-R004` | warning | `role=declare` 中 `key`/`expr` 为空的行被跳过 |
|
||||
| `TTTK-R003` | error | `role=declare` 解析失败（YAML 非法或结构不符） |
|
||||
| `TTTK-R004` | warning | `role=declare` 块没有声明任何变量或标签修饰符 |
|
||||
| `TTTK-R005` | error | `role=tag` 的 YAML 无法解析 |
|
||||
| `TTTK-R006` | error | `role=tag` 缺少 `tag:` 或元素未知 |
|
||||
| `TTTK-C001` | error | 内容引用无法解析（文件不存在，或内联 id 未定义） |
|
||||
|
||||
@@ -53,7 +53,7 @@ export const VariableView: Component = () => {
|
||||
when={hasAnyData()}
|
||||
fallback={
|
||||
<p class="text-center text-gray-400 text-xs py-8">
|
||||
暂无变量定义。在文档中使用 ```csv role=declare 代码块定义变量。
|
||||
暂无变量定义。在文档中使用 ```yaml role=declare 代码块定义变量。
|
||||
</p>
|
||||
}
|
||||
>
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
* Emitters: gm, player
|
||||
* Command: /set $key expression
|
||||
*
|
||||
* Variable declarations and tag modifiers are authored in ```csv role=declare
|
||||
* Variable declarations and tag modifiers are authored in ```yaml role=declare
|
||||
* code blocks in markdown documents. The stream carries `set` mutations that
|
||||
* build up the runtime variable store additively.
|
||||
*/
|
||||
|
||||
@@ -3,11 +3,11 @@ tag: journal-set
|
||||
icon: 🔢
|
||||
title: 变量系统
|
||||
description: 在文档中声明变量和标签，通过 /set 命令设置变量值，自动计算派生变量和标签效果。
|
||||
syntax: '```csv role=declare'
|
||||
syntax: '```yaml role=declare'
|
||||
props:
|
||||
- name: 定义文件
|
||||
type: —
|
||||
desc: 在任意 .md 文档中使用 ```csv role=declare 代码块定义变量和标签
|
||||
desc: 在任意 .md 文档中使用 ```yaml role=declare 代码块定义变量和标签
|
||||
- name: 命令
|
||||
type: —
|
||||
desc: /set $key expression | /set $key #tag1:count1;#tag2:count2
|
||||
@@ -28,37 +28,48 @@ props:
|
||||
|
||||
## 代码块语法
|
||||
|
||||
```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
|
||||
以 `yaml role=declare` 代码块定义，正文为 YAML：
|
||||
|
||||
```yaml role=declare
|
||||
vars:
|
||||
$hp: $con*5 + $mod_hp
|
||||
$ac: 10 + $dex
|
||||
tags:
|
||||
warrior:
|
||||
1:
|
||||
$mod_hp: 20
|
||||
2:
|
||||
$mod_str: 1
|
||||
```
|
||||
|
||||
| 列 | 说明 |
|
||||
| 键 | 说明 |
|
||||
|---|---|
|
||||
| `tag` | 标签名（空表示普通变量声明） |
|
||||
| `threshold` | 激活阈值（可选，默认 `1`）。标签计数值 ≥ 阈值时激活 |
|
||||
| `key` | 变量名，以 `$` 开头 |
|
||||
| `expr` | 表达式，支持数字、`$var` 引用、骰子、算术、函数 |
|
||||
| `vars` | 变量声明映射：`$name: 表达式` |
|
||||
| `tags` | 标签修饰符映射：`标签名 → 阈值 → {$目标: 增量}` |
|
||||
|
||||
标签名可以带或不带 `#` 前缀。阈值是正整数：标签计数值达到该值时，修饰符生效。
|
||||
|
||||
数字会被当作数值，其余一律作为表达式文本（如 `$con*5+$mod_hp`）。
|
||||
|
||||
### 声明类型
|
||||
|
||||
**普通声明**（tag 为空）：`$key` 是一个派生变量，其值由表达式计算。当依赖变量变化时自动重新计算。
|
||||
**普通声明**（`vars`）：`$key` 是一个派生变量，其值由表达式计算。当依赖变量变化时自动重新计算。
|
||||
|
||||
```csv role=declare
|
||||
tag,key,expr
|
||||
,$hp,$con*5+$mod_hp
|
||||
,$ac,10+$dex
|
||||
```yaml role=declare
|
||||
vars:
|
||||
$hp: $con*5 + $mod_hp
|
||||
$ac: 10 + $dex
|
||||
```
|
||||
|
||||
**标签修饰符**（tag 非空）：当源变量的标签映射中 `#tag` 的计数值 ≥ `threshold` 时，`$key` 加上表达式的计算结果。修饰符按阈值独立激活。
|
||||
**标签修饰符**（`tags`）：当源变量的标签映射中 `#tag` 的计数值 ≥ 阈值时，`$key` 加上该值。同一标签的多个阈值会叠加，修饰符按阈值独立激活。
|
||||
|
||||
```csv role=declare
|
||||
tag,threshold,key,expr
|
||||
#warrior,1,$mod_hp,20
|
||||
#warrior,2,$mod_str,1
|
||||
```yaml role=declare
|
||||
tags:
|
||||
warrior:
|
||||
1:
|
||||
$mod_hp: 20
|
||||
2:
|
||||
$mod_str: 1
|
||||
```
|
||||
|
||||
上例中：
|
||||
@@ -141,10 +152,13 @@ tag,threshold,key,expr
|
||||
|
||||
阈值允许同一标签产生不同层级的效果：
|
||||
|
||||
```csv role=declare
|
||||
tag,threshold,key,expr
|
||||
#warrior,1,$mod_hp,10
|
||||
#warrior,3,$mod_hp,20
|
||||
```yaml role=declare
|
||||
tags:
|
||||
warrior:
|
||||
1:
|
||||
$mod_hp: 10
|
||||
3:
|
||||
$mod_hp: 20
|
||||
```
|
||||
|
||||
- `#warrior` 计数 1-2：`$mod_hp` +10
|
||||
@@ -174,14 +188,18 @@ tag,threshold,key,expr
|
||||
|
||||
在文档中定义：
|
||||
|
||||
```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
|
||||
```yaml role=declare
|
||||
vars:
|
||||
$con: 10
|
||||
$dex: 12
|
||||
$hp: $con*5 + $mod_hp
|
||||
$ac: 10 + $dex
|
||||
tags:
|
||||
warrior:
|
||||
1:
|
||||
$mod_hp: 20
|
||||
2:
|
||||
$mod_str: 1
|
||||
```
|
||||
|
||||
在 Journal 中输入：
|
||||
|
||||
Reference in New Issue
Block a user