fix: script reference description

src/script-reference/arguments/name-bgm.md

@@ -1,5 +1,5 @@
 - 字符串
 
-填写一个名称，BGM 鉴赏将收录该音乐，并以该名称进行展示。如果不填写该参数，或名称为空，则不会收录此音乐。
+填写一个名称，BGM 鉴赏将收录该音乐，并以该名称进行展示。
 
 同一首音乐（严格来说是同路径的音乐）只能拥有一个展示名称。如果同一首音乐以不同的名称被收录多次，仅保留最后一次收录时填写的名称。

src/script-reference/arguments/name-cg.md

@@ -1,5 +1,5 @@
 - 字符串
 
-填写一个名称，CG 鉴赏将收录该图片，并以该名称进行展示。如果不填写该参数，或名称为空，则不会收录此图片。
+填写一个名称，CG 鉴赏将收录该图片，并以该名称进行展示。
 
 同一张图片（严格来说是同路径的图片）只能拥有一个展示名称。如果同一张图片以不同的名称被收录多次，仅保留最后一次收录时填写的名称。

src/script-reference/arguments/transform.md

@@ -5,4 +5,5 @@
 
 ::: warning
 此参数仅在对象入场，或替换对象时生效。如果需要修改在场对象的变换效果，请使用 `setTransform`、`setAnimation`、`setTempAnimation` 等命令。
+若使用了 `enter` 参数指定入场动画，该参数将不起作用。
 :::

src/script-reference/commands/bgm.md

@@ -47,6 +47,7 @@ bgm:02.wav -enter=1500;
 
 ### unlockname
 <!-- @include: ../arguments/name-bgm.md -->
+如果不填写该参数，或名称为空，则不会收录此音乐。
 ```webgal
 bgm:01.wav -unlockname=MyBgm01;
 ```

src/script-reference/commands/changeBg.md

@@ -49,6 +49,7 @@ changeBg:bg.png -ease=easeOut;
 
 ### unlockname
 <!-- @include: ../arguments/name-cg.md -->
+如果不填写该参数，或名称为空，则不会收录此图片。
 ```webgal
 changeBg:bg.png -unlockname=MyCg01;
 ```

src/script-reference/commands/changeFigure.md

@@ -256,7 +256,7 @@ changeFigure:character_a/model.json -expression=sad;
 
 对于 Live2D 立绘，填写 number[4] 数组，拓展或收缩立绘的显示区域。
 以向右和向下为正方向，顺序为 `左,上,右,下`。
-x 轴以向右为正方形向，y 轴以向下为正方向。
+x 轴以向右为正方向，y 轴以向下为正方向。
 
 ::: warning
 此参数仅在立绘出场，或替换立绘时生效。
@@ -289,7 +289,7 @@ changeFigure:character_a/model.json -blink={"blinkInterval":5000,"blinkIntervalR
 
 对于 Live2D 立绘，填写 json 字符串，控制立绘的注视参数。
 通常不需要书写所有的属性, 没填写的属性会继承上一次设置的值, 立绘出场时会继承默认值。
-x 轴以向右为正方形向，y 轴以向上为正方向。
+x 轴以向右为正方向，y 轴以向上为正方向。
 
 参数有
 - `"x"`: 数字，注视点的 x 坐标，范围 -1 到 1，默认值 0

src/script-reference/commands/changeScene.md

@@ -7,6 +7,15 @@
 填写场景文件的路径，将切换到对应场景。
 详情请见[场景与分支](../../webgal-script/scenes.md)。
 
+如果此命令成功执行，当前场景的后续命令将不会被执行。
+
+```webgal
+角色A:该出发了。;
+changeScene:chapter_01/part_02.txt;
+调试对话:如果你看到了这句话，说明切换场景失败了。;
+调试对话:因为 changeScene 成功执行的话，位于它后面的命令将不会被执行。;
+```
+
 ::: warning
 切换场景不会清空当前场景（如立绘、背景），若没有主动关闭，它们将被带到新场景中。
 :::

src/script-reference/commands/choose.md

@@ -18,3 +18,6 @@ choose:去商店:chapter_01/shop.txt|某人家里:chapter_01/house_b.txt|待在
 label:home;
 角色A:还是待在家里吧。;
 ```
+
+如果选择了跳转至「场景文件」的选项，当前场景的后续命令将不会被执行。
+如果选择了无效的选项（如跳转目标不存在），WebGAL 会继续执行当前场景的后续命令。

src/script-reference/commands/global.md

@@ -52,13 +52,15 @@ setVar:coin=10;
 ;
 label:buy;
 ;
-setVar:coin=coin-3 -when=coin>=3;
-角色名:花 3 块钱买汽水，剩下 {coin} 块。
-;
-角色名:没钱买 3 块钱的汽水了，只剩下 {coin} 块。 -when=coin<3; 
-jumpLabel:start -when=coin<3;
+jumpLabel:not_enough_coin -when=coin<3;
 ;
+setVar:coin=coin-3;
+角色名:花 3 块钱买汽水，剩下 {coin} 块。;
 jumpLabel:buy;
+;
+label:not_enough_coin;
+角色名:没钱买 3 块钱的汽水了，只剩下 {coin} 块。;
+jumpLabel:start;
 ```
 
 ### continue

src/script-reference/commands/label.md

@@ -10,3 +10,7 @@
 ```webgal
 label:myLabel;
 ```
+
+每个标签在一个场景文件中只能 **定义一次** ，但不同场景文件可以使用相同的标签名称。
+
+如果在同一场景文件中定义了多个同名标签，像 `choose` 和 `jumpLabel` 这样的命令会从场景文件的开头，从上往下搜索，跳转到第一个符合条件的标签位置。

src/script-reference/commands/setAnimation.md

@@ -33,10 +33,10 @@ setAnimation:shake -target=aaa -writeDefault;
 <!-- @include: ../arguments/keep.md -->
 ```webgal
 ; 假设这是一个特别长的动画
-setAnimation:shake -target=aaa -keep;
+setAnimation:shake -target=aaa -keep -next;
 角色A: 第一句话;
 角色A: 第二句话;
 角色A: 第三句话;
 ; 这会打断 aaa 的跨语句动画，并播放新动画
-setAnimation:rotate -target=aaa -keep;
+setAnimation:rotate -target=aaa -keep -next;
 ```

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:{"brightness":0.5} -target=aaa -duration=500 -ease=linear;
+```
+
 <!-- @include: ../arguments/writeDefault.md -->
 ```webgal
 changeFigure:1/open_eyes.png -id=aaa;
@@ -41,10 +47,10 @@ setTransform:{"brightness":0.5} -target=aaa -duration=500 -writeDefault;
 <!-- @include: ../arguments/keep.md -->
 ```webgal
 ; 假设这是一个特别长的动画
-setTransform:{"scale":{"x":2,"y":2}} -target=aaa -duration=10000 -keep;
+setTransform:{"scale":{"x":2,"y":2}} -target=aaa -duration=10000 -keep -next;
 角色A: 第一句话;
 角色A: 第二句话;
 角色A: 第三句话;
 ; 这会打断 aaa 的跨语句动画，并播放新动画
-setTransform:{"scale":{"x":1,"y":1}} -target=aaa -duration=10000 -keep;
+setTransform:{"scale":{"x":1,"y":1}} -target=aaa -duration=10000 -keep -next;
 ```

src/script-reference/commands/setVar.md

@@ -16,29 +16,35 @@ WebGAL 会尝试将无法识别的值类型，转换为字符串。
 
 ```webgal
 setVar:char_b_fav=15; 角色 B 初始好感度
+;
 角色B:呐呐，看不看得出来我今天哪里不一样？;
-choose:缎带:add|你变胖了:minus;
+choose:缎带:good_answer|你变胖了:bad_answer; 根据玩家的选择，跳转到不同的标签位置
 ;
-label:add;
-角色A:是换了缎带吧。;
+label:good_answer;
+玩家:是换了缎带吧。;
 setVar:char_b_fav=char_b_fav+10; 角色 B 好感度 +10;
 角色B:答对了，怎么样，你觉得好看吗？;
-角色A:嗯，很适合你。;
-jumpLabel:go_out;
+玩家:嗯，很适合你。;
+jumpLabel:ask_go_out; 跳转到 ask_go_out 标签，避开下面的 bad_answer 部分
 ;
-label:minus;
-角色A:你变胖了。;
+label:bad_answer;
+玩家:你变胖了。;
 setVar:char_b_fav=char_b_fav-10; 角色 B 好感度 -10;
 角色B:你这人好无趣唉......;
 ;
-label:go_out;
-角色A:对了，今天晚上你有空吗？;
+label:ask_go_out;
+玩家:对了，今天晚上你有空吗？;
+;
+jumpLabel:not_enough_fav -when=char_b_fav<10; 如果好感度小于 10，跳转到 not_enough_fav 标签
 ;
-角色B:今晚没有安排，怎么了？ -when=char_b_fav>10;
-changeScene:chapter_01/part_02.txt -when=char_b_fav>10;
+角色B:今晚没有安排，怎么了？;
+changeScene:chapter_01/part_02.txt;
+;
+label:not_enough_fav;
 ;
 角色B:没有。不好意思我先走了。;
 :角色 B 离开了。;
+changeScene:chapter_02/part_01.txt;
 ;
 ```
 
@@ -52,15 +58,21 @@ changeScene:chapter_01/part_02.txt -when=char_b_fav>10;
 
 ```webgal
 ; 假设这是新游戏的开头
+; 如果已经是多周目了，就直接跳到多周目专用的剧情
 jumpLabel:another_life -when=multiple_playthroughs;
 ;
-setVar:multiple_playthroughs=false -global; 是否为多周目游戏
+; 否则认为是第一周目，初始化变量并进入第一周目的剧情
+setVar:multiple_playthroughs=false -global; 初始化为非多周目
 changeScene:chapter_01/part_01.txt;
 ;
+; 这里是多周目专用的剧情
+; 只有当 multiple_playthroughs 为 true 时才会跳转到这里
 label:another_life;
 神秘的声音:如果有机会，你会选择过另一种人生吗？;
 changeScene:chapter_01/part_01_extra.txt;
 ;
+; ......
+;
 ; 假设这是最后一章的结束部分
-setVar:multiple_playthroughs=true -global; 设置为多周目游戏
+setVar:multiple_playthroughs=true -global; 设置为多周目
 ```

src/script-reference/others/animation-reference.md

@@ -70,7 +70,7 @@ setTempAnimation:[{"duration":0},{"position":{"x":500},"duration":500},{"positio
 您仍然可以为第一个片段设置变换效果属性，这样可以在动画开始时直接跳转到指定状态。
 
 ```webgal
-; 立绘对象初始坐标为 (-500,0)
+; 立绘对象初始坐标为 (0,0)
 changeFigure:character_a/normal.png -id=aaa;
 ; 从左走到右，动画开始时直接跳转到左边
 setTempAnimation:[{"position":{"x":-500},"duration":0},{"position":{"x":500},"duration":1000}] -target=aaa;
@@ -90,26 +90,7 @@ changeFigure:1/open_eyes.png -id=aaa;
 setTempAnimation:[{"position":{"x":-500},"duration":0},{"position":{"x":500},"duration":1000}] -target=aaa;
 ```
 
-### ease
-- 字符串
-
-填写缓动类型，控制动画的缓动效果，默认值为 `easeInOut`，可选值包括
-- `linear`：线性
-- `easeIn`：缓入
-- `easeOut`：缓出
-- `easeInOut`：缓入缓出
-- `circIn`：圆形缓入
-- `circOut`：圆形缓出
-- `circInOut`：圆形缓入缓出
-- `backIn`：起点回弹
-- `backOut`：终点回弹
-- `backInOut`：起止回弹
-- `bounceIn`：起点弹跳
-- `bounceOut`：终点弹跳
-- `bounceInOut`：起止弹跳
-- `anticipate`：预先反向
-
-任何其他字符串都会回退到默认值。
+<!-- @include: ../arguments/ease.md -->
 
 ```webgal
 changeFigure:1/open_eyes.png -id=aaa;