01 · 场景与 UI 元素

场景是灵泛引擎画面的基本单位。本章详细介绍场景的构成和各种 UI 元素。

scene 语句

scene "scene_name" type=menu
  // 缩进的行都是这个场景的内容
  text "标题" x=50% y=20%
  button "按钮" x=50% y=50%

type 参数

类型	说明	典型用途
menu	菜单场景，有按钮交互	标题画面、结局列表
game	游戏场景，有对话和场景元素	剧情场景
ui	UI 面板	设置、存档界面

type 的实际影响

type 主要影响存档行为——只有 game 类型场景可以存档。menu 和 ui 类型不创建存档点。

场景头部的命令

scene 块内除了 UI 元素，还可以包含命令行（如 set / say / transition / bgm）。这些命令会被提取为场景的入口脚本，在场景显示后自动按序执行：

scene "chapter1"
  set "story.progress" 1                              // 命令
  bgm "Media/bgm_main.wav" volume=0.7                 // 命令
  bg_switch "Images/door_zoom.jpg" transition=fade    // 命令
  text "第一章" x=50% y=10% size=32 color="#FFD700"   // UI 元素
  button "前进" x=50% y=80% nav="next"                // UI 元素

UI 元素总览

元素	语法	用途
text	text "内容" x= y= size= color=	文字
button	button "文字" x= y= width= height= nav=	按钮
image	image "路径" x= y= width= height=	图片
vbox	vbox x= y= spacing=	垂直布局容器
hbox	hbox x= y= spacing=	水平布局容器

text 文字

text "显示内容" x=50% y=20% size=48 color="#FFD700" halign=center font="Microsoft YaHei"

参数	类型	说明
size	数字	字号（默认 16）
color	十六进制	文字颜色（默认白色）
halign	center/left/right	水平对齐
valign	center/top/bottom	垂直对齐
font	字体名?	字体（null 时使用 Avalonia 默认字体，即系统字体或启动层注入的字体）
opacity	0~1	透明度

变量插值

文字内容用 {变量名} 引用变量：

text "金币: {player.gold} / HP: {player.hp}" x=5% y=90% size=14

支持表达式：

text "总价值: {player.gold + player.exp * 10}" x=50% y=20%

button 按钮

button "开始游戏" x=50% y=45% width=240 height=48 color="#88CCFF" nav="chapter1" halign=center

样式参数

参数	类型	说明
color	十六进制	按钮背景色（默认半透明深灰）
fontSize	数字	文字字号（默认 14）
font	字体名?	字体（null 时使用 Avalonia 默认字体）

交互参数

参数	说明
nav="目标"	点击后跳转到场景或标签
cmd="命令"	点击后触发 C# 命令（如 open_settings）
hover="颜色"	鼠标悬停时的文字颜色
selected=true	初始选中状态
disabled=true	禁用按钮

nav vs cmd

• nav——DSL 内部跳转，目标是一个场景名或标签名
• cmd——触发 C# 层的 Overlay 命令，用于打开设置、存档等 UI 面板

image 图片

image "Images/bg_title.png" x=0 y=0 width=100% height=100% opacity=0.5

图片路径相对于 Media/ 目录。width 和 height 支持百分比和像素值。

vbox / hbox 布局容器

当有多个元素需要整齐排列时，用容器省去逐个设坐标：

scene "menu" type=menu
  vbox x=50% y=40% spacing=12 halign=center
    button "新游戏" width=200 height=44 color="#88CCFF"
    button "继续" width=200 height=44 color="#88FF88"
    button "设置" width=200 height=44 color="#AA88FF"
    button "退出" width=200 height=44 color="#FF8888"

• vbox——垂直排列（从上到下）
• hbox——水平排列（从左到右）
• spacing——元素间距（像素）

容器内的元素不需要写 x / y，由容器自动布局。

条件渲染

场景内的 UI 元素支持 if 条件渲染：

scene "tavern"
  text "酒馆" x=50% y=10% size=32
  if {story.met_innkeeper}
    text "老张向你点头示意。" x=50% y=20% size=16
  else
    text "柜台后站着一个陌生人。" x=50% y=20% size=16
  button "离开" x=50% y=80% nav="town"

条件渲染的缩进

if / else / end 必须与 UI 元素同级缩进。条件为真时显示其下缩进的元素。

注释

用 // 写行注释：

// 这是注释
scene "title"  // 行尾注释也可以
  text "标题" x=50% y=50%  // 居中标题

动手练习

创建一个包含多种元素的菜单场景：

scene "practice" type=menu
  image "Images/door_zoom.jpg" x=0 y=0 width=100% height=100% opacity=0.3
  text "练习场景" x=50% y=15% size=40 color="#FFD700" halign=center

  vbox x=50% y=40% spacing=16 halign=center
    button "选项一" width=220 height=44 color="#88CCFF"
    button "选项二" width=220 height=44 color="#88FF88"
    button "选项三" width=220 height=44 color="#FFAA88"

  text "变量测试: {player.gold}" x=50% y=85% size=14 color="#666666" halign=center

下一步

画面构成掌握了！下一章学习对话系统——让角色开口说话。