KAG 标签语法速查与规则
什么是 KAG 标签
KAG（Kirikiri Adventure Game）是吉里吉里2 的剧本脚本系统。scenario 文件（.ks）本质上是纯文本 + 嵌入式标签：
- 普通文字 = 要显示的对话文本
[方括号内容]= KAG 指令标签，控制立绘、背景、选项、特效等
一个最小的 scenario 文件：
; 这是注释（分号开头的行）
; 切换背景
[bg storage="bg/school.tlg" time=500]
; 显示角色立绘
[chara storage="chara/hermione.tlg" layer=1]
; 显示文本（方括号结束后直接写字）
赫敏：欢迎来到吉里吉里2 的世界！
; 等待点击
[click]标签基本格式
[标签名 属性1=值1 属性2=值2]规则：
- 标签名和属性之间必须有半角空格
- 属性名和值之间用等号，等号两边不能有空格
- 多个属性之间用半角空格分隔
- 标签独占一行或嵌在行尾都可以
- 注释以
;开头，单独一行
属性值的引号
属性值有引号和没引号都行，但规则如下：
| 值的类型 | 示例 | 是否需要引号 |
|---|---|---|
| 纯数字 | time=500 | 不需要 |
| 纯字母/下划线 | layer=1 | 不需要 |
| 包含空格/特殊字符 | name="my chara" | 需要双引号 |
| 路径 | storage="bg/school.tlg" | 推荐加引号（路径含空格时必须） |
| 布尔值 | visible=true | 推荐写 true / false |
常用属性速查
几乎所有标签都支持这些通用属性：
| 属性 | 含义 | 示例 |
|---|---|---|
time | 动画时长（毫秒） | time=300 表示 300ms 动画 |
layer | 图层编号 | layer=1 表示第一层 |
visible | 是否可见 | visible=true/false |
name | 元素内部名称 | name="bg_main" |
标签分类
KAG 内置的标签按功能分大约十几个大类：
| 分类 | 常用标签 |
|---|---|
| 流程控制 | jump、call、return、click、wait |
| 文本显示 | msg、nowait、text、backlog |
| 图形 | bg、chara、image、layer、graph |
| 动画 | fade、move、shake、effect |
| 选项 | select、selectcancel、goto |
| 变量 | set、if、while、for |
| 存档 | save、load、savenew |
| 音频 | playbgm、playse、stopbgm、fadebgm |
| 视频 | playvideo、stopvideo |
| 脚本嵌入 | tjs、eval、script |
| KAG 自身 | load、callback、system |
与 TJS2 的交互
scenario 里可以嵌入 TJS2 代码：
; 方式一：[tjs] 标签后接多行
[tjs]
var hp = 100;
hp -= 10;
Layer.current.message = "HP: " + hp;
; 方式二：[eval] 执行单行表达式
HP 现在是 [eval exp="hp"][tjs] 块在 scenario 中作为一个标签存在，执行完再继续。
嵌套规则
- KAG 标签本身不嵌套（
[a][b][/b][/a]这种 XML 风格不行） - 选项块用
[select]+[goto]结构实现伪嵌套 - TJS2 代码块
[tjs]...[/tjs]内部可以嵌套 TJS2 的控制流
编码
scenario 文件推荐 UTF-8（无 BOM） 或 Shift_JIS（日语环境）。中文内容用 UTF-8 即可。
进阶提示
- KAG 本身是用 TJS2 写的，你可以在
base/kag/目录里看到完整源码 - 当某个标签行为不对时，改 KAG 源码比绕弯子写 workaround 更彻底
[system]标签可以查询引擎状态（版本、窗口大小等），适合做兼容性判断