hypercross
/
ttrpg-tools
2
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: refactor journal-stat documentation structure

This commit is contained in:
hypercross 2026-07-09 10:59:37 +08:00
parent a4cfcde613
commit d83256e049
1 changed files with 76 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
src/doc-entries/journal-stat.md
View File

@ -7,46 +7,48 @@ syntax: '```yaml role=stat'
props: props:
- name: 定义文件 - name: 定义文件
type: — type: —
desc: 在任意 .md 文档中使用 yaml role=stat 代码块定义属性 desc: 在任意 .md 文档中使用 ```yaml role=stat 或 ```csv role=stat 代码块定义属性
- name: 命令 - name: 命令
type: — type: —
desc: /stat set key=value | /stat del key | /stat roll key desc: /stat set key=value | /stat del key | /stat roll key
- name: 属性类型 - name: 属性类型
type: — type: —
desc: number, string, enum, modifier, derived desc: number, string, enum, modifier, derived, template
- name: 权限 - name: 权限
type: — 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` 命令在游戏过程中动态修改 - **值**（State）：通过 `/stat set/del/roll` 命令在游戏过程中动态修改
## 属性类型 ## 代码块语法
| 类型 | 说明 | 支持掷骰 | 所有属性相关代码块使用统一的属性语法：
```lang role=xxx [id=xxx]
| 属性 | 说明 | 示例 |
|---|---|---| |---|---|---|
| `number` | 数值，可声明 `roll` 公式 | ✅ | | `lang` | 代码语言 | `yaml`, `csv` |
| `string` | 自由文本 | ❌ | | `role` | 块用途 | `stat`（属性定义）, `stat-template`（模板表） |
| `enum` | 枚举选项，掷骰随机选择 | ✅ | | `id` | 引用标识 | 模板名称，如 `id=年龄` |
| `modifier` | 修饰值，自动加到 `target` 属性上 | ❌ |
| `derived` | 通过公式从其他属性计算 | ✅ |
| `template` | 查表属性，掷骰匹配范围并应用修饰符 | ✅ |
## 属性定义语法 代码块默认会被**剥离**（不渲染到页面），仅用于数据提取。
如需保留为可见代码块，添加 `as=codeblock`。
## 属性定义
支持两种格式：**YAML**（适合复杂属性）和 **CSV**（适合同质列表）。 支持两种格式：**YAML**（适合复杂属性）和 **CSV**（适合同质列表）。
### YAML 格式 ### YAML 格式
在 `.md` 文档中插入 ` ```yaml role=stat ` 代码块：
```yaml role=stat ```yaml role=stat
- key: strength - key: strength
scope: player scope: player
@ -100,9 +102,6 @@ props:
### CSV 格式 ### CSV 格式
对于同质属性列表（如多个 `number` 类型的属性），CSV 更紧凑。
插入 ` ```csv role=stat ` 代码块：
```csv role=stat ```csv role=stat
key,label,type,roll key,label,type,roll
mind,心智,number,2d10+20 mind,心智,number,2d10+20
@ -122,38 +121,43 @@ CSV 列说明：
| `default` | — | — | 默认值 | | `default` | — | — | 默认值 |
| `roll` | — | — | 掷骰公式 | | `roll` | — | — | 掷骰公式 |
| `target` | — | — | modifier 的目标 key | | `target` | — | — | modifier 的目标 key |
| `template` | — | — | template 类型引用的模板 id |
| `formula` | — | — | derived 的计算公式 | | `formula` | — | — | derived 的计算公式 |
| `options` | — | — | enum 选项，用 `\|` 分隔 | | `options` | — | — | enum 选项，用 `\|` 分隔 |
示例 — enum 属性： ### 属性类型
```csv role=stat | 类型 | 说明 | 支持掷骰 |
key,label,type,options |---|---|---|
weather,天气,enum,晴天\|阴天\|雨天\|暴风雨 | `number` | 数值，可声明 `roll` 公式 | ✅ |
``` | `string` | 自由文本 | ❌ |
| `enum` | 枚举选项，掷骰随机选择 | ✅ |
| `modifier` | 修饰值，自动加到 `target` 属性上 | ❌ |
| `derived` | 通过公式从其他属性计算 | ✅ |
| `template` | 查表属性，掷骰匹配范围并应用修饰符 | ✅ |
### 关键语法说明 ### 关键字段说明
- **`key`**：唯一标识符。使用纯名字（如 `strength`），不用加玩家前缀 - **`key`**：唯一标识符。使用纯名字（如 `strength`），不用加玩家前缀
- **`scope`**：`player` 或 `global`。`player` 表示每个玩家各自独立的值，运行时 key 为 `玩家名:strength`；`global` 表示所有玩家共享 - **`scope`**：`player` 或 `global`。`player` 表示每个玩家各自独立的值，运行时 key 为 `玩家名:strength`；`global` 表示所有玩家共享
- **`label`**：在属性视图中显示的名称 - **`label`**：在属性视图中显示的名称
- **`type`**：属性类型（见上表）
- **`default`**：默认值，在未通过命令设置时使用 - **`default`**：默认值，在未通过命令设置时使用
- **`roll`**：掷骰公式（仅 `number` 类型），支持引用其他属性值（使用 bare key，自动同 scope 解析） - **`roll`**：掷骰公式（`number` 类型），支持引用其他属性值（bare key，自动同 scope 解析）
- **`target`**：`modifier` 类型的目标属性 key（bare key，同 scope 内解析） - **`target`**：`modifier` 类型的目标属性 key
- **`options`**：`enum` 类型的选项列表，支持多行 `- value` 语法 - **`options`**：`enum` 类型的选项列表，YAML 支持多行 `- value` 语法，CSV 用 `|` 分隔
- **`formula`**：`derived` 类型的计算公式，支持 `+ - * / floor() ceil() round()`，属性引用使用 bare key - **`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 ```yaml role=stat
- key: attack - key: attack
scope: player scope: player
roll: "1d20 + attack" # attack 自动解析为 alice:attack roll: "1d20 + attack" # attack 自动解析为 alice:attack
- key: str_mod - key: str_mod
scope: player scope: player
@ -162,7 +166,7 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
## 命令 ## 命令
所有命令在 Journal 输入框中输入，前缀为 `/stat`。命令中使用 bare key： 所有命令在 Journal 输入框中输入，前缀为 `/stat`：
| 命令 | 示例 | 说明 | | 命令 | 示例 | 说明 |
|---|---|---| |---|---|---|
@ -175,31 +179,32 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
- **`number` + `roll`**：解析公式中的属性引用，掷骰，结果写入属性值 - **`number` + `roll`**：解析公式中的属性引用，掷骰，结果写入属性值
- **`enum`**：从选项列表中随机选择一项 - **`enum`**：从选项列表中随机选择一项
- **`derived` + `formula`**：计算公式，结果写入属性值 - **`derived` + `formula`**：计算公式，结果写入属性值
- **`template`**：掷模板头部骰子，匹配范围，应用修饰符
例如 `/stat roll attack` 会： 例如 `/stat roll attack`：
1. 在当前玩家 scope 下查找 `attack` 的定义 1. 在当前玩家 scope 下查找 `attack` 的定义
2. 解析 `roll` 公式 `1d20 + attack`，将 `attack` 替换为当前值（含修饰符）→ 如 `1d20 + 3` 2. 解析 `roll` 公式 `1d20 + attack`，将 `attack` 替换为当前值（含修饰符）→ `1d20 + 3`
3. 掷骰 → 如结果 `15` 3. 掷骰 → `15`
4. 将 `15` 写入 `alice:attack`，同步到所有连接的客户端 4. 将 `15` 写入 `alice:attack`，同步到所有客户端
## 属性视图 ## 属性视图
在 Journal 面板顶部点击 **属性** 标签切换视图： 在 Journal 面板顶部点击 **属性** 标签切换视图：
- 属性按 scope 分组（全局属性 + 玩家属性） - 属性按 scope 分组（全局 + 玩家）
- 显示属性名、当前值、默认值 - 显示属性名、当前值、默认值
- 修饰符自动合并显示（`strength = 16` 时，`str_mod` 自动加到 `strength` 上） - 修饰符自动合并显示
- 有掷骰属性的行显示 🎲 按钮，点击可快速掷骰 - 可掷骰的行显示 🎲 按钮
## 权限 ## 权限
- **GM**：可以修改所有属性 - **GM**：可修改所有属性
- **玩家**：只能修改自己 scope 下的属性（`scope: player` 的属性） - **玩家**：只能修改 `scope: player` 的属性
- **观察者**：不能修改任何属性 - **观察者**：不能修改任何属性
## 修饰符（modifier）详解 ## 修饰符（modifier）
修饰符类型的属性会自动加到其 `target` 属性上： 修饰符自动加到 `target` 属性上：
```yaml role=stat ```yaml role=stat
- key: strength - key: strength
@ -213,12 +218,12 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
target: strength 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 ```yaml role=stat
- key: hp_max - key: hp_max
@ -227,15 +232,14 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
formula: "strength * 2 + 10" formula: "strength * 2 + 10"
``` ```
公式中引用其他属性时，会自动使用其计算值（包含修饰符）。 公式引用其他属性时自动使用计算值（含修饰符）。
支持的函数：`floor(x)`, `ceil(x)`, `round(x)`。 支持的函数：`floor(x)`, `ceil(x)`, `round(x)`。
## 模板属性（template）详解 ## 模板属性（template）
模板属性用于查表掷骰，例如年龄表、职业表等。 模板属性用于查表掷骰（年龄表、职业表等）。
模板在独立的 CSV 代码块中定义，使用 `role=stat-template` 和 `id=模板名`。 **第一步：定义模板表**
**第一列是骰子表达式**（如 `1d10`），第二列是 `label`，其余列为修饰符：
```csv id=年龄 role=stat-template ```csv id=年龄 role=stat-template
1d10,label,heart,mind,strength,speed 1d10,label,heart,mind,strength,speed
@ -245,12 +249,12 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
10,换躯者,,,+30,-10 10,换躯者,,,+30,-10
``` ```
- **第一列（header）**：骰子表达式，如 `1d10`、`2d6` - **第一列（header）**：骰子表达式，如 `1d10`
- **第一列（rows）**：匹配范围，支持 `1-3`（区间）、`4`（精确）、`1-3,5`（多个） - **第一列（rows）**：匹配范围，`1-3`（区间）、`4`（精确）、`1-3,5`（多个）
- **`label` 列**：显示名称 - **`label`**：显示名称
- **其余列**：修饰符键名，值为变化量（正数加、负数减、空表示不修改） - **其余列**：修饰符键名，值为变化量（`+`加、`-`减、空不修改）
然后在属性定义中引用模板： **第二步：引用模板**
```yaml role=stat ```yaml role=stat
- key: age - key: age
@ -260,17 +264,20 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
template: 年龄 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 ```yaml role=stat
- key: attack - key: attack
@ -279,5 +286,3 @@ weather,天气,enum,晴天\|阴天\|雨天\|暴风雨
default: 0 default: 0
roll: "1d20 + attack + str_mod" roll: "1d20 + attack + str_mod"
``` ```
`/stat roll alice:attack` 时，`alice:attack` 和 `alice:str_mod` 会被替换为当前值后再掷骰。