2026 Ren'Py完全手册：新手快速上手场景切换+标签+转场效果

一、对话语法详解#

1.1 基本对话格式#

Ren’Py的对话系统采用简洁的say语句，支持三种基本格式：

旁白格式（无角色名）：

1
"这是一句旁白，用于叙述故事或表达角色内心想法。"

角色对话格式（角色名+对话内容）：

1
"艾琳" "你好，我是艾琳！"

角色对象格式（使用预定义角色）：

1
e "Hello, world!"

1.2 角色定义方法#

Character对象用于控制对话的外观和行为：

1
define e = Character("艾琳", who_color="#c8ffc8", what_color="#ffffff")
2

3
# 更复杂的角色定义
4
define narrator = Character(None, what_italic=True, what_size=20)

常用角色参数：

who_color：角色名称颜色
what_color：对话文本颜色
what_prefix/what_suffix：对话文本前缀/后缀
who_prefix/who_suffix：角色名前缀/后缀
image：关联的图片标签

1.3 对话样式设置#

文本标签用于局部样式控制：

1
e "这是{b}粗体文本{/b}，这是{i}斜体文本{/i}。"
2
e "这是{color=#ff0000}红色{/color}和{size=30}大字体{/size}。"
3
e "这是{w=1.0}暂停1秒{/w}的文本。"

特殊对话效果：

1
# 打字机效果
2
e "这段文字会逐字显示。"
3

4
# 暂停效果
5
e "我想想...{p}好的！"
6

7
# 表情符号和图片插入
8
e "表情符号：{image=smile.png}"

注意事项：

左花括号 { 和左方括号 [ 在对话中具有特殊含义，使用时需要重复
引号需要使用反斜杠转义
文本标签必须成对闭合，避免嵌套错误

二、选项与分支控制#

2.1 菜单选项创建#

基础菜单格式：

1
menu:
2
    "我应该怎么做？"
3

4
    "喝咖啡":
5
        "我喝了咖啡，味道很好。"
6

7
    "喝茶":
8
        $ drank_tea = True
9
        "我喝了茶，尽量不发表政治声明。"
10

11
    "离开":
12
        jump leave_scene

2.2 条件选项显示#

使用if子句控制选项的显示条件：

1
menu:
2
    "我想去哪里？"
3

4
    "去公园" if park_available:
5
        jump park_scene
6

7
    "去咖啡馆" if cafe_open:
8
        jump cafe_scene
9

10
    "去秘密基地" if secret_unlocked:
11
        jump secret_base

2.3 分支路径设计#

完整分支示例：

1
label choices:
2
    menu:
3
        "选择你的道路":
4
            "魔法之路":
5
                $ path = "magic"
6
                jump magic_training
7
            "战士之路":
8
                $ path = "warrior"
9
                jump warrior_training
10
            "学者之路":
11
                $ path = "scholar"
12
                jump scholar_training
13

14
label magic_training:
15
    "你选择了魔法之路..."
16
    if path == "magic":
17
        "魔法课程开始！"
18
    jump story_continues
19

20
# 分支合并点
21
label story_continues:
22
    "无论选择哪条路，你都开始了你的冒险。"

2.4 条件判断语句#

if/elif/else结构：

1
if points >= 100:
2
    "太棒了！你获得了最高评价！"
3
elif points >= 60:
4
    "不错！你及格了。"
5
else:
6
    "还需要继续努力。"

复杂条件判断：

1
if love > 50 and trust > 30:
2
    jump good_ending
3
elif love > 30 or trust > 50:
4
    jump normal_ending
5
else:
6
    jump bad_ending

注意事项：

菜单选项至少需要有一个，否则会报错
所有菜单选项的条件都不满足时，会跳过整个菜单
使用jump跳转后，执行完目标标签不会自动返回
call语句可以跳转到其他标签并在执行完后返回

三、变量与数据存储#

3.1 变量定义与赋值#

define语句（定义常量）：

1
define e = Character("艾琳")
2
define game_version = "1.0.0"

default语句（定义默认变量）：

1
default love = 0
2
default money = 100
3
default inventory = []

单行Python语句：

1
$ love += 10
2
$ name = "玩家"
3
$ items.append("剑")

3.2 常用数据类型#

字符串操作：

1
$ greeting = "你好，"
2
$ name = "艾琳"
3
e "[greeting][name]！"

数值运算：

1
$ score = 0
2
$ score += 5
3
$ double_score = score * 2

布尔值与条件：

1
$ is_hero = True
2
$ has_item = False
3

4
if is_hero and not has_item:
5
    "你是英雄，但还没有装备。"

列表和字典：

1
$ items = ["剑", "盾", "药水"]
2
$ character_stats = {
3
    "hp": 100,
4
    "mp": 50,
5
    "attack": 20
6
}

3.3 变量作用域管理#

命名存储区：

1
# 在指定存储区定义变量
2
default sylvie.love = 0
3
default alice.love = 0
4

5
# 访问存储区变量
6
e "艾琳的好感度为[sylvie.love]"
7
e "爱丽丝的好感度为[alice.love]"

存储区访问：

1
python:
2
    from store import sylvie, alice
3
    sylvie.love += 1
4
    alice.love += 2

3.4 Persistent数据存储#

跨会话数据保存：

1
# 设置默认值
2
default persistent.gallery_unlocked = False
3
default persistent.endings_seen = []
4

5
# 修改persistent数据
6
label ending_good:
7
    $ persistent.endings_seen.append("good")
8
    $ persistent.gallery_unlocked = True
9
    "恭喜达成好结局！"

MultiPersistent多游戏数据共享：

1
define mp = MultiPersistent("demo.game")
2

3
label start:
4
    if mp.has_played_part1:
5
        e "欢迎回来！你已经完成了第一章。"
6
    else:
7
        e "这是你的第一次冒险！"
8

9
    $ mp.has_played_part1 = True
10
    $ mp.save()

注意事项：

define定义的变量不会随游戏存档保存
default定义的变量会自动包含在游戏存档中
persistent数据在游戏退出时保存，适合存储解锁内容
避免在persistent中存储自定义对象实例

四、场景与标签系统#

4.1 场景切换语法#

基本场景切换：

1
# 设置背景
2
scene bg classroom
3

4
# 带转场效果的场景切换
5
scene bg forest with dissolve
6
scene bg city with fade

常用转场效果：

1
# 淡入淡出
2
scene bg night with fade
3

4
# 溶解效果
5
scene bg castle with dissolve
6

7
# 滑动效果
8
scene bg ocean with dissolve
9

10
# 拉帘效果
11
scene bg interior with curtains

4.2 角色立绘显示与隐藏#

显示角色：

1
# 基本显示
2
show eileen happy at left
3
show sylvie normal at right
4
show alice worried at center
5

6
# 带转场效果
7
show eileen happy with dissolve
8
show sylvie normal at left with move
9

10
# 多角色显示
11
show eileen happy at left
12
show sylvie normal at right
13
show alice worried at center

隐藏角色：

1
# 隐藏特定角色
2
hide eileen
3

4
# 带转场隐藏
5
hide sylvie with dissolve
6

7
# 隐藏所有角色
8
scene black

角色属性修改：

1
# 临时修改（仅对当前对话生效）
2
e @ smile "我感到很开心！"
3

4
# 永久修改
5
e smile "我现在微笑着。"
6

7
# 组合使用
8
e sad@smile "从不开心到开心。"

4.3 标签系统#

基础标签定义：

1
label start:
2
    "游戏从这里开始。"
3
    "欢迎来到视觉小说世界！"
4
    jump chapter1
5

6
label chapter1:
7
    "第一章开始..."
8
    e "你好，我是艾琳。"

局部标签：

1
label chapter1:
2
    "这是第一章。"
3

4
    label .intro:
5
        "这是第一章的介绍部分。"
6
        jump .main_story
7

8
    label .main_story:
9
        "这是第一章的主线剧情。"
10
        jump .intro  # 循环
11

12
label chapter2:
13
    "第二章开始。"
14
    jump chapter1.intro  # 跳转到第一章的局部标签

带参数的标签：

1
label show_stats(level=1, exp=0):
2
    "等级：[level]"
3
    "经验：[exp]"
4
    return
5

6
label start:
7
    call show_stats(5, 1000)
8
    call show_stats(level=3, exp=500)

4.4 剧情流程控制#

jump语句（单向跳转）：

1
label start:
2
    "起点"
3
    jump middle
4

5
label middle:
6
    "中点"
7
    jump end
8

9
label end:
10
    "终点"

call语句（调用后返回）：

1
label start:
2
    "主剧情"
3
    call sub_event
4
    "返回主剧情"
5

6
label sub_event:
7
    "子事件"
8
    # 执行完会返回call语句后的代码

return语句（返回调用点）：

1
label game_start:
2
    menu:
3
        "开始游戏":
4
            jump main_story
5
        "查看帮助":
6
            call help_screen
7
            "返回游戏菜单"
8

9
label help_screen:
10
    "这是帮助信息。"
11
    return  # 返回到menu语句之后

特殊标签：

1
# 游戏启动标签
2
label start:
3
    "游戏从这里开始"
4

5
# 主菜单替换
6
label main_menu:
7
    # 自定义主菜单逻辑
8
    return
9

10
# 游戏退出标签
11
label quit:
12
    "感谢游玩！"
13
    return

注意事项：

场景切换会清除所有显示的图片
show命令会保持之前的显示，需要用hide清除
jump是单向跳转，call会记住返回位置
局部标签只能在所属全局标签内直接引用
标签名要具有描述性，便于代码维护

音乐

一、对话语法详解#

1.1 基本对话格式#

1.2 角色定义方法#

1.3 对话样式设置#

二、选项与分支控制#

2.1 菜单选项创建#

2.2 条件选项显示#

2.3 分支路径设计#

2.4 条件判断语句#

三、变量与数据存储#

3.1 变量定义与赋值#

3.2 常用数据类型#

3.3 变量作用域管理#

3.4 Persistent数据存储#

四、场景与标签系统#

4.1 场景切换语法#

4.2 角色立绘显示与隐藏#

4.3 标签系统#

4.4 剧情流程控制#

文章分享

音乐

文章目录