From d83256e049d4f58ad5e11ecc70c74196f462ae97 Mon Sep 17 00:00:00 2001 From: hypercross Date: Thu, 9 Jul 2026 10:59:37 +0800 Subject: [PATCH] docs: refactor journal-stat documentation structure --- src/doc-entries/journal-stat.md | 147 +++++++++++++++++--------------- 1 file changed, 76 insertions(+), 71 deletions(-) diff --git a/src/doc-entries/journal-stat.md b/src/doc-entries/journal-stat.md index 03d7ca6..5d365d5 100644 --- a/src/doc-entries/journal-stat.md +++ b/src/doc-entries/journal-stat.md @@ -7,46 +7,48 @@ syntax: '```yaml role=stat' props: - name: 定义文件 type: — - desc: 在任意 .md 文档中使用 yaml role=stat 代码块定义属性 + desc: 在任意 .md 文档中使用 ```yaml role=stat 或 ```csv role=stat 代码块定义属性 - name: 命令 type: — desc: /stat set key=value | /stat del key | /stat roll key - name: 属性类型 type: — - desc: number, string, enum, modifier, derived + desc: number, string, enum, modifier, derived, template - name: 权限 type: — - desc: GM 可修改所有属性，玩家只能修改自己的属性 (玩家名:xxx) + desc: GM 可修改所有属性，玩家只能修改自己的属性 --- ## 概述 -属性系统允许你在文档中定义角色属性（如力量、生命值、技能等）， -通过命令设置和掷骰，并在 Journal 面板的属性视图中查看当前值。 +属性系统允许你在文档中定义角色属性，通过命令设置和掷骰， +并在 Journal 面板的属性视图中查看当前值。 属性分为两层： -- **定义**（Schema）：在 markdown 文档的 ` ```yaml role=stat ` 代码块中定义 +- **定义**（Schema）：在 markdown 文档的 ` ```yaml role=stat ` 或 ` ```csv role=stat ` 代码块中定义 - **值**（State）：通过 `/stat set/del/roll` 命令在游戏过程中动态修改 -## 属性类型 +## 代码块语法 -| 类型 | 说明 | 支持掷骰 | +所有属性相关代码块使用统一的属性语法： + + ```lang role=xxx [id=xxx] + +| 属性 | 说明 | 示例 | |---|---|---| -| `number` | 数值，可声明 `roll` 公式 | ✅ | -| `string` | 自由文本 | ❌ | -| `enum` | 枚举选项，掷骰随机选择 | ✅ | -| `modifier` | 修饰值，自动加到 `target` 属性上 | ❌ | -| `derived` | 通过公式从其他属性计算 | ✅ | -| `template` | 查表属性，掷骰匹配范围并应用修饰符 | ✅ | +| `lang` | 代码语言 | `yaml`, `csv` | +| `role` | 块用途 | `stat`（属性定义）, `stat-template`（模板表） | +| `id` | 引用标识 | 模板名称，如 `id=年龄` | -## 属性定义语法 +代码块默认会被**剥离**（不渲染到页面），仅用于数据提取。 +如需保留为可见代码块，添加 `as=codeblock`。 + +## 属性定义 支持两种格式：**YAML**（适合复杂属性）和 **CSV**（适合同质列表）。 ### YAML 格式 -在 `.md` 文档中插入 ` ```yaml role=stat ` 代码块： - ```yaml role=stat - key: strength scope: player @@ -100,9 +102,6 @@ props: ### CSV 格式 -对于同质属性列表（如多个 `number` 类型的属性），CSV 更紧凑。 -插入 ` ```csv role=stat ` 代码块： - ```csv role=stat key,label,type,roll mind,心智,number,2d10+20 @@ -122,38 +121,43 @@ CSV 列说明： | `default` | — | — | 默认值 | | `roll` | — | — | 掷骰公式 | | `target` | — | — | modifier 的目标 key | +| `template` | — | — | template 类型引用的模板 id | | `formula` | — | — | derived 的计算公式 | | `options` | — | — | enum 选项，用 `\|` 分隔 | -示例 — enum 属性： +### 属性类型 -```csv role=stat -key,label,type,options -weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 -``` +| 类型 | 说明 | 支持掷骰 | +|---|---|---| +| `number` | 数值，可声明 `roll` 公式 | ✅ | +| `string` | 自由文本 | ❌ | +| `enum` | 枚举选项，掷骰随机选择 | ✅ | +| `modifier` | 修饰值，自动加到 `target` 属性上 | ❌ | +| `derived` | 通过公式从其他属性计算 | ✅ | +| `template` | 查表属性，掷骰匹配范围并应用修饰符 | ✅ | -### 关键语法说明 +### 关键字段说明 - **`key`**：唯一标识符。使用纯名字（如 `strength`），不用加玩家前缀 - **`scope`**：`player` 或 `global`。`player` 表示每个玩家各自独立的值，运行时 key 为 `玩家名:strength`；`global` 表示所有玩家共享 - **`label`**：在属性视图中显示的名称 -- **`type`**：属性类型（见上表） - **`default`**：默认值，在未通过命令设置时使用 -- **`roll`**：掷骰公式（仅 `number` 类型），支持引用其他属性值（使用 bare key，自动同 scope 解析） -- **`target`**：`modifier` 类型的目标属性 key（bare key，同 scope 内解析） -- **`options`**：`enum` 类型的选项列表，支持多行 `- value` 语法 -- **`formula`**：`derived` 类型的计算公式，支持 `+ - * / floor() ceil() round()`，属性引用使用 bare key +- **`roll`**：掷骰公式（`number` 类型），支持引用其他属性值（bare key，自动同 scope 解析） +- **`target`**：`modifier` 类型的目标属性 key +- **`options`**：`enum` 类型的选项列表，YAML 支持多行 `- value` 语法，CSV 用 `|` 分隔 +- **`formula`**：`derived` 类型的计算公式，支持 `+ - * / floor() ceil() round()` +- **`template`**：`template` 类型引用的模板 id（对应 `id=xxx` 的 stat-template 块） -### 作用域说明 +### 作用域 -`scope: player` 的属性在运行时会自动加上玩家名前缀。例如 Alice 连接时，`strength` 的实际 key 是 `alice:strength`。 +`scope: player` 的属性在运行时自动加上玩家名前缀。Alice 连接时，`strength` 的实际 key 是 `alice:strength`。 -在公式（`roll`、`formula`）和 `target` 中，使用 bare key 即可，系统会自动在相同 scope 内查找： +在公式（`roll`、`formula`）和 `target` 中，使用 bare key 即可，系统自动在相同 scope 内查找： ```yaml role=stat - key: attack scope: player - roll: "1d20 + attack" # attack 自动解析为 alice:attack + roll: "1d20 + attack" # attack 自动解析为 alice:attack - key: str_mod scope: player @@ -162,7 +166,7 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 ## 命令 -所有命令在 Journal 输入框中输入，前缀为 `/stat`。命令中使用 bare key： +所有命令在 Journal 输入框中输入，前缀为 `/stat`： | 命令 | 示例 | 说明 | |---|---|---| @@ -175,31 +179,32 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 - **`number` + `roll`**：解析公式中的属性引用，掷骰，结果写入属性值 - **`enum`**：从选项列表中随机选择一项 - **`derived` + `formula`**：计算公式，结果写入属性值 +- **`template`**：掷模板头部骰子，匹配范围，应用修饰符 -例如 `/stat roll attack` 会： +例如 `/stat roll attack`： 1. 在当前玩家 scope 下查找 `attack` 的定义 -2. 解析 `roll` 公式 `1d20 + attack`，将 `attack` 替换为当前值（含修饰符）→ 如 `1d20 + 3` -3. 掷骰 → 如结果 `15` -4. 将 `15` 写入 `alice:attack`，同步到所有连接的客户端 +2. 解析 `roll` 公式 `1d20 + attack`，将 `attack` 替换为当前值（含修饰符）→ `1d20 + 3` +3. 掷骰 → `15` +4. 将 `15` 写入 `alice:attack`，同步到所有客户端 ## 属性视图 在 Journal 面板顶部点击 **属性** 标签切换视图： -- 属性按 scope 分组（全局属性 + 玩家属性） +- 属性按 scope 分组（全局 + 玩家） - 显示属性名、当前值、默认值 -- 修饰符自动合并显示（`strength = 16` 时，`str_mod` 自动加到 `strength` 上） -- 有掷骰属性的行显示 🎲 按钮，点击可快速掷骰 +- 修饰符自动合并显示 +- 可掷骰的行显示 🎲 按钮 ## 权限 -- **GM**：可以修改所有属性 -- **玩家**：只能修改自己 scope 下的属性（`scope: player` 的属性） +- **GM**：可修改所有属性 +- **玩家**：只能修改 `scope: player` 的属性 - **观察者**：不能修改任何属性 -## 修饰符（modifier）详解 +## 修饰符（modifier） -修饰符类型的属性会自动加到其 `target` 属性上： +修饰符自动加到 `target` 属性上： ```yaml role=stat - key: strength @@ -213,12 +218,12 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 target: strength ``` -如果 `/stat set str_mod=3`，则 `strength` 的**计算值**为 `10 + 3 = 13`。 -多个修饰符指向同一个目标时会累加。 +`/stat set str_mod=3` 后，`strength` 的计算值为 `10 + 3 = 13`。 +多个修饰符指向同一目标时累加。 -## 派生属性（derived）详解 +## 派生属性（derived） -派生属性通过公式从其他属性计算： +通过公式从其他属性计算： ```yaml role=stat - key: hp_max @@ -227,15 +232,14 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 formula: "strength * 2 + 10" ``` -公式中引用其他属性时，会自动使用其计算值（包含修饰符）。 +公式引用其他属性时自动使用计算值（含修饰符）。 支持的函数：`floor(x)`, `ceil(x)`, `round(x)`。 -## 模板属性（template）详解 +## 模板属性（template） -模板属性用于查表掷骰，例如年龄表、职业表等。 +模板属性用于查表掷骰（年龄表、职业表等）。 -模板在独立的 CSV 代码块中定义，使用 `role=stat-template` 和 `id=模板名`。 -**第一列是骰子表达式**（如 `1d10`），第二列是 `label`，其余列为修饰符： +**第一步：定义模板表** ```csv id=年龄 role=stat-template 1d10,label,heart,mind,strength,speed @@ -245,12 +249,12 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 10,换躯者,,,+30,-10 ``` -- **第一列（header）**：骰子表达式，如 `1d10`、`2d6` -- **第一列（rows）**：匹配范围，支持 `1-3`（区间）、`4`（精确）、`1-3,5`（多个） -- **`label` 列**：显示名称 -- **其余列**：修饰符键名，值为变化量（正数加、负数减、空表示不修改） +- **第一列（header）**：骰子表达式，如 `1d10` +- **第一列（rows）**：匹配范围，`1-3`（区间）、`4`（精确）、`1-3,5`（多个） +- **`label`**：显示名称 +- **其余列**：修饰符键名，值为变化量（`+`加、`-`减、空不修改） -然后在属性定义中引用模板： +**第二步：引用模板** ```yaml role=stat - key: age @@ -260,17 +264,20 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 template: 年龄 ``` -`/stat roll age` 时： -1. 掷 `1d10`（模板头部的骰子表达式） -2. 匹配第一列获取条目 -3. 发布 `set age=青少年` -4. 同时发布 `set alice:heart=52`（原始值 +20）、`set alice:mind=22`（-10）等 +**第三步：掷骰或直接设置** -修饰符值中的 `+`/`-` 前缀表示相对调整。如果 modifiers 值是 `+20`，会在当前值基础上加 20；如果是 `-10`，会减 10。 +- `/stat roll age` — 掷 `1d10`，匹配范围，应用修饰符 +- `/stat set age=换躯者` — 直接设置，同样应用修饰符 + +`/stat roll age` 或 `/stat set age=青少年` 时： +1. 发布 `set age=青少年` +2. 同时发布 `set alice:heart=52`（原始值 +20）、`set alice:mind=22`（-10） + +修饰符值中的 `+`/`-` 前缀表示相对调整，基于当前值计算。 ## 掷骰公式中的属性引用 -`roll` 字段中的标识符会自动替换为当前属性值： +`roll` 字段中的标识符自动替换为当前属性值： ```yaml role=stat - key: attack @@ -278,6 +285,4 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 type: number default: 0 roll: "1d20 + attack + str_mod" -``` - -`/stat roll alice:attack` 时，`alice:attack` 和 `alice:str_mod` 会被替换为当前值后再掷骰。 \ No newline at end of file +``` \ No newline at end of file