屏幕语言
本页属于 GenPy Ren'Py 学习路线。教程内容面向 Ren'Py 8.x，并在页面末尾连接到 GenPy 的对应工作流。
学习目标
- 了解“屏幕语言”在 Ren'Py 项目中的用途。
- 能在一个最小项目里验证本章相关语法或工作流。
- 知道发布前需要检查的常见风险，并能在 GenPy 中继续维护。
核心语法
screentextbuttonvboxhboxactionuse
可运行示例
text
screen hello():
text "你好，世界！" xalign 0.5 yalign 0.1
textbutton "关闭" action Hide("hello") xalign 0.5 yalign 0.9教程正文
屏幕语言（Screen Language）用来声明式地搭建界面：对话框、主菜单、存档界面、HUD、 自定义弹窗、物品栏等。Ren'Py 自带的所有 UI 都是用它写的（见 screens.rpy）。
1. 声明一个 screen
text
screen hello():
text "你好，世界！" xalign 0.5 yalign 0.1
textbutton "关闭" action Hide("hello") xalign 0.5 yalign 0.9显示与隐藏：
text
show screen hello # 持续显示，叠加在画面上
hide screen hello
$ renpy.call_screen("confirm") # 模态显示，等待其返回值show screen 是非模态叠加；call_screen 是模态，常用于需要返回值的对话框。
2. 控件（displayables）速查
| 控件 | 用途 |
|---|---|
text "..." | 文本 |
textbutton "..." action ... | 文字按钮 |
imagebutton | 图片按钮（idle/hover 图） |
button: | 通用按钮（内部可放任意控件） |
image "x.png" / add | 显示图片/可显示物 |
bar / vbar | 进度条/滑块 |
input | 文本输入框 |
viewport | 可滚动视口 |
vbox / hbox | 垂直/水平排列 |
grid / vpgrid | 网格排列 |
fixed | 绝对定位容器 |
frame / window | 带背景的容器 |
side | 九宫格定位容器 |
null | 占位空白 |
imagemap + hotspot/hotbar | 图像热区界面 |
key | 绑定按键 |
timer | 定时器 |
use other_screen | 嵌入另一个 screen |
3. 布局容器
text
screen menu_demo():
frame:
xalign 0.5 yalign 0.5
vbox:
spacing 10
text "主菜单" size 40
textbutton "开始" action Start()
textbutton "读档" action ShowMenu("load")
textbutton "设置" action ShowMenu("preferences")
textbutton "退出" action Quit()vbox/hbox自动排列子元素，spacing控制间距。frame/window提供背景与内边距。fixed用绝对坐标（配合xpos/ypos/xalign等）。
4. 动作（Action）
按钮的 action 指定点击行为。常用：
| 动作 | 作用 |
|---|---|
Return(value) | 关闭 call_screen 并返回值 |
Jump("label") | 跳转到 label |
Call("label") | 调用 label |
Show("screen") / Hide("screen") | 显示/隐藏屏幕 |
ShowMenu("load") | 打开游戏菜单页 |
Start() / Quit() | 开始新游戏 / 退出 |
SetVariable("v", val) | 设变量 |
ToggleVariable("v") | 取反布尔变量 |
SetScreenVariable(...) | 设屏幕局部变量 |
Function(fn, *args) | 调用任意函数 |
NullAction() | 什么都不做（占位） |
动作可组合为列表（依次执行）：action [SetVariable("x", 1), Hide("dlg")]。
5. 屏幕变量与逻辑
text
screen counter():
default n = 0 # 屏幕局部变量
vbox:
text "计数：[n]"
textbutton "+1" action SetScreenVariable("n", n + 1)
if n >= 5: # 屏幕里可用 if / for
text "到 5 了！"
for i in range(3):
text "第 [i] 行"default声明屏幕局部状态（每次显示重置）。- 屏幕里可用
if/for（Python 风格）做条件与循环渲染。 - 屏幕是响应式的：引用的变量变化时自动重绘。
6. 传参给 screen
text
screen confirm(message):
frame:
vbox:
text message
textbutton "确定" action Return(True)
textbutton "取消" action Return(False)
label start:
$ ok = renpy.call_screen("confirm", "真的退出吗？")7. imagebutton 与 imagemap
text
screen title():
imagebutton:
idle "ui/start_idle.png"
hover "ui/start_hover.png"
action Start()
xalign 0.5 yalign 0.6
screen room_map():
imagemap:
ground "map/ground.png"
hover "map/hover.png"
hotspot (100, 200, 120, 80) action Jump("door") # (x,y,w,h)8. viewport（滚动）与 bar（进度/血条）
text
screen log():
viewport:
scrollbars "vertical"
mousewheel True
vbox:
for line in history:
text line
screen hp_bar():
bar value AnimatedValue(hp, 100) xsize 300 yalign 0.059. 覆盖内置界面
screens.rpy 里已有 say、main_menu、navigation、save/load、preferences、 choice、quick_menu 等标准屏幕。直接编辑它们即可定制游戏 UI（小步修改，避免大改一锅端）。
text
# 例：定制对话框屏幕 say（节选自 screens.rpy）
screen say(who, what):
window:
id "window"
if who is not None:
text who id "who"
text what id "what"常见坑
show screen（叠加，非模态）≠call_screen（模态，等返回值）。- 屏幕里引用的可变量请用
default（屏幕变量）或存档变量，才能正确刷新。 - 改内置界面优先在
screens.rpy小范围改，配合gui.*（第 17 章）。 hotspot/frame坐标与尺寸单位是像素，注意与分辨率匹配。- 屏幕里写复杂逻辑会影响性能；重计算放外部函数，屏幕只负责展示。
官方参考
- 屏幕语言：https://www.renpy.org/doc/html/screens.html
- 屏幕动作/值/函数：https://www.renpy.org/doc/html/screen_actions.html
- 特殊屏幕名：https://www.renpy.org/doc/html/screen_special.html
在 GenPy 里怎么做
- 在 GenPy 的代码模式中维护相关 .rpy 文件，先保持语法清晰，再逐步加入本章功能。
- 用故事图谱、变量、校验或演出编辑器把“能运行”提升到“可维护”。
- 导出前结合 Ren'Py Lint 和 GenPy 校验结果，确认脚本、素材和发布路径一致。
推荐继续阅读：