主题设置

游戏的行为由其配置决定，外观由其主题决定。两者都是普通数据，在每种使用方式下的设置方法都相同：

使用方式	配置	主题
脚本	define config.text_speed = 60	define theme.text_size = 40
C#	game.SetConfig("text_speed", "60")	game.SetTheme("text_size", "40")
Divooka，过程式	Set Config	Set Theme
Divooka，函数式	With Config	With Theme

在 C# 和节点中，值的写法与脚本中相同：数字、true 或 false、方括号中的列表（[40, 40, 40, 40]），或文本。通过代码进行的设置（SetConfig、SetTheme、SetResolution 和 SetTitle，或 Set Config、Set Theme、With Config 和 With Theme 节点）优先于脚本中同一键的 define config. 或 define theme.，无论哪个先出现；因此程序可以先加载游戏的脚本，再更改其中某项设置。传给构造函数的标题和分辨率只是默认值，会被脚本的 define 替换。对于 Novella 不认识的任何键，lint 都会发出警告。

主题中的所有内容都是可选的。没有图像时，引擎会以主题颜色的面板绘制对话窗口、名字标签、选项和对话框，这就是游戏在拥有美术素材之前的样子。

配置

键	默认值	含义
title	Novella Game	游戏名称：窗口标题和主菜单标题。
version	1.0	版本号，显示在主菜单和 About 中，并存储在存档里。
developer		游戏的制作者，显示在 About 中。
about		About 界面的文本。
id		存档文件夹使用的简短标识符；为空时使用去掉空格和标点后的标题。
icon		用作窗口图标的图像文件。
width、height	1280、720	所有内容布局所用的分辨率；窗口会对其进行缩放。
start_label	start	Start 运行的标签。
splash_label	splashscreen	若存在，则在启动时、主菜单之前运行一次的标签。
main_menu_label	main_menu	若存在，则代替内置主菜单运行的标签；它返回时开始新游戏。
after_load_label	after_load	若存在，则在加载存档后调用的标签。
fall_through	true	到达一个标签的末尾时，是否继续进入同一文件中的下一个标签，而不是结束游戏。
rollback_limit	100	玩家可以回滚的步数。
history_limit	250	历史记录保留的条目数。
allow_rollback	true	玩家是否可以回滚。
rollback_past_choices	true	回滚是否可以撤消菜单选择，让玩家重新选择。
text_speed	40	默认打字速度，单位为每秒字符数；0 表示立即显示文本。
auto_forward_delay	2.0	一行显示完毕后，自动前进之前的默认等待时间，单位为秒（每个字符再额外加一点）。
skip_unseen	false	跳过偏好设置 Unseen Text 的默认值。
skip_after_choices	false	跳过偏好设置 After Choices 的默认值。
fullscreen	false	全新安装时是否以全屏启动。
window	auto	对话窗口的默认可见性：auto（显示对话时显示，否则隐藏）、show 或 hide。
auto_voice		语音文件模式，例如 voice/{id}.ogg；若存在以台词 id（或 {character}，即说话者的语音标签）命名的文件，则该行台词会播放它。
main_menu_music		主菜单上播放的音乐。
start_transition	fade	从主菜单进入游戏时的转场。
after_load_transition	dissolve	加载存档后的转场。
end_game_transition	fade	游戏结束、返回主菜单时的转场。
original_language	English	脚本自身语言的名称，即语言偏好设置中列出的名称。
default_language		全新安装时使用的语言；为空表示原始语言。
autosave	true	游戏是否在菜单处和退出时保存到自动存档位。
autosave_slots	6	轮换使用的自动存档位数量。
save_pages	6	存档位的页数。
slots_per_page	6	每页的存档位数量。
show_quick_menu	true	是否在对话窗口下方显示快捷菜单（Back、History、Skip、Auto、Save、Q.Save、Q.Load、Prefs）。其简短标签会通过带有对应按键的工具提示加以说明，例如 Quick save (F5)；没有可回滚的内容时，Back 会变暗。
confirm_quit	true	退出前是否先询问。
show_title_on_main_menu	true	主菜单是否绘制标题；当背景美术已包含标题时，请将其关闭。
developer_mode	false	开发者工具：Shift+O 打开控制台，Shift+R 重新加载脚本。

text_speed、auto_forward_delay、skip_unseen、skip_after_choices、fullscreen 和 default_language 是玩家偏好设置的默认值；一旦玩家更改了某项偏好设置，其选择会保存在持久数据中并优先生效。

主题

像素尺寸以 1080 像素高的游戏为基准书写，并按游戏的高度（或在设置了 scale 时按其值）缩放，因此一个主题适用于所有分辨率。颜色写作 #rgb、#rrggbb 或 #rrggbbaa。内缩边距、外边距和内边距可以是四个数字（左、上、右、下）、两个数字（水平、垂直），或一个数字表示四边相同。

缩放与字体

键	默认值	含义
scale	0	所有像素尺寸的乘数；0 表示按游戏高度相对于 1080 的比例缩放。
font_files	[]	资源中的字体文件，在游戏开始前注册，以便下列字体族设置可以引用它们。
text_font		对话使用的字体族；为空时使用默认字体栈。
name_font		说话者名字使用的字体族；为空时使用 interface_font。
interface_font		菜单和按钮使用的字体族。
title_font		主菜单标题和界面标题使用的字体族；为空时使用 interface_font。
text_size	34	对话文本字号。
name_size	36	说话者名字字号。
interface_size	30	菜单和按钮文本字号。
small_size	22	小号文本：快捷菜单、存档位详情、备注。
heading_size	48	界面标题（Save、Load、Preferences）。
title_size	96	主菜单标题。
line_spacing	1.25	对话行高，以字号的倍数表示。
ruby_scale	0.5	注音文本（ruby）相对于其基础文本的大小。

颜色

键	默认值	含义
text_color	#f7f2e8	对话。
name_color	#f2c879	说话者名字，用于没有自身颜色的角色。
accent_color	#d9a441	选中项、滑块填充、边框。
interface_text_color	#ebe4d6	菜单文本。
idle_color	#d8cfbf	静止状态的按钮文本。
hover_color	#ffd98a	指针下的按钮文本。
selected_color	#ffffff	选中状态的按钮文本。
insensitive_color	#7d7568	禁用的按钮文本。
muted_color	#a59c8c	次要文本。
background_color	#16121a	没有背景图像的菜单的底色。
frame_color	#120e14e8	面板：存档位、偏好设置分组、对话框。
frame_border_color	#d9a44166	面板边框。
text_outline_width	0	对话文本周围的描边，单位为像素，作为光晕绘制在字母后面，因此不会让字母变细。
text_outline_color	#000000	对话描边的颜色。
text_shadow	true	对话是否投下柔和的阴影，使其在任何背景上都清晰可读。
text_shadow_color	#000000b0	阴影的颜色。

对话窗口

键	默认值	含义
textbox_image		对话窗口的图像，按九宫格方式拉伸；为空时绘制面板。
textbox_borders	[40, 40, 40, 40]	图像的九宫格内缩边距，以图像像素计。
textbox_color	#0f0b12d0	绘制的面板的填充色。
textbox_border_color	#d9a44188	绘制的面板的边框。
textbox_corner_radius	14	绘制的面板的圆角半径。
textbox_height	270	窗口的高度。
textbox_margin	[60, 0, 60, 30]	窗口与屏幕边缘之间的空间。
textbox_padding	[70, 62, 70, 30]	窗口边缘与其文本之间的空间。
namebox_image		说话者名字后面的图像（九宫格）；为空时绘制标签。
namebox_borders	[20, 10, 20, 10]	名字图像的九宫格内缩边距。
namebox_color	#2a1a1ce8	绘制的名字标签的填充色。
namebox_offset	[50, -26]	名字相对于窗口左上角的位置。
namebox_padding	[26, 8, 26, 8]	名字在其标签内的周围空间。
side_image_width	300	窗口内为侧边图像保留的宽度。
ctc_image		点击继续指示器；为空时绘制一个小箭头。在游戏等待点击时，两者都会轻轻浮动。

选项

键	默认值	含义
choice_image		每个菜单选项后面的图像（九宫格）；为空时绘制面板。
choice_hover_image		指针下的选项图像。
choice_borders	[30, 12, 30, 12]	选项图像的九宫格内缩边距。
choice_width	1100	选项按钮宽度。
choice_height	76	选项按钮高度。
choice_spacing	20	选项之间的空间。
choice_color	#140f14e0	绘制的选项填充色。
choice_hover_color	#4a2a1ef0	指针下绘制的选项填充色。
choice_center_y	0.42	选项列表的垂直中心，以屏幕的比例表示。

菜单

键	默认值	含义
button_image		菜单按钮后面的图像（九宫格）；为空时绘制纯文本按钮。
button_hover_image		指针下的菜单按钮图像。
button_borders	[20, 10, 20, 10]	按钮图像的九宫格内缩边距。
main_menu_background		主菜单的图像名称或文件；为空时绘制渐变。
game_menu_background		Save、Load、Preferences 等界面后面的图像名称或文件；为空时将游戏画面调暗。
main_menu_xalign	0.08	主菜单按钮的水平位置。
main_menu_yalign	0.86	主菜单按钮的垂直位置（其底部）。
main_menu_panel	true	主菜单按钮后面是否有半透明面板。
logo_image		在主菜单按钮上方绘制、代替标题文本的图像。
frame_image		确认框等对话框后面的图像，使用 textbox 的内缩边距按九宫格方式拉伸；为空时绘制面板。
hover_sound		指针进入按钮时播放的声音。
click_sound		按下按钮时播放的声音。
notify_color	#120e14ee	通知的填充色。
nvl_background	#000000b8	NVL 页面的背景幕。
nvl_text_size	32	NVL 文本字号。
menu_transition_time	0.25	菜单淡入所需的时间。

主题设置与样式

Novella 自己绘制的每个界面都使用命名的样式绘制，而这些样式由主题构建。因此，主题设置是一个或多个内置样式中某个属性的简写：

主题设置	对应
text_font、text_size、text_color、line_spacing、text_outline_width、text_outline_color、text_shadow、text_shadow_color	say_dialogue 的 font、size、color、line_spacing、描边和阴影；NVL 页面、居中文本和历史记录会继承它们。
name_font、name_size、name_color	say_label 的 font、size 和 color。
interface_font、interface_size、interface_text_color、accent_color	default，即所有样式继承的根。
idle_color、hover_color、selected_color、insensitive_color、muted_color	button_text 的 color 及其 hover_、selected_、insensitive_ 和 visited_ 变体。
textbox_image 或 textbox_color、textbox_borders、textbox_border_color、textbox_corner_radius、textbox_padding、textbox_margin、textbox_height	say_window 的 background、borders、border_color、corner_radius、padding、margin 和 ysize。
namebox_image 或 namebox_color、namebox_borders、namebox_padding、namebox_offset	namebox 的 background、borders、padding、xoffset 和 yoffset。
choice_image、choice_hover_image、choice_color、choice_hover_color、choice_borders、choice_width、choice_height、choice_spacing	choice_button 的 background、hover_background、borders、xsize、ysize 和 spacing。
button_image、button_hover_image、button_borders	menu_button 的 background、hover_background 和 borders；button_image 和 button_borders 还为游戏自有界面上的 button 提供图片。
frame_image 或 frame_color、frame_border_color	frame 及各种面板：save_slot、tooltip、confirm_frame、game_menu_navigation 等。
hover_sound、click_sound	每个按钮样式的 hover_sound 和 activate_sound。
title_font、title_size、heading_size	main_menu_title 和 game_menu_title。
side_image_width、ctc_image、nvl_background、nvl_text_size、notify_color、background_color	side_image、ctc、nvl_window、nvl_dialogue、notify_frame 和 game_menu。

故事中同名的 style 会叠加在主题构建的样式之上，因此它是细化而非替换：define theme.text_color = "#fff4d0" 与设置了 color "#fff4d0" 的 style say_dialogue: 块表达的是同一件事；只设置了 background 的 style say_window: 会保留主题中窗口的高度、外边距和内边距。未设置任何样式的游戏，外观与仅由主题决定的完全相同。有些设置背后没有样式，因为它们说明的是内容放在哪里或游戏如何运作，而不是外观：scale、font_files、choice_center_y、main_menu_xalign、main_menu_yalign、main_menu_panel、main_menu_background、game_menu_background、logo_image 和 menu_transition_time。

使用主题设置游戏的整体外观，用样式处理主题键无法表达的内容：某个角色的窗口、名字或文本；选项的悬停边框，或之前选过的选项的颜色；比其他容器圆角更大的容器；界面上某一个按钮的外观；台词中以另一种颜色显示的某个词。Built-in Style Names 节点会列出故事可以重新设定样式的每个样式。

字体

字体设置接受一个字体族列表：以逗号分隔的名称，对每个字符依次尝试，因此可以把拉丁字体放在前面，再由中文或日文字体补上它缺少的字符。引擎的默认字体栈总是跟在该列表之后：拉丁文本使用 Noto Sans、Segoe UI、Helvetica Neue 和 Arial，随后是 Noto Sans CJK、Source Han Sans、Microsoft YaHei、PingFang SC、Yu Gothic UI、Hiragino Sans、Malgun Gothic、SimSun 和 DejaVu Sans，因此只要机器上装有其中任何一种，中文、日文和韩文文本就能开箱即用地正确显示。

要随游戏一起发布字体，请将字体文件放入游戏资源中，在 font_files 中列出它们，并指定其字体族名称：

define theme.font_files = ["fonts/EBGaramond-Regular.ttf", "fonts/EBGaramond-Italic.ttf", "fonts/EBGaramond-SemiBold.ttf", "fonts/LXGWWenKaiLite-Regular.ttf", "fonts/MaShanZheng-Regular.ttf"]
define theme.text_font = "EB Garamond, LXGW WenKai Lite"
define theme.name_font = "EB Garamond, LXGW WenKai Lite"
define theme.interface_font = "EB Garamond, LXGW WenKai Lite"
define theme.title_font = "Ma Shan Zheng, LXGW WenKai Lite"

可识别 .ttf、.otf 和 .ttc 文件。请同时注册一个字体族的斜体和粗体文件，这样 {i} 和 {b} 才会使用真正的字形。角色可以有自己的字体（character q "Qinglan" font "Ma Shan Zheng"），一段文本也可以用 {font=Family} 切换字体。CJK 字符上方的注音文本（ruby）大小由 ruby_scale 决定。请使用开放许可的字体（SIL Open Font License 或 Apache），并随游戏附上每种字体的许可证。

九宫格图像

对话窗口、名字标签、选项、菜单按钮和对话框都可以使用按九宫格方式拉伸的图像：图像由四个内缩边距切成 3×3 的网格，四个角按原始大小绘制，边沿其长度方向拉伸，中心向两个方向拉伸。因此，一张带装饰边角的小图像可以填满任意尺寸，而不会使边角变形。

define theme.textbox_image = "gui/textbox.png"
define theme.textbox_borders = [48, 48, 48, 48]
define theme.textbox_height = 280
define theme.textbox_padding = [80, 66, 80, 34]
define theme.choice_image = "gui/choice_idle.png"
define theme.choice_hover_image = "gui/choice_hover.png"
define theme.choice_borders = [28, 28, 28, 28]

内缩边距以图像自身的像素度量，不会缩放；它们说明四个角在哪里结束。外边距、内边距和尺寸以游戏像素计，并随游戏缩放。准备图像时，请将所有不能拉伸的内容（装饰、圆角）放在角区域内，并让边和中心区域足够简单，以便拉伸。边是拉伸的，而不是平铺的。

图像	内缩边距
textbox_image	textbox_borders
namebox_image	namebox_borders
choice_image、choice_hover_image	choice_borders
button_image、button_hover_image	button_borders
frame_image	textbox_borders

偏好设置

Preferences 界面为玩家提供以下选项：Display（Window 或 Fullscreen）、Skip（Unseen Text、After Choices、Transitions）、Language（当故事有翻译时）、Text Speed、Auto-Forward Time、Text Size、Music Volume、Sound Volume、Voice Volume、Window Opacity 和 Mute All。偏好设置保存在持久数据中，从不保存在存档里。

界面翻译

引擎自身的文字（主菜单、游戏菜单、偏好设置、存档位、确认框、通知、帮助界面）除英语外还内置了三种语言：

语言	选择该语言的代码	覆盖范围
简体中文	zh、zh-Hans、zh-CN 以及下文未列出的任何其他 zh- 代码、schinese、chinese、simplified chinese	所有界面文字、消息和帮助行。
繁体中文	zh-Hant、zh-TW、zh-HK、tchinese、traditional chinese	菜单、偏好设置、快捷菜单及其工具提示、确认框和常见通知。
日语	ja、ja-JP 和其他 ja 代码、japanese	菜单、偏好设置、快捷菜单及其工具提示，以及最常见的消息。

代码匹配时不区分大小写，_ 与 - 视为相同。没有翻译的文字以英文显示。当玩家的语言是上述语言之一时，内置文字即会生效；语言选择器会列出故事已翻译的语言，因此游戏只需将自身文本翻译成该语言（或设置 config.default_language），即可获得这些内置文字。

故事自身的字符串翻译优先，因此游戏可以替换任何语言中的任何引擎文字，包括 Novella 没有对应翻译表的语言：

translate zh-Hans strings:
    old "Start"
    new "开篇"
    old "Quit"
    new "归去"

translate ko strings:
    old "Start"
    new "시작"

对于它认识的代码，语言选择器以语言自身的名称显示该语言（简体中文、繁體中文、日本語、한국어、English、Français、Deutsch、Español、Русский），否则显示其代码。