【开发教程】NVL Maker常用系统变量

【开发教程】NVL Maker常用系统变量

内容 教程 游戏开发教程
#NVLMAKER #游戏开发教程
作者忧郁的DT君 更新2026-10-29 评论0
ARTICLE AUTHOR 忧郁的DT君 忧郁的DT君
AI搜索 当前暂无可用关联资料 收藏 评论
更新于 2026-10-29 0 评论
EDITORIAL · 2026-07-11

[post id=”1088″ title=””]

NVL Maker 是一款基于吉里吉里/KAG 开发的免费开源视觉小说制作工具。本文档将系统性地介绍 NVL Maker 的核心系统变量、脚本指令以及各类界面数据的配置方法，帮助你从入门到精通掌握这款工具。

一、系统变量参考（nvlflag）

游戏运行时使用了大量系统变量来记录状态和控制行为。了解这些变量的作用，可以避免在自定义脚本时发生命名冲突。

1.1 系统初始化参数

变量名 类型 默认值 说明
sf.初始化 Boolean false 第一次执行游戏且所有数值初始化完毕后，该值被设为 true
sf.语音初始化 Boolean 0 音量相关系统数值初始化完毕后，该值被设为 1
sf.cglist Dictionary %[] 登录CG时，将对应CG名的值设为1，可通过 sf.cglist['图片名'] 判断CG是否已登录
sf.历史 Array [] 每个存档对应的最后一句对话，例如存档0对应 sf.历史[0]
sf.最近存储页 Int 1 存档/读取界面自动翻到上次打开的页面

1.2 游戏运行参数

变量名 类型 默认值 说明
kag.allskip Boolean false true=跳过全部，false=只跳过已读
kag.textspeed Int 5 跳字速度，范围0-10，10为最快
kag.autospeed Int 5 自动前进速度，范围0-10，10为最快
kag.bgmvolume Int 50 音乐音量
kag.sevolume Int 100 音效总音量（包括一般音效和语音）
sf.sevolume Int 50 音效音量（因 kag.se[0].volume 不会被保存而额外设置）
sf.voicevolume Int 50 语音音量（因 kag.se[1].volume 不会被保存而额外设置）

1.3 界面配置文件

NVL Maker 的各类界面配置存储在 macro 文件夹下的配置文件中：

变量名 文件 对应界面
f.setting setting.tjs 选项按钮
f.config_title uititle.tjs 标题画面
f.config_dia uidia.tjs 对话界面
f.config_menu uimenu.tjs 主选单
f.config_slpos uislpos.tjs 存储/读取系统排版
f.config_option uioption.tjs 系统设置界面
f.config_history uihistory.tjs 历史记录界面
f.config_name namelist.tjs 主要人物姓名及颜色代码
f.config_save uisave.tjs 存储系统图片
f.config_load uiload.tjs 读取系统图片
f.config_cgmode uicgmode.tjs CG鉴赏界面

命名提示：为自己创建变量时，请避开以上系统已使用的变量名。

二、脚本指令参考（nvltag）

NVL Maker 的脚本指令基于 KAG 语法扩展。以下列出最常用的图形化指令。

2.1 通用参数

切换效果参数（trans 相关）：

参数 值 说明
time 毫秒数 切换时间，不同指令有不同默认值
canskip true/false 效果是否可点击跳过，默认 true
method ①~⑩ 切换效果：①crossfade（淡入）、②universal（遮片）、③turn（翻页）、④wave（波纹）、⑤ripple（水面涟漪）、⑥scroll（卷动）、⑦mosaic（马赛克）、⑧rotateswap（旋转切换）、⑨rotatezoom（旋转缩放）、⑩rotatevanish（旋转消失）
rule 图片名 遮片图，method 为 universal 时使用
from left/right/top/bottom 切换方向，method 为 scroll 时使用
stay nostay/stayback/stayfore 原图是否停留，method 为 scroll 时使用

图层参数（layer 相关）：

参数 值 说明
layer stage/base 背景层
layer all 全部前景图层（0-8）
layer 0-7 立绘层
layer 8 头像层
page fore 表页（默认）
page back 里页

2.2 图像操作指令

（1）显示背景 @bg

参数 是否必须/默认值 说明
time 默认700 显示效果切换时间
storage 必须 背景图片名
clfg false 同时消除所有前景层
hidemes false 同时消除对话框及系统按钮
convert false 图片反色效果
grayscale false 图片去色效果
mcolor — 蒙版色
mopacity — 蒙版色透明度

（2）显示人物 @fg

参数 是否必须/默认值 说明
time 默认500 显示效果切换时间
storage 必须 人物图片名
layer 0 显示人物的图层编号
pos left/center/right 人物显示位置
left — 直接指定横坐标（pos为空时生效）
top — 直接指定纵坐标（pos为空时生效）
opacity — 图片透明度

（3）显示头像 @face

参数 是否必须/默认值 说明
time 默认100 显示效果切换时间
storage 必须 头像图片名
opacity — 图片透明度
fg — 同时显示人物立绘（自动取得指定图层坐标）
layer 0 同时显示立绘所用的图层

（4）消除背景 @clbg

参数 是否必须/默认值 说明
time 默认700 消除效果切换时间
clfg false 同时消除所有前景层
hidemes false 同时消除对话框及系统按钮

（5）消除人物 @clfg

参数 是否必须/默认值 说明
time 默认500 消除效果切换时间
layer 0 可选 0~8 或 all
clface false 是否同时消除头像

三、界面数据说明（nvluidata 1-5）

NVL Maker 的界面通过配置文件进行高度定制。大部分配置文件是字典结构，一个 name 对应一个控件。

3.1 基础设定（nvluidata1）

文件列表

数据文件 对应界面
uititle 标题画面
setting 基础设定
uidia 对话界面（主界面）
uimenu 主选单界面
uioption 系统设置界面
uihistory 对话回顾界面
namelist 人物姓名、简称及颜色列表
uisave 保存游戏界面图素
uiload 读取游戏界面图素
uislpos 保存/读取游戏界面排版

按钮控件通用结构

所有按钮控件都包含以下参数：

name type 说明
use bool 0=隐藏，1=显示
x int 按钮坐标 x
y int 按钮坐标 y
normal string 一般状态图片
over string hover 状态图片
on string click 状态图片
enterse string hover 时播放的音效
clickse string click 时播放的音效

滑动槽控件通用结构

name type 说明
use bool 0=隐藏，1=显示
x int 坐标 x
y int 坐标 y
base string 滑动槽底部图
normal string 滑动按钮一般状态
over string 滑动按钮 over 状态
on string 滑动按钮 click/drag 状态

标题画面（uititle）控件

name type 说明
logo string 小组标志图片
bgd string 标题画面背景图
front string 标题画面前景图（非必要）
bgm string 标题画面背景音乐

标题画面按钮：start（开始游戏）、load（读取进度）、exit（离开游戏）、option（系统设定）、extra（自定义脚本）、omake（CG一览）

粒子效果：rain（下雨）、snow（下雪）、sakura（樱花）、momiji（红叶）、movie（旧电影）、firefly（萤火虫）

基础设定（setting）

name type 说明
selbutton dict 选项按钮的默认外观和音效
selfont dict 选项按钮的默认字体颜色和字号

3.2 保存与读取界面（nvluidata2）

保存和读取界面共用同一套排版（uislpos），但使用不同的图片和颜色配置（uisave / uiload）。

uisave / uiload 控件

name type 说明
bgd string 背景图片
lastsavemark string 最近保存档案旁的标记图片
button 按钮* 存档栏位按钮
back 按钮* 返回按钮
up 按钮* 向前翻页
down 按钮* 向后翻页

存取界面的按钮没有 x/y 坐标参数，坐标由 uislpos 控制。

颜色组

name type 说明
num 颜色组 存档按钮编号的颜色
date 颜色组 存档日期颜色
bookmark 颜色组 书签名颜色
history 颜色组 最近一句对话记录颜色
draw 特殊颜色组 hover 时显示的额外信息颜色

颜色组结构：normal（一般状态）、over（hover状态）、on（click状态）

draw 颜色组：talk（对话记录）、bookmark（书签名）、date（日期）

uislpos 排版配置

name type 说明
pagefont 文字设置组 全页面文字设定（粗体、斜体、阴影、描边等）
snapshot 特殊设置组 hover 时显示的截图设置
drawmark 特殊设置组 hover 时显示的书签名
drawdate 特殊设置组 hover 时显示的日期
drawtalk 特殊设置组 hover 时显示的最近对话

3.3 CG一览模式（nvluidata3）

CG 一览界面包含以下控件：

name type 说明
bgd string CG界面背景图
up 按钮 向前翻页
down 按钮 向后翻页
back 按钮 返回上层
locate array CG栏位位置
thum dictionary CG缩略图按钮效果

locate 定位：locate[0][0] 代表第一个CG栏的 x 坐标，locate[0][1] 代表 y 坐标，以此类推。

thum 缩略图：实际只读取 thum.normal 的值，用于决定缩略图大小和hover/click时的叠加效果。

CG列表配置（cglist.txt）

text
CG1_1,CG1_2,CG1_3
CG2
CG3_1,CG3_2
CG4
CG5
....

每行代表一个CG栏位，同一行的多个文件名用逗号隔开表示差分。

CG收集机制

一张CG要出现在CG一览中，必须满足：

  1. 该CG在 cglist.txt 中，且是某行的第一张图

  2. 在剧情脚本中使用 “登录CG” 功能登录过（将CG名存入 sf.cglist）

例如登录CG “abc”：sf.cglist.abc = true

点击CG小图时，会按顺序显示该行的所有已登录差分，鼠标点击切换下一张。

3.4 地图面板（nvluidata4）

地图数据存储在 .map 文件中，内容为 TJS 数组。整个数组有 16 个元素：array[0] 设定背景板，array[1] 到 array[15] 设定按钮。

array[0] 背景设定

name 类型 说明
bgd string 地图背景图片
normal string 默认按钮一般状态图片
over string 默认按钮 hover 状态图片
on string 默认按钮 click 状态图片

array[1]-array[15] 按钮设定

name 类型 说明
use bool 0=隐藏，1=显示
x int 按钮坐标 x
y int 按钮坐标 y
place string 编辑界面显示的按钮名（注释用）
normal/over/on string 按钮三态图片
enterse/clickse string 音效
storage string 跳转的脚本文件
target string 跳转的脚本标签
exp string 点击后执行的 TJS 式
cond string 按钮出现的条件 TJS 式
onenter string 鼠标移入时执行的 TJS 式
onleave string 鼠标离开时执行的 TJS 式

关于 cond 条件：cond 为空时，只要 use==1 按钮即显示；cond 有值时，需满足条件才显示，如 "(sf.结局A==1)"。

3.5 养成面板（nvluidata5）

养成数据存储在 .edu 文件中，内容为 TJS 数组。整个数组有 31 个元素：

  • array[0]：背景板设定

  • array[1] 到 array[10]：按钮（10个）

  • array[11] 到 array[20]：文字（10个）

  • array[21] 到 array[30]：图片（10个）

array[0] 背景设定

name 类型 说明
bgd string 背景图片
normal/over/on string 默认按钮三态图片
num string 图片数字的默认前缀
space int 图片数字的默认间隔

array[1]-array[10] 按钮

与地图面板按钮结构完全相同（参见 3.4 节）。

array[11]-array[20] 文字

使用 ptext 指令描绘，支持 n 换行。

name 类型 说明
use bool 0=隐藏，1=显示
cond string 显示条件 TJS 式
x/y int 坐标
name string 编辑界面显示的名称（注释用）
flagname string 具体文字或 TJS 式（如 “提示：” 或 “f.姓+f.名”）
fontname string 字体名
size int 文字大小
lineheight int 每行高度（支持多行时使用）
color color 文字颜色
bold/shadow/edge bool 粗体/阴影/描边
shadowcolor/edgecolor color 阴影色/描边色

array[21]-array[30] 图片

name 类型 说明
use bool 0=隐藏，1=显示
cond string 显示条件 TJS 式
x/y int 坐标
name string 编辑界面显示的名称（注释用）
pic string 固定图片名（flagname 为空时使用）
flagname string 变数名或 TJS 式
num string 图片数字前缀
space int 图片数字间隔

四、实用技巧总结

4.1 变量命名规范

创建自定义变量时，务必避开系统变量名（sf.xxx、kag.xxx、f.xxx 等），以免造成冲突。

4.2 CG 小图优化

系统会自动缩放原图作为 CG 小图。如果存在 xxx_thum.png 格式的图片，会优先使用该图，避免缩放失真。

4.3 条件显示

在地图和养成面板中，通过 cond 参数可以实现按钮/文字/图片的条件显示，常用于根据游戏进度解锁不同内容。

4.4 动态文字

养成面板的文字控件支持 TJS 式，可以显示变量内容。例如 flagname: "f.姓+f.名" 会动态显示玩家设定的姓名。

4.5 存档缩略图

在 uislpos 中配置 snapshot 可以实现鼠标悬停时显示存档截图，提升用户体验。

以上即 NVL Maker 核心系统变量、脚本指令与界面数据的完整参考。建议在实际开发中结合官方示例和本文档进行实践，逐步掌握各项功能的使用方法。如有疑问，可访问 THE NVL Maker 官网 获取更多资源。

标签
# NVLMAKER # 游戏开发教程
FOR YOU

为您推荐

DISCUSSION

评论