2.7. KAG的语法
2.7.1. 基本格式
KAG使用的剧本格式称作KAG Script，文件扩展名为.ks。
该文件是ANSI或Unicode（UCS2）编码的文本文件，可以用记事本等纯文本编辑器编辑。
脚本内的文字除下面将讲到的注释、命令、段落标签等内容外，一律被当作剧本文本被处理显示。
KS中用于控制引擎动作的部分，本文档一般称之为“命令”。由于KAG可以被视作一种标记语言，所以这些命令也被称作标记（Tag）。
每个标签都可能有若干个属性（也可能完全没有属性），用于精确控制指令的行为。调用中传递的属性一般都需要附带一个属性值，定义该属性指定的具体对象（例如对于“目标文件(storage)”这样的属性，属性值一般就是文件名），但在特殊情况下也可能不需要指定这个值。
2.7.2. 标记命令
标记命令类似于HTML等标记语言，可以将控制指令插入文本当中。
命令的格式为：
[命令名 属性1=值1 属性2=值2...]
例 2.1. 标记命令的范例
以下的代码将在KAGeXpress中显示一幅背景图片。
下面是说明使用方法的例子。这是一句话，[r]可以插入标记。[l][r]
当然在行首插入标记命令也是可以的。[l][r]
比如像这样。[l][r]

bg是切换背景的命令，l和r是文字排版相关的命令。关于这些命令的详细功能将在解说命令时说明。详细请参见第 3 章 KAGeXpress使用入门
这种命令格式可以随意插入剧本文字中。
2.7.3. 行命令
用类似于NScripter的指令格式书写命令标签，一般占用单独的一行，用于较长的指令。
命令的格式为：
@命令名 属性1=值1 属性2=值2...
这种语法格式一般要求一条命令单独使用一行。
例 2.2. 行命令的范例
@bg file=图片1
下面是使用方法的例子。@bg file=图片1
一般来说，行命令是单独占用一行的。
请注意，KAG的标记命令和行命令两种格式在效果上是等效的。
上面的例子，和标记命令的例子执行的结果是完全相同的。
下文介绍其他命令时，将只说明命令的名称。例如，我们说到的“p命令”或“p标记”，其正确的调用方法是在ks中插入“[p]”或者“@p”。
2.7.4. 段落标签
段落标签占用单独的一行，代表了一个段落/章节的开始。
分支选项、剧本跳跃、进度的存取都以段落标签作为标志。例如剧本跳跃时，就只能跳跃到指定段落标签的开始。
命令的格式为：
*标签名|显示名
标签名是标签的内部名称，建议使用简单但不重复的英文数字组合。
显示名是显示在存档界面等地方的名称，可以使用较复杂的中文名。
例 2.3. 段落标签的范例
*ch01|第一章
这里是华丽的第一章。[l][r]
则如果在这章内（这个标签后，下一个标签前）存档，存档界面中显示该存档的进度名称为“第一章”。
每次系统跳转到这个段落的时候，就会从段落标示的地方开始执行。

与段落跳转相关的命令将在下文说明。详情参见第 3.5 节
“控制剧本流程”
2.7.5. 注释
以;符号开始，从分号到该行结尾的所有内容将被忽略。
注释主要用于写入开发者的备忘、代码说明等内容。
例 2.4. 注释的范例
*ch01|第一章
这里是华丽的第一章。[l][r] ;这是注释1
;这是注释2

2.8. 关于渐变的类型、参数和使用
渐变效果是ADV制作中最经常用到的效果。ADV游戏经常包含图像的切换。如果毫无过渡的更换图像，效果一般会显得非常糟糕。因而，淡入、淡出等图像效果几乎是每一个ADV游戏必然会使用的。加入这些效果，可以使得图像的切换更加平滑，让游戏感觉更加精细。
KAG中，淡入、淡出这些在一定的时间内改变图像的功能都使用统一的渐变效果来实现。KAGeXpress的背景切换等效果，也被设计为可以调用渐变效果。使用的渐变效果的类型在KAGeXpress中都可以由method属性指定。
KAG包含了多种的渐变方式。吉里吉里内核自嵌了3种类型的渐变，此外通过外部插件，还可以增加新的渐变效果。
所有调用的渐变的指令都需要通过time属性指定时间，对于KAGeXpress的图像指令，未指定时间的渐变视作要求新的图像直接出现。
以下的图例中，A为渐变前的图像（下面称作原图像），B为用来取代原图像的目标图像（下面称作新图像）。
2.8.1. crossfade
最简单、最常用的渐变类型。要渐变的部分渐渐从原图像变为新图像。
没有特别的属性需要指定。
2.8.2. universal
一种独特的渐变类型。可以按照使用者的要求，按照任意顺序与方式渐变整个区域。
使用时，必须提供一个规则文件，指定渐变的规则。该文件必须是灰阶的图像。
请看以下的样图。

图 2.4. 规则文件的样例
系统将按照这个规则文件的灰度，从对应规则文件黑色的部分渐渐渐变到对应白色部分。
对于上述的规则文件，系统将从上到下（对应规则文件中从黑到白）将屏幕上的A渐变为B。
此外，这种类型的渐变可以设定渐变区域属性（vague属性），指定过渡区域（也就是转换中，同时显示出原图像和新图像的区域）的大小。
这是vague=1的场合。
这是vague=64的场合。
图 2.5. 渐变区域（vague）属性设定样例
指定不同vague值产生的差别可以参看上图。
对于KAGeXpress，默认的vague值为64。
下面是universal渐变属性详细列表：
表 2.4. universal渐变的使用的属性列表
属性名称
是否必须
说明
rule
是
指定决定通用渐变的轨迹的，规则文件的名称。
该文件必须是灰度图像数据。
系统将从该图像中黑色部分所对应的原图部分开始渐变，渐渐按照顺序开始处理图像中白色的部分。
vague
否
决定过渡区域，也就是同时进行转换的区域的大小。
2.8.3. scroll
scroll类型的渐变，如同其字面意思一样，就是让新图像从外面移动进入原图像的区域。
新的图像可以任意选择从上、下、左、右四个方向中的任意一个进入，这个效果可以通过from属性指定。
本节讲解scroll时使用的样图，进入方向都为下，也就是从下方进入屏幕。
此外，实际上scroll渐变的类型还包括三种，由参数stay控制。
这是stay=stayfore的场合。
这是stay=stayback的场合。
这是stay=nostay的场合。
图 2.6. scroll渐变卷动类型（stay）属性设定样例
三种不同的效果如上图所示。
首先，stay=stayfore时，原图像将原地不动，而新图像从外向里移动。当进入方向是从下方进入时，看起来是如同下图这样的。
stay=stayback时，原图像将从进入方向的反方向被抽走，而露出没有移动的新图像。
stay=nostay时，原图像和新图像将同时向同一方向移动，直到新图像取代旧图像。
下面是scroll渐变属性详细列表：
表 2.5. scroll渐变的使用的属性列表
属性名称
是否必须
说明
stay
否
stay=nostay时，原图像和新图像将按相同速度向同一方向移动，直到新图像代替旧图像。
stay=stayfore时，原图像将不会移动，新图像会自外移动进来并覆盖元图像。
stay=stayback时，新图像将不会移动，原图像会被抽走，然后露出新图像。
from
是
指定为left、right、top、bottom，分别可以让新图像从左、右、上、下方向卷入屏幕。

文字显示与控制
KAG允许有多个文字层同时存在。但是默认只用其中的一个来描绘剧本的文字。这个层将会拥有message这个别名。
正常情况下，默认的文字层是message0。这种情况下可以用message0，也可以用message来访问这个层。
默认文字层的尺寸在config.tjs中可以设置，同时也可以通过position（见下）指令设置。
KAGeXpress预置了3种不同的文字层格式，可以通过相关的KAG指令调用。详情见下表。
表 3.1. KAGeXpress的预设文字层参数
名称
调用命令名
说明
全屏文字层
menul
覆盖全屏，背景完全透明的文字层。locate命令的定位将准确定位在屏幕的对应像素上。适合用于菜单、系统界面、字幕等场合。
电子小说文字层
val
覆盖屏幕大部分，有不透明效果的文字层。适合电子小说类游戏（例如Fate、Toheart）使用。
AVG文字层
advl
覆盖屏幕下半部分，有不透明效果的文字层。一般用于单句对话为主的场合，适合对话型AVG类游戏使用。
预设的文字层设置可以在System\Textset.ks中找到并修改，不同种类的预设文字层可以通过命令调用在同一个游戏中交替使用。
KAG没有被包含在命令、注释及分段标签等特殊内容中的文字全部会被当作文字内容处理，显示在默认的文字层中。默认设置下，message0为这个文字层。
例 3.1. 文字显示
*start
这样输入文本，就会被当作文字输出。
执行效果：

剧本文件中，行尾键入的Enter自动会被忽略。如果需要换行，请在需要换行的地方加入指令r。
在文中需要等待点击的时候，请加入指令l。KAG执行到这个指令的时候默认将会显示一个闪烁的记号，并等待点击。
行末等待点击并换行请按照[l][r]这个顺序。否则等待的记号将显示在下一行。
例 3.2. 换行及等待点击
*start
这是第一行，[l][r]
要看到第二行请点击鼠标。
点击鼠标前：

点击鼠标后：

换页时等待点击请使用指令p。请注意默认[p]执行之后页面将被清空。
例 3.3. 换页功能
*start
这是第一行，[l][r]
要看到第二行请点击鼠标。[l][r]
第三行就到了页尾。[p]
这里是新的一页。
点击鼠标前：

点击鼠标后：

清除所有文字可以使用指令er。但因为在一页结束（p标记）后会自动清屏，所以这个命令并不多用。

3.4. 播放音效、音乐
bgm、se、vo这三个功能分别对应BGM、音效、语音的播放。
和标准的图形命令相似，要调用的文件名由storage属性指定，淡入淡出、交换音乐的时间由time属性指定。当time不指定的时候将立即开始播放。
例 3.7. 背景音乐指令的例子
@bgm storage=bgm01 time=1000
这条命令将播放bgm01，淡入时间1000毫秒（1秒）。
对于bgm，如果设置了wait属性，则系统将在继续执行底下的部分之前等待音乐淡入淡出的完成。而对于se，如果设置了wait属性，则系统将等待音效播放完成。
例 3.8. 音效使用wait属性的例子
@se wait storage=se001
这条指令将播放se001，并等待其播放完成后才继续执行。
vo指令执行的时候，将会在历史履历中留下回放语音的链接。
从vo语句执行的地方开始，到 页尾（p命令处） 或 用户手工用vend命令中止
的位置，其中所有的文字在历史记录中都会被加上回放语音的链接。点击对应的语音，则对应的语音将被回放。
例 3.9. 使用语音播放及语音回放的例子
@vo storage=a001
【路人甲】「大家好，我是华丽的路人甲！[r]
　　　　　　当玩家打开历史纪录时，只要点击这句话，[r]
　　　　　　这句语音就会被回放的」[p]

4.1. 条件判断与变量的使用
4.1.1. TJS语言简介
TJS语言，是吉里吉里使用的编程语言。该语言具有类似C语言的语法，与JavaScript和Java语言有一定相似性。TJS语言具有结构清晰，易学易用的特点。
运行在吉里吉里上的KAG系统自身使用了TJS编写而成。因而，KAG系统允许在脚本中使用TJS程序代码。利用TJS，用户可以轻易写出逻辑复杂的程序结构，自幼控制引擎的工作，甚至写出特殊的应用功能和小游戏。
由于TJS语言自身已经具有良好的数据类型支持，以及完备的逻辑结构，KAG系统直接使用了TJS的部分功能来处理剧本中的变量操作和条件判断。因而，我们将简单介绍以下基本的TJS知识。

有C/C++、PHP、Java或者Javascript等编程语言的使用经验的可以跳过这一章节。
4.1.1.1. TJS的表达式
TJS表达式由数据与运算符构成，其中数据可以是一个常数，也可以是变量、函数调用或者其他的TJS表达式。
24+32 就是一个简单而且合法的TJS表达式。
4.1.1.2. TJS常用运算符
TJS常用的运算符见下表
表 4.1. TJS常用运算符一览表
运算符类型
运算符
说明
四则运算
+ - * / \
%
分别为加、减、乘、除（实数商）、除（整数商）、取余数
赋值
=
把等号右边的值赋予左边的变量。如 f.a=1 。
条件判断
== >= <=
> < !=
按照表达式判断运算符左右是否满足条件。满足则该式值为非0（真），否则该式值为0（假）
括号
( )
如同数学式一般，括号中的表达式将被作为一个整体。此外，调用函数时括号也被用来包裹参数。
逻辑判断
&& || !
分别表示逻辑的与、或、非的关系。
与(&&)，即&&左右两边都为真时，该式为真。
或(||)，即||左右两边有一个以上为真，则该式为真。
非（!），即右式不为真时，该式为真。
例：(5>3)&&(8>2)为真（非0）
4.1.2. KAG中的变量操作
4.1.2.1. 变量
KAG中总共有三类的变量可以使用。
以 f. 开头的变量，为游戏变量。该类变量将随着进度存档被保存。这类变量用于和游戏进度相关的数据。
以 sf.
开头的是系统变量。该类变量将在系统存档中被自动保存，在正常且没有改动的情况下将一直保持。这类变量用于与系统设置及游戏全局变量相关的数据。
以 tf. 开头的是全局变量。该类变量不会被保存，一旦程序退出就将丢失，用于临时使用的数据。
一般情况下，不要随便在KAG剧本中使用不以这三种类型开头的变量。此外，建议变量名用半角英文开头，但如果有需要，也可以使用中文。
以上这三类变量将在第一次使用时被自动声明。不需要单独的声明或者定义。
4.1.2.2. eval命令
KAG中的eval命令，可以执行特定的TJS表达式。
使用时，请将表达式作为eval指令的exp属性传递。
例如：[eval exp="tf.t1=1+2"]，这一句将执行TJS式 tf.t1=1+2
。也就是将1+2的值赋予临时变量tf.t1
4.1.2.3. cond属性
除了极少数例外之外，大部分KAGeXpress指令都存在一个cond，也就是条件属性。
cond属性值为一个TJS表达式。执行一个带有cond属性的命令之前，系统会先评估cond属性的表达式。如果该式值为真，则该指令才会被执行。
例 4.1. cond标签的例子
@eval exp="tf.t1 = 3"
@bg storage="bg01" cond="tf.t1 == 4" time=1000
@cl all cond="tf.t1 != 3"
则背景将被切换为bg01，且不会被cl命令清除（因为cl命令没有执行）。
4.1.2.4. if指令的例子
if与endif只见可以包围大段KAG剧本，如if的exp属性中TJS式为真，则if与endif之间的代码才会被执行。
例 4.2. if..endif的使用例子
@eval exp="tf.t1 = 3"
@if exp="tf.t1 == 3" ;这边到endif的指令将被执行
因为tf.t1值为3，所以这里被执行了。[l][r]
@endif
@if exp="tf.t1 > 12"
因为tf.t1不大于12，这里会被忽略。[l][r]
@endif
4.1.2.5. emb指令
emb指令将把exp属性中的TJS式求值，把求出的值作为剧本文本显示出来。
例 4.3. emb指令的例子
@eval exp="tf.t1 = 120"
tf.t1的值为[emb exp="tf.t1"]而tf.t1加上20的值为[emb exp="tf.t1+20"]。[l][r]
4.1.2.6. &符号
在KAG指令的属性中传递&符号，则&符号后的内容将被作为TJS式求值，然后把返回的值作为指令的参数。
例 4.4. &符号的例子
@eval exp="tf.t1 = 1200"
@bg storage="bg01" time=&tf.t1
上面的例子将以tf.t1中的1200作为bg指令的time属性。也就是将执行一个1200秒渐变将背景换为bg01。