标签与控制流

本页属于 GenPy Ren'Py 学习路线。教程内容面向 Ren'Py 8.x，并在页面末尾连接到 GenPy 的对应工作流。

学习目标

• 了解“标签与控制流”在 Ren'Py 项目中的用途。
• 能在一个最小项目里验证本章相关语法或工作流。
• 知道发布前需要检查的常见风险，并能在 GenPy 中继续维护。

核心语法

• label
• jump
• call
• return
• pause
• after_load

可运行示例

label start:
    "故事从这里开始。"
    jump chapter1

label chapter1:
    "第一章。"
    return

教程正文

控制流决定故事“往哪走”。核心是 label（站点）、jump（单程跳转）、call/return （子程序调用与返回）。

1. label（标签）

label 是脚本中的命名站点，供跳转或调用：

label start:
    "故事从这里开始。"
    jump chapter1

label chapter1:
    "第一章。"
    return

带参数的 label

label 可以像函数一样接收参数（常配合 call 使用）：

label sleep(hours=8):
    "你睡了 [hours] 个小时。"
    return

局部标签

以 .name 定义的是局部标签，作用域归属其上方最近的全局 label：

label chapter1:
    "正文。"
    jump .secret        # 跳到本章的局部标签

label .secret:
    "隐藏剧情。"
    return

8.5 起，局部标签的声明更灵活：可以指明任意全局标签作为其归属 （global.local 形式），便于跨文件组织。

2. jump（跳转，单程）

jump 把控制权转给目标 label，不记录返回点——一去不回头，适合章节推进、分支结局、循环。

label loop_start:
    e "我们好像陷入死循环了。"
    jump loop_start     # 无限循环

jump expression（动态跳转）

目标名在运行时由表达式算出：

$ target = "chapter" + str(n)
jump expression target

3. call / return（子程序，可返回）

call 跳转的同时把“下一句”压入调用栈，子程序里 return 会回到调用点之后。

label start:
    e "先调用一个子程序。"
    call subroutine            # 无参
    call subroutine(2)         # 带参
    call expression "sub" + "routine" pass (count=3)   # 动态名+参数
    return

label subroutine(count=1):
    e "我来过这里 [count] 次。"
    return

要点：

• 动态调用带参数时，表达式与参数列表之间必须加 pass 关键字 （否则参数会被当成表达式的一部分）。
• return expression 可返回值，结果存入 _return 变量。

from 子句（发布安全，重要）

call subroutine from _call_subroutine_1

• from 给调用点一个稳定的内部标签名，保证老存档在脚本更新后仍能正确返回。
• 手写麻烦时，构建发布勾选 “Add from clauses to calls” 自动添加。
• 若计划日后更新游戏，强烈建议补全 from 子句，否则改动被调用文件可能损坏存档。

4. return 的特殊行为

• 调用栈为空时 return 会重启 Ren'Py 回到主菜单（常用于游戏结束）。
• return 也用于结束 label start 流程。

5. pause（暂停）

pause              # 等待玩家点击
pause 3.0          # 等待 3 秒（玩家可点击跳过）
pause 3.0 hard=True  # 硬暂停，期间忽略点击（谨慎用）

6. 特殊 label（生命周期钩子）

Ren'Py 在特定时机自动调用这些 label（若你定义了它们）：

label	触发时机
start	新游戏开始（必有）
splashscreen	启动后、主菜单前的开场
main_menu	自定义主菜单流程（高级）
after_load	每次读档完成后
before_main_menu	进入主菜单前（可显示背景动画）
quit	玩家退出时
after_warp	用 warp 跳入后

label after_load:
    # 读档后重建一些不可回滚的运行期状态
    $ rebuild_runtime_cache()
    return

7. 从 Python 控制流

$ renpy.jump("chapter2")
$ renpy.call("subroutine")            # 较少直接用
$ result = renpy.call_screen("confirm")

常见坑

• jump 不可返回；要返回用 call + return。
• 调用栈会参与存档；改脚本前先想清楚老存档的返回点（用 from 子句兜底）。
• 死路 label（无 jump/return 的末尾）会被 Lint 警告，发布前修掉。
• label 名拼写/大小写要对得上，jump Chapter1 ≠ jump chapter1。

官方参考

• 标签与控制流：https://www.renpy.org/doc/html/label.html

在 GenPy 里怎么做

• 在 GenPy 的代码模式中维护相关 .rpy 文件，先保持语法清晰，再逐步加入本章功能。
• 用故事图谱、变量、校验或演出编辑器把“能运行”提升到“可维护”。
• 导出前结合 Ren'Py Lint 和 GenPy 校验结果，确认脚本、素材和发布路径一致。

推荐继续阅读：

• 故事图谱
• 分支视图
• 脚本校验