From 3c2f8a0978e3d3e0361a74348190ccc866c0cc3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=99=8D=E6=98=9F=E9=A9=B0?=
 <107794984+starrybamboo@users.noreply.github.com>
Date: Thu, 28 May 2026 14:27:44 +0800
Subject: [PATCH] docs: complete WebGAL script reference gaps

---
 src/.vuepress/sidebar/zh.ts                   |  1 +
 src/config.md                                 |  1 +
 src/script-reference/commands/applyStyle.md   | 16 ++++
 src/script-reference/commands/callSteam.md    | 39 ++++++++++
 src/script-reference/commands/changeBg.md     | 22 ++++++
 src/script-reference/commands/changeFigure.md | 34 +++++++-
 src/script-reference/commands/choose.md       | 41 ++++++++++
 src/script-reference/commands/getUserInput.md |  4 +
 src/script-reference/commands/intro.md        |  6 +-
 src/script-reference/commands/jumpLabel.md    | 18 +++++
 src/script-reference/commands/playEffect.md   | 11 +++
 src/script-reference/commands/say.md          |  6 ++
 src/script-reference/commands/setTextbox.md   |  3 +-
 src/script-reference/commands/setTransform.md |  6 ++
 src/webgal-script/animation.md                | 77 ++++++++++++++++---
 src/webgal-script/base.md                     | 22 ++++++
 16 files changed, 294 insertions(+), 13 deletions(-)
 create mode 100644 src/script-reference/commands/callSteam.md

diff --git a/src/.vuepress/sidebar/zh.ts b/src/.vuepress/sidebar/zh.ts
index 990b22632..29a3adc6f 100644
--- a/src/.vuepress/sidebar/zh.ts
+++ b/src/.vuepress/sidebar/zh.ts
@@ -92,6 +92,7 @@ export const zhSidebar = sidebar({
             "getUserInput",
             "applyStyle",
             "wait",
+            "callSteam",
           ]
         },
         {
diff --git a/src/config.md b/src/config.md
index 8afc335cc..38c1ea6e1 100644
--- a/src/config.md
+++ b/src/config.md
@@ -15,6 +15,7 @@
 | Legacy_Expression_Blend_Mode | 是否启用 Live2D 的旧表情混合模式，设置为 true 或 false      |
 | Max_line                     | 文本框的最大显示行数                                        |
 | Line_height                  | 文本框的行高（单位：em）                                    |
+| Steam_AppID                  | Steam 应用 ID，用于初始化 Steam 集成，仅在 Electron 构建环境下有效 |
 
 以下是配置文件示例：
 
diff --git a/src/script-reference/commands/applyStyle.md b/src/script-reference/commands/applyStyle.md
index 39a7fa696..7c150b3a7 100644
--- a/src/script-reference/commands/applyStyle.md
+++ b/src/script-reference/commands/applyStyle.md
@@ -23,3 +23,19 @@ applyStyle:原样式名->新样式名1;
 applyStyle:新样式名1->新样式名2; 错误
 applyStyle:原样式名->新样式名2;
 ```
+
+## 常用可替换样式
+
+选择枝使用以下样式名：
+
+| 样式名 | 作用 |
+| :--- | :--- |
+| `Choose_Main` | 选项列表容器 |
+| `Choose_item_outer` | 单个选项的外层容器 |
+| `Choose_item` | 可点击选项 |
+| `Choose_item_disabled` | 条件未满足、不可点击的选项 |
+
+```webgal
+; 将可点击选项替换成模板中定义的 Choose_item_Red
+applyStyle:Choose_item->Choose_item_Red;
+```
diff --git a/src/script-reference/commands/callSteam.md b/src/script-reference/commands/callSteam.md
new file mode 100644
index 000000000..1c0df1930
--- /dev/null
+++ b/src/script-reference/commands/callSteam.md
@@ -0,0 +1,39 @@
+# callSteam
+
+通过 Electron / Steam 桥接解锁 Steam 成就。
+
+:::warning 平台限制
+此命令仅在具备 Steam / Electron 桥接能力的构建环境下有效。普通网页部署（浏览器直接访问）无法使用此命令，引擎会跳过调用并返回失败结果。
+:::
+
+## 前置配置
+
+在 `game/config.txt` 中填写 `Steam_AppID`，WebGAL 会在启动时初始化 Steam 集成。
+
+```text
+Steam_AppID:480;
+```
+
+详情请见[编辑游戏配置](../../config.md)。
+
+## 语句内容
+
+无语句内容，所有参数通过参数名传入。
+
+## 参数
+
+### achievementId
+- 字符串
+
+填写要解锁的 Steam 成就 ID，与 Steam 后台配置的成就 API 名称一致。
+
+```webgal
+callSteam: -achievementId=ACH_WIN_ONE_GAME;
+```
+
+## 示例
+
+```webgal
+; 解锁成就
+callSteam: -achievementId=ACH_WIN_ONE_GAME;
+```
diff --git a/src/script-reference/commands/changeBg.md b/src/script-reference/commands/changeBg.md
index d416a28ab..3274b1b27 100644
--- a/src/script-reference/commands/changeBg.md
+++ b/src/script-reference/commands/changeBg.md
@@ -60,3 +60,25 @@ changeBg:bg.png -unlockname=MyCg01;
 ```webgal
 changeBg:bg.png -unlockname=MyCg01 -series=MySeries01;
 ```
+
+### enterDuration
+- 数字
+- 单位：毫秒
+- 范围：0 到正无穷
+
+入场动画时长。若未填写，默认取 `duration` 的值。
+
+```webgal
+changeBg:bg.png -enterDuration=500;
+```
+
+### exitDuration
+- 数字
+- 单位：毫秒
+- 范围：0 到正无穷
+
+退场动画时长。若未填写，默认值为 1500。
+
+```webgal
+changeBg:bg.png -exitDuration=800;
+```
diff --git a/src/script-reference/commands/changeFigure.md b/src/script-reference/commands/changeFigure.md
index 259af389b..9b01bda86 100644
--- a/src/script-reference/commands/changeFigure.md
+++ b/src/script-reference/commands/changeFigure.md
@@ -93,6 +93,28 @@ changeFigure:1/open_eyes.png -duration=200;
 changeFigure:1/open_eyes.png -ease=easeOut;
 ```
 
+### enterDuration
+- 数字
+- 单位：毫秒
+- 范围：0 到正无穷
+
+入场动画时长。若未填写，默认取 `duration` 的值（默认 300）。
+
+```webgal
+changeFigure:1/open_eyes.png -enterDuration=200;
+```
+
+### exitDuration
+- 数字
+- 单位：毫秒
+- 范围：0 到正无穷
+
+退场动画时长。若未填写，默认值为 450。
+
+```webgal
+changeFigure:1/open_eyes.png -exitDuration=300;
+```
+
 ### left
 - 布尔值
 
@@ -152,6 +174,16 @@ changeFigure:1/open_eyes.png -id=aaa -zIndex=2;
 changeFigure:2/open_eyes.png -id=bbb -zIndex=1;
 ```
 
+### blendMode
+- 字符串
+- 默认值：`normal`
+
+设置立绘的混合模式。仅在立绘出场或替换立绘时生效。
+
+```webgal
+changeFigure:1/open_eyes.png -id=aaa -blendMode=add;
+```
+
 ### clear
 - 布尔值
 
@@ -173,7 +205,7 @@ changeFigure:1/open_eyes.png -none;
 ### animationFlag
 - 字符串
 
-动画标志，暂无实际作用。
+图片立绘差分动画标志。当前云端引擎会将此值写入 `figureAssociatedAnimation`，但嘴型同步和眨眼动画实际按目标立绘 id 读取 `mouthOpen`、`mouthHalfOpen`、`mouthClose`、`eyesOpen`、`eyesClose` 等差分资源；`animationFlag` 本身暂未被后续逻辑读取。
 
 ### mouthOpen
 - 字符串
diff --git a/src/script-reference/commands/choose.md b/src/script-reference/commands/choose.md
index dd6b586ba..45adb7d24 100644
--- a/src/script-reference/commands/choose.md
+++ b/src/script-reference/commands/choose.md
@@ -18,3 +18,44 @@ choose:去商店:chapter_01/shop.txt|某人家里:chapter_01/house_b.txt|待在
 label:home;
 角色A:还是待在家里吧。;
 ```
+
+在玩家选择一个选项前，`choose` 会暂停后续剧情和自动播放。玩家点击选项后，选项会消失，剧情会跳转到对应的场景文件或标签。
+
+### 条件展示和条件启用
+
+每个选项可以在选项文本前添加条件前缀：
+
+- `(条件表达式)`：控制选项是否显示。
+- `[条件表达式]`：控制选项是否可点击。
+- `->`：分隔条件前缀和实际选项内容。
+
+```webgal
+setVar:hasTicket=true;
+setVar:doorPower=1;
+choose:(hasTicket==true)->出示门票:ticket|(doorPower>0)[doorPower>1]->强行开门:force|回家:home;
+;
+label:ticket;
+角色A:有票就能进去了。;
+jumpLabel:end;
+;
+label:force;
+角色A:力量足够时才能选择这里。;
+jumpLabel:end;
+;
+label:home;
+角色A:还是先回家吧。;
+;
+label:end;
+```
+
+在上面的例子中：
+
+- `出示门票` 只有在 `hasTicket==true` 时显示。
+- `强行开门` 只有在 `doorPower>0` 时显示，且只有在 `doorPower>1` 时可点击。
+- 没有条件前缀的选项始终显示且可点击。
+
+条件表达式的写法与通用参数 `-when` 相同，详情请见 [(global)](global.md#when)。
+
+::: warning
+`()` 和 `[]` 必须写在 `->` 左侧。若选项文本中需要显示冒号、分号或竖线等特殊符号，请使用转义写法，详情请见[特殊符号转义](../../webgal-script/base.md#特殊符号转义)。
+:::
diff --git a/src/script-reference/commands/getUserInput.md b/src/script-reference/commands/getUserInput.md
index 24ec943ba..b2a4f56ab 100644
--- a/src/script-reference/commands/getUserInput.md
+++ b/src/script-reference/commands/getUserInput.md
@@ -12,6 +12,8 @@ getUserInput:player_name -title=您的名字 -buttonText=确认 -defaultValue=Bo
 角色B:{player_name}，我记住了。;
 ```
 
+玩家确认输入后，引擎会写入变量、关闭输入框，并继续执行下一句。若设置了输入校验且校验失败，则会停留在输入框，不会写入变量。
+
 ## 参数
 
 ### title
@@ -41,6 +43,8 @@ getUserInput:player_name -buttonText=确认;
 getUserInput:player_name -defaultValue=Bob;
 ```
 
+如果玩家没有输入内容就确认，引擎会把 `defaultValue` 写入变量；如果没有设置 `defaultValue`，则写入一个空格。
+
 ### rule
 - 字符串
 
diff --git a/src/script-reference/commands/intro.md b/src/script-reference/commands/intro.md
index 8f4691de3..5aec8778d 100644
--- a/src/script-reference/commands/intro.md
+++ b/src/script-reference/commands/intro.md
@@ -11,6 +11,8 @@
 intro:这是第一行文字|这是第二行文字|这是第三行文字;
 ```
 
+全屏文字演出结束后会自动关闭，不会遮挡后续对话。连续执行多条 `intro` 时，只会显示当前这一次的全屏文字。
+
 ## 参数
 
 ### fontSize
@@ -90,12 +92,12 @@ intro:这是第一行文字|这是第二行文字|这是第三行文字 -delayTi
 intro:这是一段话 -hold;
 ```
 
-### useForward
+### userForward
 - 布尔值
 
 当值为 `true` 时，需要用户手动点击屏幕，才会显示下一行文字，并设置 `hold` 为 `true`，忽略 `delayTime`。
 当值为 `false` 时，自动显示下一行文字。
 
 ```webgal
-intro:这是一段话 -useForward;
+intro:这是一段话 -userForward;
 ```
diff --git a/src/script-reference/commands/jumpLabel.md b/src/script-reference/commands/jumpLabel.md
index 542f4d9f4..970a104fc 100644
--- a/src/script-reference/commands/jumpLabel.md
+++ b/src/script-reference/commands/jumpLabel.md
@@ -20,3 +20,21 @@ jumpLabel:think;
 label:correct;
 角色A:对，是兔子玩偶。;
 ```
+
+### 条件跳转
+
+`jumpLabel` 可以配合通用参数 `-when` 使用。条件不满足时，本句会被跳过，剧情继续执行下一句。
+
+```webgal
+setVar:score=2;
+jumpLabel:scoreHigh -when=score>1;
+角色A:分数不足时会看到这里。;
+jumpLabel:scoreEnd;
+;
+label:scoreHigh;
+角色A:分数大于 1，跳转成功。;
+;
+label:scoreEnd;
+```
+
+条件表达式的写法请见 [(global)](global.md#when)。
diff --git a/src/script-reference/commands/playEffect.md b/src/script-reference/commands/playEffect.md
index 41c161bd4..978666326 100644
--- a/src/script-reference/commands/playEffect.md
+++ b/src/script-reference/commands/playEffect.md
@@ -32,3 +32,14 @@ playEffect:rain.wav -id=rain;
 ; 播放一次雷声
 playEffect:thunder.wav;
 ```
+
+### volume
+- 数字
+- 范围：0 到 100
+- 默认值：100
+
+设置音效的音量百分比，0 为静音，100 为最大音量。
+
+```webgal
+playEffect:rain.wav -id=rain -volume=60;
+```
diff --git a/src/script-reference/commands/say.md b/src/script-reference/commands/say.md
index e21276ad4..b5b1eee1c 100644
--- a/src/script-reference/commands/say.md
+++ b/src/script-reference/commands/say.md
@@ -151,3 +151,9 @@ WebGAL 支持声音文件的简化写法。
 ```webgal
 角色A:你好，世界！ -figureId=aaa;
 ```
+
+## 嘴型同步工作流
+
+`vocal`、`left`、`right`、`center`、`figureId` 参数共同构成图片立绘嘴型同步的驱动端。使用前需先通过 `changeFigure` 注册差分图片。
+
+完整工作流请参见[动画效果 - 图片立绘嘴型同步](../../webgal-script/animation.md#图片立绘嘴型同步)。
diff --git a/src/script-reference/commands/setTextbox.md b/src/script-reference/commands/setTextbox.md
index 2dd976665..6ef19ca2d 100644
--- a/src/script-reference/commands/setTextbox.md
+++ b/src/script-reference/commands/setTextbox.md
@@ -5,6 +5,7 @@
 ## 语句内容
 
 填写 `hide` 时，隐藏对话框，其他任何字符串均表示显示对话框。
+常用写法是 `setTextbox:hide;` 隐藏文本框，`setTextbox:on;` 或 `setTextbox:show;` 恢复显示。
 
 ::: info
 用 `setTextbox` 隐藏对话框后，若后续没有其他 `setTextbox` 命令显示对话框，则对话框将一直保持隐藏状态。
@@ -18,6 +19,6 @@
 角色A:带你去一个地方。;
 setTextbox:hide;
 changeBg:shop.png;
-setTextbox:show;
+setTextbox:on;
 角色A:我们到了。;
 ```
diff --git a/src/script-reference/commands/setTransform.md b/src/script-reference/commands/setTransform.md
index eb2c07ef5..7970b99dc 100644
--- a/src/script-reference/commands/setTransform.md
+++ b/src/script-reference/commands/setTransform.md
@@ -32,6 +32,12 @@ changeFigure:1/open_eyes.png -id=aaa;
 setTransform:{"brightness":0.5} -target=aaa -duration=500;
 ```
 
+<!-- @include: ../arguments/ease.md -->
+```webgal
+changeFigure:1/open_eyes.png -id=aaa;
+setTransform:{"position":{"x":-200}} -target=aaa -duration=500 -ease=easeOut;
+```
+
 <!-- @include: ../arguments/writeDefault.md -->
 ```webgal
 changeFigure:1/open_eyes.png -id=aaa;
diff --git a/src/webgal-script/animation.md b/src/webgal-script/animation.md
index c680e2f3e..fea5bf859 100644
--- a/src/webgal-script/animation.md
+++ b/src/webgal-script/animation.md
@@ -13,15 +13,27 @@ setAnimation:enter-from-bottom -target=fig-center -next;
 
 目前，预制的动画有：
 
-| 动画效果      | 动画名              | 持续时间（毫秒）|
-| :------------ | :----------------- | :------------- |
-| 渐入          | enter              | 300            |
-| 渐出          | exit               | 300            |
-| 左右摇晃一次  | shake               | 1000           |
-| 从下侧进入    | enter-from-bottom   | 500            |
-| 从左侧进入    | enter-from-left     | 500            |
-| 从右侧进入    | enter-from-right    | 500            |
-| 前后移动一次  | move-front-and-back | 1000           |
+| 动画效果 | 动画名 | 持续时间（毫秒） |
+| :--- | :--- | :--- |
+| 渐入 | enter | 300 |
+| 渐出 | exit | 300 |
+| 左右摇晃一次 | shake | 1000 |
+| 从下侧进入 | enter-from-bottom | 500 |
+| 从左侧进入 | enter-from-left | 500 |
+| 从右侧进入 | enter-from-right | 500 |
+| 前后移动一次 | move-front-and-back | 1000 |
+| 模糊进入 | blur | 300 |
+| 老电影滤镜 | oldFilm | 0 |
+| 点状滤镜 | dotFilm | 0 |
+| 反射滤镜 | reflectionFilm | 0 |
+| 故障滤镜 | glitchFilm | 0 |
+| RGB 分离滤镜 | rgbFilm | 0 |
+| 光辉滤镜 | godrayFilm | 0 |
+| 移除电影类滤镜 | removeFilm | 0 |
+| 冲击波入场 | shockwaveIn | 2000 |
+| 冲击波退场 | shockwaveOut | 2000 |
+
+这些名称来自 `game/animation/animationTable.json`。持续时间为 0 的预设通常用于立刻设置或清除滤镜状态。
 
 目前，动画的作用目标有：
 
@@ -171,3 +183,50 @@ setTransition: -target=fig-center -enter=enter-from-bottom -exit=exit;
 
 如果不在立绘或背景设置后立即执行进出场效果的设置，等到图像已经进场了，再覆盖进场动画就没有意义了。但如果此时图像还没有出场，设置的出场动画仍有意义。其会在立绘或背景出场时正确地被应用。
 :::
+
+## 图片立绘嘴型同步
+
+WebGAL 支持通过差分图片实现图片立绘的嘴型同步动画。
+
+### 准备差分图片
+
+为角色准备以下差分立绘：
+
+- 默认图（通常为闭嘴状态）
+- 张嘴差分
+- 半张嘴差分
+- 闭嘴差分（可与默认图相同）
+- 可选：睁眼差分、闭眼差分
+
+### 最小示例
+
+**1. 注册差分并上场立绘**
+
+```webgal
+changeFigure:1/normal.png -id=charA -mouthOpen=1/mouth_open.png -mouthHalfOpen=1/mouth_half.png -mouthClose=1/normal.png;
+```
+
+**2. 播放语音并驱动嘴型**
+
+```webgal
+; 通过 id 驱动自由立绘
+角色A:你好，世界！ -vocal=charA_hello.wav -figureId=charA;
+```
+
+引擎会根据语音的实时音量，在 `mouthOpen`、`mouthHalfOpen`、`mouthClose` 三个差分之间切换，模拟嘴型动画。
+
+### 位置立绘示例
+
+```webgal
+; 上场中间立绘并注册差分
+changeFigure:1/normal.png -mouthOpen=1/mouth_open.png -mouthHalfOpen=1/mouth_half.png -mouthClose=1/normal.png;
+
+; 驱动中间立绘嘴型
+角色A:你好，世界！ -vocal=charA_hello.wav -center;
+```
+
+### 限制
+
+- 使用 `vocal` 时，引擎会根据语音音量驱动嘴型；未提供 `vocal` 但指定了 `figureId`、`left`、`right` 或 `center` 时，引擎会用模拟音量驱动目标立绘的嘴型差分。
+- 此功能仅适用于图片立绘。Live2D 立绘有独立的嘴型参数体系，不使用此差分方式。
+- 眨眼差分（`eyesOpen`、`eyesClose`）可选，注册后引擎会自动触发随机眨眼动画。
diff --git a/src/webgal-script/base.md b/src/webgal-script/base.md
index e8c7d2822..01225c722 100644
--- a/src/webgal-script/base.md
+++ b/src/webgal-script/base.md
@@ -13,6 +13,28 @@ WebGAL:你好！; 分号后的内容会被视作注释
 ; 可以直接输入一个分号，然后写一条单行注释
 ```
 
+## 特殊符号转义
+
+WebGAL 脚本使用英文冒号 `:` 分隔命令和内容，使用英文分号 `;` 结束语句并开始行内注释，部分命令还会使用 `|`、`,`、`.` 等符号作为内容语法的一部分。如果你希望这些符号作为普通文本显示，可以在符号前加反斜杠 `\`。
+
+常见需要转义的符号：
+
+| 原符号 | 写法 |
+| :--- | :--- |
+| `:` | `\:` |
+| `,` | `\,` |
+| `.` | `\.` |
+| `;` | `\;` |
+| `|` | `\|` |
+
+```ws
+intro:我会显示出来：\:\,\.\;不信你看看 -hold;
+WebGAL:我会显示出来：\:\,\.\;不信你看看;
+choose:我会显示出来：\:\,\.\;不信你看看:nextLabel;
+```
+
+在文本拓展语法中写 CSS 时，分号同样需要写成 `\;`，否则会被当作 WebGAL 语句注释的开始。
+
 ## `none` 关键词
 
 在设置立绘、BGM、背景等 **资源** 时，通过设置为 `none`，可以关闭这个对象。