renpy引擎基础语法

前言

基本从官方文档搬过来总结出来的常用基础语句和语法，没有搞完还，回头再把解释翻译成人话，文档里面的话跟机翻的一样，真的离谱，根本没法看

注释

# 这是一条注释。
show black # 这也是一条注释。

"# 这不是一条注释因为它是一个字符串的一部分。"

label语句

label语句允许使用自定义的标签名声明一个程序点位。这些标签仅仅用来被调用或者跳转，可以使用在Ren’Py脚本、python函数及各类界面中。

label sample1:
    "这是一个'sample1'脚本标签。"

label sample2(a="default"):
    "这是一个'sample2'脚本标签。"
    "a = [a]"

一个label语句可能只跟某一个语句块(block)关联。在那种情况下，主控流程遇到label语句就会进入关联语句块(block)，并顺序执行之后的语句。

总共有两种脚本标签(label)：global 和 local 。global标签在所有项目文件中都生效，所以每个游戏中都不能重复定义。 local标签可以同名，但需要与不同的global标签做关联。需要声明一个local标签的话，在标签名前缀一个英文句号“.”即可。例如：

label global_label:
    "这在一个global脚本标签里。"
label .local_label:
    ".这里属于local脚本标签。"
    jump .another_local
label .another_local:
    "另一个local脚本标签"
    jump .local_label

local脚本标签在关联的global标签内部可以直接引用。其他地方则需要使用标签全名，由关联的globle标签和local标签组成。一个关于global标签和local标签的例子如下：

label another_global:
    "现在让我们跳转进入其他地方的local脚本标签。"
    jump global_label.local_name

jump语句

jump语句用于将主控流程转入指定的脚本标签(label)处。

若出现了 expression (表达式)关键词，关键词后面的表达式将被赋值，而被计算后的对应字符串则会被用作跳转目标的标签语句。若未出现 expression (表达式)关键词，跳转目标的标签名字就必须精确指定。

与call语句不同，jump语句不会将下一个语句放入栈(stack)中。因此，执行完跳转标签对应的语句块之后，主控流程不会回到跳转前的脚本位置。

label loop_start:

    e "哦，不！看起来我们陷入了一个无限循环之中。"

    jump loop_start

call语句

call语句用于将主控流程转入给定的脚本标签(label)处。call语句会将下一条语句压入到调用栈(stack)中，并允许主控流程在执行完这次调用后，回到调用发生的脚本位置。

from 分句是可选的，在label语句后面直接添加入参名和值，并直接在该label下直接使用。一个命名直白的标签(lable)有助于我们能利用栈(stack)回到脚本里合适的地方，就算加载的是修改过的脚本。

当我们使用一个带入参列表的调用表达式时，必须在表达式和入参列表之间插入关键词 pass 。否则，入参列表会被当作表达式的一部分，而不是call语句的一部分。

label start:

    e "首先，我们调用一个支线。"

    call subroutine

    call subroutine(2)

    call expression "sub" + "routine" pass (count=3)

    return

label subroutine(count=1):

    e "我来过这里 [count] 次了。"
    e "接着，我们会从支线返回。"

    return

每条 call 语句后面都不加上 from 从句就发布游戏是危险的。当然也可以通过发布更新补丁解决。在没有 from 从句的情况下，编辑 call 相关的脚本，可能会有存档损坏的风险。

构建发行版时，将选项“向call语句添加from从句”勾选上就能解决以上问题。

return语句

return语句会在调用栈中弹出最顶层的那条语句，并将主控流程转到那条语句。若调用栈为空，返回语句将重启Ren’Py，将主控流程切换至主菜单。

若返回语句带有可选项表达式，表达式会被计算求值，并且结果会被存储在_return变量中。_return变量依赖于各种场景动态变化。

特殊脚本标签(label)

以下脚本标签(label)会在Ren’Py中使用：start

默认情况下，Ren’Py在游戏启动后会跳转至这个标签。quit

若该标签存在，当用户退出游戏时该标签内容会被调用。after_load

若该标签存在，当游戏读档后会调用这个标签内容。其可能被用于游戏内容更新后的数据修复。如果数据从此标签后发生变化，应该调用 renpy.block_rollback() 函数防止用户从该存档点回滚。splashscreen

若该标签存在，游戏首次运行时，在主菜单出现前，该标签内容会被调用。详见添加启动画面。before_main_menu

若该标签存在，在主菜单出现前，该标签内容会被调用。在少数情况下，其用来设置主菜单，例如背景播放一段影片。main_menu

label main_menu:
    return

若该标签存在，标签内容会被调用，用来替代默认的主菜单。若其内容中包含return语句，Ren’Py将从start标签处开始游戏。例如，下面这段脚本在不显示主菜单的情况下开始游戏。label main_menu: returnafter_warp

若该标签存在，则调用warp语句时，此标签至传送(warp)点前的语句都将被执行。详见传送至某行hide_windows

若该标签存在，当玩家使用鼠标右键或键盘H键隐藏对话窗口时，将调用此标签。若标签返回值为True，隐藏对话窗口行为将取消(依然当作隐藏已经发生)。否则，继续隐藏对话窗口。

say语句

say语句被用在对话和旁白场景中。由于在Ren’Py脚本中say语句出现如此之频繁，所以在编写say语句的语法是一个最小化后的语法结构。这是一些样例:


    "这是一句旁白。"

    "艾琳" "这是一句对话，用了完整的角色名。"

    e "这是一句对话，使用了角色对象。"

    "嘭!!" with vpunch

say语句的第一种形式是一个其自身组成的整个字符串。这种形式用于陈述，陈述内容就是字符串内容。

say语句的第二种形式是由两个字符串组成。第一个字符串是发言角色的名字，第二个字符串是该角色正在说的内容。

say语句的第三种形式是一个简单表达式后接一个字符串。简单表达式应该等同于一个角色名字或者一个角色(character)对象。在后面的例子中，角色对象被用于控制对话展现。

say语句的最后一种形式是一个字符串及with分句的一个转场(transition)效果。在上面的例子中，字符串会显示为对话内容，屏幕会同步抖动。

尽管say语句所处理对话的具体细节实际是由角色(character)对象所控制，say语句的通常用处是在界面上展现一个对话，直到用户点击鼠标后取消对话，并在界面上移除对话内容。

某些字符对Ren’Py有特殊含义，所以不能用在对话字符串中。左花括号 { 开启一个文本标签(tag)，左方括号 [ 开启一个替换(substitution)。若需要在对话中使用这些字符，需要连续出现两次。而转移双引号则需要使用反斜杠符号，不然字符串会在那个引号处截断。应用举例

"I walked past a sign saying, \"Let's give it 100%!\""

定义角色(character)对象

通过创建一个角色对象并在say语句中使用该角色对象，你可以定制化对话窗口外观(甚至行为)。角色对象通过使用define语句，将角色(character)声明为一个变量。举例:

define e = Character("艾琳", who_color="#c8ffc8")

完成了这步工作后，定义的角色就可以使用在say语句中。例如：

e "Hello, world."

角色(Character)是一个python函数，该函数包含一大串的关键词参数。这些关键词参数控制着角色行为。

define语句会计算其自身的表达式，并声明为一个给定的变量名。若 define 语句不在 init 语句块(block)中，其会自动以与初始化相同的最高优先级(0)运行。

Character(name, kind=adv, **args)link

创建并返回了一个角色对象，其控制了对话和旁白的观感。name

如果该参数是一个字符串，则成为对话中角色的名字。如果 name 参数是 None ，名字不会显示，用于旁白。kind

新建角色的基底角色。当使用该参数时，新建角色没有显示赋值的参数，均使用对应基底角色的属性作为默认值。这个设计常用来定义模板(template)角色，然后继承模板角色属性并修改。

链接图片 与某个角色关联的图像标签(tag)名。这种设计，允许一个包含角色的say语句使用标签(tag)名来展现角色图片，也同时允许角色说话时Ren’Py自动选择并展现一个头像。image

与角色关联的图像标签(tag)名的字符串。

语音标签(tag) 若某个声音标签(tag)被指定为某个角色所有，标签下对应的声音文件将会与该角色关联，这些声音文件可以在自定义设置界面被静音或者被播放。voice_tag

voice_tag是一个字符串，在“voice”频道内可以voice_tag可以控制关联角色声音文件的静音或者播放。

前缀和后缀 这个设计允许在角色名字或者展现文本上添加前缀和后缀。前缀和后缀可以用在每一行对话的前后添加引用内容。what_prefix

显示对话内容之前，添加的前缀字符串。what_suffix

显示对话内容之前，添加的后缀字符串。who_prefix

显示角色名字之前，添加的前缀字符串。who_suffix

显示角色名字之前，添加的后缀字符串。

改变角色显示名 该可选项用于控制显示角色名。dynamic

该参数若为True，角色名 name 应是一个包含python表达式的字符串。该字符串会在每行对话执行前先演算，将演算结果用作角色名。

互动控制 这些可选项在“对话展示、发生互动、模式输入”情况下控制显示效果。condition

若给定，该参数应是一个包含python表达式的字符串。若表达式结果为False，对话不会发生，即say语句不会执行。interact

若该值为True，默认情况下无论对话何时被展现，都会发生一项互动。若该值为False，则互动不会发生，而一些额外元素可以被添加到界面上。advance

若该值为True，默认情况下用户可以快进语句执行，还有一些其他的快进方式(比如跳过skip和auto-forward mode自动前进模式)也将生效。若该值为False，用户不能跳过say语句，除非脚本中出现某些替换方法(比如跳转超链接)。mode

该参数是一个字符串，给定了角色发言时进入的模式(mode)。详见模式(mode) 章节。callback

角色发言时，若有事件(event)发生则会被调用的函数。详见角色(character)回调(callback) 章节。

点击继续 “点击继续”提示是在(一段内容)所有文本均已展示完的情况下，通常出现一次，提醒用户进入下一部分内容。ctc

一个用做“点击继续”提示的可展现部件，若有其他特殊提示被使用时可能不会展现。ctc_pause

当文本显示被{p}或{w}标签(tag)暂停时，用作“点击继续”提示的一个可视组件。ctc_timedpause

当文本显示被{p=}或{w=}标签(tag)暂停时，用作“点击继续”提示的一个可视组件。当该值为None时，会使用 ctc_pause 的值作为默认值。若你想要使用 ctc_pause 而不是 ctc_timedpause ，请使用 Null() 。ctc_position

该参数控制“点击继续”提示的位置。若值为 "nestled" ，该提示会作为目前展示文本的一部分出现，在最后一个字符显示后立即出现相应提示。若值为 "fixed" ，提示会被直接添加到界面上，其在界面上的位置由位置样式属性控制。

界面显示对话使用到一个界面。该入参允许你选择界面(screen)，并传入参数。screen

显示对话时使用的界面名。

关键词参数以前缀 show_ 开头，去掉前缀后传参给界面(screen)。例如， show_myflag 的值会改为变量 myflag 并传参给界面(screen)。(myflag变量并不是默认会用参数，但可以被一个定制对话界面使用。)

鉴于某些历史原因，show系列变量由Ren’Py引擎处理：show_layer

若给定了这个参数，其应该是一个字符串，这个字符串给定了展现“说话”界面所在图层的名字。

样式化文本和窗口 以 who_ 、 what_ 和 window_ 开头的关键词参数，会去掉前缀后分别用于样式 <styles> 角色名、对话文本和窗口内容。

例如，若一个角色被给定了关键词参数 who_color="#c8ffc8" ，角色名的颜色就被改变，这里的例子中会被改成绿色。 window_background="frame.png" 是把包含该角色的对话窗口背景设置为图片frame.png。

应用于角色名、对话文本和窗口的样式化，也可以使用这种方式进行设置：分别对应使用 who_style ， what_style 和 window_style 参数。

设置 config.character_id_prefixes 后，就可以样式化其他可视组件了。例如，如果使用了默认的GUI配置，带有前缀 namebox_ 的样式将会应用在发言角色名上。

带有图像属性(attribute)的say语句

当一个角色与一个图像标签(tab)关联，包含对应角色的say语句将在角色名和第二个字符串之间就可以插入图像属性(attribute)。

在这中情况下，如果带有给定标签(tag)的某个图片需要显示，Ren’Py会定位一条包含角色标签(tag)和属性(attribute)的show命令。如果图片未显示，Ren’Py会保存属性(attribute)并用于头像，但依然不会显示图片。

举例:

define e = Character("艾琳", image="eileen")

label start:

    show eileen mad
    e "我对你有点失望。"

    e happy "不过这都是过去的事了。"

相当于：

define e = Character("艾琳")

label start:

    show eileen mad
    e "我对你有点失望。"

    show eileen happy
    e "不过这都是过去的事了。"

在上面的例子中，mad 和 happy 会互相替换。不过也可以可以直接从 happy 恢复而不用指定 mad 属性。办法是使用减号(-)，具体请参考 show语句。

举例：

define e = Character("艾琳")

label start:

    show eileen
    e mad "我对你有点失望。"

    e happy "虽然还挺有趣的。"

    e -happy "我不清楚现在该怎么看了。"

如果在图像属性前面加一个 @ 符号，图像属性的改变将是临时性的，在执行完这行对话脚本后会恢复成上一个图像属性。

举例：

define e = Character(“艾琳”, image=”eileen”)label start:
show eileen mad e “我对你有点失望。”
e @ happy “虽然还挺有趣的。”
e “我不清楚现在该怎么看了。”

两种语法可以混用，在 @ 符号之前表示永久改变，符号后面表示临时改变一次。

e happy @ vhappy "真的！一切都改变了。"

减号也可以与 @ 符号混用：

e @ right -mad "我的怒火暂时得到了平息……"
e "但是！"

使用这个方式，若需要在图片改变时触发一个转场(transition)效果的话，将config.say_attribute_transition设置为一种转场(transition)即可。若要设置更多控制项，可以使用 config.say_attribute_transition_callback 。

前言

注释