动画和变换语言 link

动画和变换语言(简称ATL)提供了一种高级方式实现可视组件的展示、界面布置、应用各种变换(比如旋转、alpha遮罩)等。ATL语言可以根据时间变化实现那些效果，也可以对事件类消息做出响应。

在Python中，与ATL变换等效的是 Transform() 类组件。目前没有办法通过编程创建一个ATL变换效果。

Ren’Py脚本语句 link

ATL可以包含在Ren’Py脚本语句中。

transform语句 link

transform 语句创建了一个变换(transform)效果，可以在某个at分句中使用。transform语句的语法如下：

atl_transform ::=  "transform" qualname ( "(" parameters ")" )? ":"
                      atl_block

transform语句必须在初始化时运行。如果在 init 语句块(block)之外发现transform语句，其会被自动放入一个 init 语句块中并设置其优先级为0。定义的transform可能需要一些参数，被调用时必须提供。 最右侧的参数可以使用等号“=”指定默认值(例如，transform a (b, c=0):)。

qualname 必须是一个使用英文标点“.”分割的Python标识符。使用ATL创建的transform与 qualname 绑定， 如果存在 store 则保存在对应存储空间中。

transform left_to_right:
    xalign 0.0
    linear 2.0 xalign 1.0
    repeat

transform ariana.left:
    xcenter .3

带ATL语句块的image语句 link

使用ATL的另一种方法是，在 image 语句中包含ATL语句块。这将某个图像与给定的transform绑定。由于没有办法向该transform传入参数，所以只在transform自身定义了某个动画的情况下才有用。带ATL语句块的image语句语法如下：

atl_image ::=  "image" image_name ":"
                  atl_block

image eileen animated:
    "eileen_happy.png"
    pause 1.0
    "eileen_vhappy.png"
    pause 1.0
    repeat

带ATL语句块的scene和show语句 link

最后一种使用ATL的方法是，包含在 scene 或者 show 语句中。这种方法可以通过ATL变换扭曲图像。

atl_scene ::=  stmt_scene ":"
                   atl_block
atl_show  ::=  stmt_show ":"
                   atl_block

scene bg washington:
    zoom 2.0

show eileen happy:
    xalign 1.0

ATL语法和语义 link

一个ATL语句块(block)由一个或多个逻辑行组成，使用相同的缩进量。每个ATL语句块中的逻辑行都必须包含一条或多条ATL语句。

总共有两种ATL语句：简单ATL语句和复杂ATL语句。简单语句不使用ATL语句块。单条逻辑行就可能包含一条或多条ATL语句，使用英文逗号分隔。复杂语句会包含语句块(block)。复杂语句的第一行会以英文冒号( ":" )结尾：

默认情况下，语句块(block)里会从第一条语句开始顺序执行所有语句。当整个语句块达到结尾时执行就会被终止。time语句会改变这种执行逻辑，详见后面的段落。

当语句块(block)中所有语句都终止时，语句块的执行也就被终止了。

如果ATL语句需要某个表达式赋值，只能在transform初次加入场景列表时进行赋值。(比如使用 show 语句或者某个界面显示展示部分变换时。)

ATL语句 link

下面这些都是ATL语句。

interpolation语句 link

interpolation语句语句是ATL控制变换的主要方式。

atl_properties ::=  ( property simple_expression ( "knot" simple_expression )*
                    | "clockwise"
                    | "counterclockwise"
                    | "circles" simple_expression
                    | simple_expression )*

atl_interp ::=  ( warper simple_expression | "warp" simple_expression simple_expression )? atl_properties
                | ( warper simple_expression | "warp" simple_expression simple_expression )? ":"
                   atl_properties

interpolation语句的第一部分用于选择使用的time-warp函数。 (即，将线性时间转为非线性时间，关于warper的信息详见 warpers 。)可以使用在ATL注册的warp类函数名，或者使用关键词“warp”开头的某个表达式代表的函数。 无论使用的是哪种函数，后面跟着的数字表示整个interpolation过程消耗的时间，单位为秒。

transform builtin_warper:
    xpos 0
    ease 5 xpos 520

init python:
    def my_warper(t):
        return t**4.4

define my_warpers = [my_warper]

transform accessed_as_function:
    xpos 0
    warp my_warpers[0] 5 xpos 520
    warp my_warper 3 xpos 100

详见 warpers 获取更多关于warper函数的信息。

如果没有给定warp类函数，interpolation过程会瞬间完成。否则就会持续给定的那段时间，至少一帧。

时间warp和范围值常用于计算完成的进度。这个进度通过各项interpolation占据整个interpolation语句的总进度来计算。每个interpolation执行前，先取进度值。warp类返回的结果就是完成进度。

interpolation语句可以包含一些其他分句。若出现了特性(property)和对应的值，在interpolation结尾，特性(property)就能获得那个值。该值的获得可以通过以下几种方式：

  • 如果那个值后面跟着一个或者两个节点，就使用样条(spline)运动。整个interpolation开头的特性值就是起点，上文提到的特性值就是终点，连接符用于控制样条(spline)。(译者注：在CAD和CG中，样条spline通常是指分段定义的多项式参数曲线。)

  • 如果interpolation语句包含一个“clockwise”或者“counterclockwise”分句，就使用圆周(circular)运动，后面会解释这点。

  • 除了以上两种情况，根据完成度均分，并将对应的值interpolate插入到起点与终点之间。

如果出现的是简单表达式，其可以简化为一个变换(transform)，这个变换是一个最简单的interpolate语句，不包含warp、spline或者circular行为。变换(transform)中的各项特性(property)会如同直接包含在interpolation语句中一般被处理。

warper后面可以跟一个英文冒号(:)。 这种情况下，warper后可以跟一个或多个如上阐述的从句。 这样做可以让ATL可以同时对多个特性进行插值。

一些interpolation语句样例如下：

show logo base:
    # 在界面的右上角显示logo。
    xalign 1.0 yalign 0.0

    # 将某物平移到左端，耗时1.0秒。
    linear 1.0 xalign 0.0

    # 将某物移动至正中央(truecenter)，耗时1秒。使用ease的warp效果实现。
    ease 1.0 truecenter

    # 暂停1秒。
    pause 1.0

    # 设置旋转圆心
    anchor (.5, .5)

    # 使用circular运动带着我们旋转并从界面顶端离开。
    # 耗时2秒钟。
    linear 2.0 yalign 0.0 clockwise circles 3

    # 使用样条运动环绕界面移动。
    linear 2.0 align (0.5, 1.0) knot (0.0, .33) knot (1.0, .66)

    # 同时修改xalign和yalign。
    linear 2.0 xalign 1.0 yalign 1.0

    # 在一个语句块中做同样的操作。
    linear 2.0:
        xalign 1.0
        yalign 1.0

一种重要的特殊情况是暂停warper，pause后面只跟一个时间值，触发ATL暂停对应的时间。

有些特性(property)可以使用多种类型的值。例如，xpos 特性可以是int、float或者 absolute 类型。 如果计算某个插值时，新旧两个值是不同的数据类型，具体表现是未定义的。

time语句 link

time 语句是一种简单控制语句。其包含一个简单表达式，可以算出一个时间点，单位为秒。这个时间点表示其所在语句块(block)从开始执行到time语句结束的总时长。

atl_time ::=  "time" simple_expression

当time语句中给定的“time”结束后，后面的语句才会开始执行。在上一个语句还在执行的情况下，这种控制转换依然会执行，也能强行终止任意优先级的语句。

time语句隐含了一个pause语句，表示暂停无限长时间。这表示如果主控流程不能抵达time语句处，它就会保持等待直到time语句获取流程控制权。

当一个语句块(block)中存在多个time语句时，它们各自的结束时间点必须按顺序严格递增。

image backgrounds:
    "bg band"
    time 2.0
    "bg whitehouse"
    time 4.0
    "bg washington"

表达式语句 link

表达式语句是一种以简单表达式开头的简单语句。可能会带一个分句，是另一个简单表达式。

atl_expression ::=   simple_expression ("with" simple_expression)?

第一个简单表达式可能等效的东西有三种：

  • 如果是一个ATL变换(transform)，并且该变换没有应用到其子组件(直接作为变换被调用或者用作 child 入参)的情况下，该变换会包含在表达式中，with 分句会被忽略。

  • 如果是一个整数或者浮点数，会执行对应时间(单位为秒)的暂停。with 分句会被忽略。

  • 以上都不是的话，表达式会被看作一个可视组件。当分句执行时，该组件替换变换(transform)的子组件，使其可以用作动画。如果出现了 with 分句，第二个表达式会被认为一个转场(transition)，并应用于新旧可视组件的替换表现。

transform move_right:
    linear 1.0 xalign 1.0

image atl example:
     # 显示logo_base.png
     "logo_base.png"

     # 暂停1.0秒
     1.0

     # 使用溶解效果显示logo_bw.png
     "logo_bw.png" with Dissolve(0.5, alpha=True)

     # 运行名为move_right的tranform.
     move_right

pass语句 link

atl_pass ::=  "pass"

pass 语句是一个简单语句，不会触发任何效果。pass语句可以用于分隔其他语句。比如出现两套choice语句的时候，如果不用pass语句，选项会混在一起。

repeat语句 link

repeat 语句是一种简单语句，包含它的语句块(block)会从开头重新执行。如果repeat中出现了一个表达式，该表达式可以计算出一个整数。这个整数就是整个语句块(block)重复执行的次数。(“repeat 2”表示语句块最多会执行2次。)

atl_repeat ::=  "repeat" (simple_expression)?

repeat语句必须是一个语句块(block)的最后一个语句：

show logo base:
    xalign 0.0
    linear 1.0 xalign 1.0
    linear 1.0 xalign 0.0
    repeat

block语句 link

block 语句是一种复杂语句，包含了ATL语句块(block)。block语句用于对需要重复运行的语句分组。

atl_block_stmt ::=  "block" ":"
                         atl_block

label logo base:
    alpha 0.0 xalign 0.0 yalign 0.0
    linear 1.0 alpha 1.0

    block:
        linear 1.0 xalign 1.0
        linear 1.0 xalign 0.0
        repeat

choice语句 link

choice 语句是一种复杂语句，其定义了一个所有可选项的集合。Ren’Py会选取集合中的某一个选项，执行与该选项相关的ATL语句块(block)，之后跳转到choice语句块结束处。

atl_choice ::=  "choice" (simple_expression)? ":"
                    atl_block

choice语句会将语句块(block)中连续出现的多个choice选项都放入一个选项集之中。如果选项后面出现一个简单表达式，这个表达式的值应该是一个浮点数，表示对应选项的权重；如果没有权重表达式，默认值为1.0。

image eileen random:
    choice:
        "eileen happy"
    choice:
        "eileen vhappy"
    choice:
        "eileen concerned"

    pause 1.0
    repeat

parallel语句 link

parallel 语句用于定义一个可以并行执行的ATL语句块的集。

atl_parallel ::=  "parallel" ":"
                     atl_block

parallel语句会将语句块(block)中连续出现的多个parallel项都放入一个并行集之中。当整个语句块中所有语句都执行完后，parallel语句才会终止。

语句块中的所有并行语句都应各自独立，并使用不同的特性(property)参数。当两个并行分支修改了同一项特性(property)，会产生无法预料的结果。

show logo base:
    parallel:
        xalign 0.0
        linear 1.3 xalign 1.0
        linear 1.3 xalign 0.0
        repeat
    parallel:
        yalign 0.0
        linear 1.6 yalign 1.0
        linear 1.6 yalign 0.0
        repeat

event语句 link

event 语句是一个简单语句，其会使用给定的名称触发一个事件(event)。

atl_event ::=  "event" name

当在某个语句块(block)运行过程中出现某个事件(event)时，语句块会检查自身是否存在对应事件名的处理器(handler)。如果处理器存在，主控流程会切换到对应的事件处理器。否则，事件会广播至所有事件处理器。

on语句 link

on 语句是一种复杂语句，其定义事件处理器(handler)。on语句会将语句块(block)中连续出现的多个on项都放入一个事件集之中。on语句可以只处理某一个事件名，或者使用逗号分隔的事件名列表。

atl_on ::=  "on" name [ "," name ] * ":"
                 atl_block

on语句用于处理各种事件(event)。当某个事件被处理后，其他的事件处理就会停止，并且会立即进入新事件的处理流程。当某个事件处理器没有新的待处理事件，就会产生 default 事件(已经处理 default 事件的情况除外)。

on语句的执行不会自然终止。(但是其可以被time语句，或者关联的事件处理器终止。)

show logo base:
    on show:
        alpha 0.0
        linear .5 alpha 1.0
    on hide:
        linear .5 alpha 0.0

transform pulse_button:
    on hover, idle:
        linear .25 zoom 1.25
        linear .25 zoom 1.0

contains语句 link

contains 语句将可视组件安置在ATL的transform中。(作为transform的子组件。)总共有两类contains语句的变种。

contains表达式变种使用某个表达式，将表达式设为transform的子组件。当希望ATL的transform容纳而不是引用另一个ATL的transform时，这个变种就会有用。

atl_contains ::=  "contains" expression

transform an_animation:
    "1.png"
    pause 2
    "2.png"
    pause 2
    repeat

image move_an_animation:
    contains an_animation

    # 如果我们不使用contains语句，
    # 就会一直处于循环中并不能抵达这里
    xalign 0.0
    linear 1.0 yalign 1.0

contains语句块(block)允许我们定义一个ATL语句块(block)用作ATL transform的子组件。一个或多个contains语句块(block)会被组合，在 Fixed() 函数中扭曲(warp)，并设置为该transform的子组件。

atl_counts ::=  "contains" ":"

每个语句块都应该定义一个使用的可视组件，或者可能发生的错误。contains语句的执行是即时的，不会等待子组件的完成。contains语句可以说是语法糖，使我们很容易将参数传给它的子组件。 (译者注：语法糖(Syntactic Sugar)，也称作糖衣语法。由英国计算机科学家彼得·约翰·兰达(Peter J. Landin)发明。指计算机语言中添加的某种语法，对语言的功能并没有影响，能更方便程序员使用。通常来说使用语法糖能够增加程序的可读性，从而减少程序代码出错的机会。)

image test double:
    contains:
        "logo.png"
        xalign 0.0
        linear 1.0 xalign 1.0
        repeat

    contains:
        "logo.png"
        xalign 1.0
        linear 1.0 xalign 0.0
        repeat

function语句 link

function 语句允许ATL使用Python函数控制ATL特性(property)。

atl_function ::=  "function" expression

这些函数与 Transform() 具有相同的识别标志：

  • 第一个入参是一个transform对象。transform特性可以通过该对象进行设定。

  • 第二个入参是显示时间轴，表示函数开始执行到现在经过的秒数。

  • 第三个入参是动画时间轴，表示具有相同标签(tag)的某物在整个界面上已存在的秒数。

  • 如果函数返回一个数值，其会在数值对应的时间(秒)后再次被调用。(0秒表示尽可能快地调用该函数。)如果函数返回空值(None)，主控流程会跳到下一个ATL语句。

除了修改第一个入参中的Transform对象之外，该函数不应该包含其他作用。 在可以在任意时间传入任意值，以启用预加载。

注意，function 不是一个变换特性，并且其跟 Transform() 的 function 参数也不完全一致。

init python:
    def slide_function(trans, st, at):
        if st > 1.0:
            trans.xalign = 1.0
            return None
        else:
            trans.xalign = st
            return 0

label start:
    show logo base:
        function slide_function
        pause 1.0
        repeat

animation语句 link

使用 animation 语句时，必须将其放在整个ATL语句块的开头，告诉Ren’Py该语句将使用动画时间轴。

atl_animation ::=  "animation"

与普通的显示时间轴相比，在带有相同标签(tag)的图像(image)或界面(screen)开始显示的那一刻，animation时间轴就将进行计时并被所有相同标签(tag)的图像和界面共享。 animation时间轴常用于动画过程中的图像替换。例如：

image eileen happy moving:
    animation
    "eileen happy"
    xalign 0.0
    linear 5.0 xalign 1.0
    repeat

image eileen vhappy moving:
    animation
    "eileen vhappy"
    xalign 0.0
    linear 5.0 xalign 1.0
    repeat

label start:

    show eileen happy moving
    pause
    show eileen vhappy moving
    pause

这个例子中，艾琳的立绘表情将在第一个 pause 语句处改变，但她的位置不会改变。 因为两个动画使用相同的animation时间轴，避免了更换立绘后出现图像位置不连续。 不使用 animation 语句的话，用户通过点击鼠标或屏幕后，角色的立绘位置将发生一次重置。

warpers link

warper是一类函数，其可以改变interpolation语句中定义的时间值。以下warper都是默认定义的。他们将时间t转换为t’，t和t’都是浮点数，t会将给定的时间值标准化为0.0到1.0。(如果该语句给定的原时长是0，那运行时t就是1.0。)t’的初始取值范围也是0.0到1.0，不过可以超出这个范围。

pause

暂停，然后跳变成新值。如果 t == 1.0，则 t' = 1.0；否则 t' = 0.0。

linear

线性插值。t' = t

ease

开头慢，中间加速，之后又减速。t' = .5 - math.cos(math.pi * t) / 2.0

easein

开头快，然后减速。t' = math.cos((1.0 - t) * math.pi / 2.0

easeout

开头慢，然后加速。t' = 1.0 - math.cos(t * math.pi / 2.0)

除此之外，Robert Penner的easing函数都是支持的。为了避免与上面的几个函数名重复，有些函数名字修改过。这些标准函数的图像可以在这个网站上查看 http://www.easings.net/

Ren’Py中函数名

easings.net中函数名

ease_back

easeInOut_back

ease_bounce

easeInOut_bounce

ease_circ

easeInOut_circ

ease_cubic

easeInOut_cubic

ease_elastic

easeInOut_elastic

ease_expo

easeInOut_expo

ease_quad

easeInOut_quad

ease_quart

easeInOut_quart

ease_quint

easeInOut_quint

easein_back

easeOut_back

easein_bounce

easeOut_bounce

easein_circ

easeOut_circ

easein_cubic

easeOut_cubic

easein_elastic

easeOut_elastic

easein_expo

easeOut_expo

easein_quad

easeOut_quad

easein_quart

easeOut_quart

easein_quint

easeOut_quint

easeout_back

easeIn_back

easeout_bounce

easeIn_bounce

easeout_circ

easeIn_circ

easeout_cubic

easeIn_cubic

easeout_elastic

easeIn_elastic

easeout_expo

easeIn_expo

easeout_quad

easeIn_quad

easeout_quart

easeIn_quart

easeout_quint

easeIn_quint

可以通过只读模块 _warper 访问这些warper效果。该模块包含了上述所有函数。 在Ren’Py内置效果中使用时间warp函数很有用，比如可以这样用：

with Dissolve(1, time_warp=_warper.easein_quad)

我们可以在一个 python early 语句块中，使用 renpy.atl_warper 构造器定义新的warper函数。定义warper函数文件需要在使用那个函数的其他任何文件之前被处理。定义的代码如下：

python early hide:

    @renpy.atl_warper
    def linear(t):
        return t

transform特性列表 link

transform存在以下特性(property)：

当给定的数据类型当作一个坐标 position 时，其可能是一个整型、 absolute 类型或者浮点型。如果是一个浮点型，其可以用作某块区域(用作坐标 pos )或者可视组件(用作锚点 anchor )的比例值。

需要注意的是，并非所有特性都是完全独立的。例如， xalign 和 xpos 都会更新同一批底层数据。在parallel语句中，对相同的数据，最多只允许一个语句块进行调整。。(这些可能都是在同一个语句块中。)angle和radius特性同时设置水平和垂直坐标。

坐标 link

pos link
Type:

(position, position)

Default:

(0, 0)

相对坐标，以整个区域左上角为原点。

xpos link
Type:

position

Default:

0

水平坐标，以整个区域的左边为坐标零点。

ypos link
Type:

position

Default:

0

垂直坐标，以整个区域的顶边为坐标零点。

anchor link
Type:

(position, position)

Default:

(0, 0)

锚点坐标，以可视组件左上角为原点。

xanchor link
Type:

position

Default:

0

锚点的水平坐标，以可视组件左边为坐标零点。

yanchor link
Type:

position

Default:

0

锚点的垂直位置，以可视组件顶边为坐标零点。

align link
Type:

(float, float)

Default:

(0.0, 0.0)

将pos和anchor设置为相同的值。

xalign link
Type:

float

Default:

0.0

将xpos和xanchor设置为相同的值。

yalign link
Type:

float

Default:

0.0

将ypos和yanchor设置为相同的值。

offset link
Type:

(absolute, absolute)

Default:

(0, 0)

可视组件在两个方向偏离的像素数。向右和向下偏离时是正数。

xoffset link
Type:

absolute

Default:

0.0

可视组件在水平方向偏离的像素数。向右偏离时是正数。

yoffset link
Type:

absolute

Default:

0.0

可视组件在垂直方向偏离的像素数。向下偏离时是正数。

xycenter link
Type:

(position, position)

Default:

(0.0, 0.0)

等效于将pos的值设置为该特性的值，并同时将archor设置为(0.5, 0.5).

xcenter link
Type:

position

Default:

0.0

等效于将pos的值设置为该特性的值，并同时将xanchor设置为0.5。

ycenter link
Type:

position

Default:

0.0

等效于将pos的值设置为该特性的值，并同时将yanchor设置为0.5。

subpixel link
Type:

boolean

Default:

False

若为True，子组件将根据子像素(subpixel)确定位置。

子像素位置还影响写入最终像素的颜色(包括不透明度)，但具体写入哪个像素依然是不变的。 如果子像素位置还会发生移动(很常见的情况)，移动方向上的即将进入的界面图像应该包含带透明度混合的边界。

例如，某个角色立绘在水平方向移动，最好在左右两侧设置半透明的边界。 对于实际大小超过整个可视区域的背景图就没必要使用该特性，反正边界部分是看不到的。

(译者注：subpixel往往跟MSAA相关。具体内容请借助搜索引擎学习。)

旋转 link

rotate link
Type:

float 或 None

Default:

None

若值为None，不会进行旋转。否则，图像会按指定的角度顺时针旋转。根据下面会提到的rotate_pad的配置值，旋转可视组件会导致组件尺寸改变。xanchor和yanchor不为0.5的情况下，旋转整个可视组件会让组件相对整个界面的坐标发生变化。

rotate_pad link
Type:

boolean

Default:

True

若该值为True，一个可以旋转的可视组件就会使用原本的宽度和高度填充旋转矩形，并确保旋转时不会改变组件的尺寸。若该值为False，transform会给定某个能应用于可视组件的最小尺寸，更适合用于自动匹配的旋转。

transform_anchor link
Type:

boolean

Default:

False

若该值为True，锚点会定位在关联的子组件上，当子组件发生变换时拉伸并旋转。实际效果是，当子组件拉伸或旋转时，这项值可以指定子组件以指定的锚点拉伸或旋转。

缩放与翻转 link

zoom link
Type:

float

Default:

1.0

该值根据系数对可视组件进行缩放。

xzoom link
Type:

float

Default:

1.0

该值根据系数对可视组件在水平方向进行缩放。负值可以让图像水平翻转(即与原图像互为左右镜像)。

yzoom link
Type:

float

Default:

1.0

该值根据系数对可视组件在垂直方向进行缩放。负值可以让图像垂直翻转(即与原图像互为上下镜像)。

像素效果 link

nearest link
Type:

boolean

Default:

None

若该值为True，可视组件及其子组件会使用近邻取样(nearest-neighbor)过滤绘制。若该值为False，可视组件及其子组件使用双线性(bilinear)过滤绘制。若该值为None，绘制方式从父组件继承，或者采用 config.nearest_neighbor 配置(默认值是false)。

alpha link
Type:

float

Default:

1.0

该值控制可视组件的不透明度。

alpha变换(transform)会分别作用于每个图像所包含的子组件。在子组件存在重叠部门的情况，这可能会导致一些不期望出现的结果，比如透过衣服看到角色之类的。 Flatten() 类可视组件可以解决这些问题。

additive link
Type:

float

Default:

0.0

该值控制Ren’Py加性混合后的表现效果。该值为1.0时，Ren’Py使用ADD操作器(operator)绘制；该值为0.0时，Ren’Py使用OVER操作器(operator)绘制。

加性混合会分别作用于transform的每一个子组件。

完全的加性混合不会改变目标图像的alpha通道值，并且添加上去的图像可能不是可见的，前提是那些图像没有直接绘制在某个不透明的表面上。(某些复杂的操作，像 Flatten()， Frame() 和某些转场，使用加性混合可能会出现问题。)

Warning

加性混合只被基于硬件的渲染器支持，比如OpenGL和DirectX/ANGLE渲染器。软件渲染器无法正确绘制加性图像。

图形系统启动后，如果加性混合可以被支持的话 renpy.get_renderer_info()["additive"] 的值会是true。

matrixcolor link
Type:

None 或 矩阵 或 MatrixColor对象

Default:

None

若非None，该特性值将应用到所有子组件并重新计算颜色。只有使用MatrixColor并且满足结构性相似的前提下，才能进行插值计算。 详见 Matrixcolor 。

blur link
Type:

None 或 float

Default:

None

使用 blur 像素数模糊图像的子组件， blur 数值不超过可视组件的边长。 Ren’Py不同版本的模糊细节可能存在差异。模糊的结果可能存在瑕疵，尤其是模糊数值不断发生修改的情况下。

极坐标 link

around link
Type:

(position, position)

Default:

(0.0, 0.0)

该特性指定了一个起点坐标，以整个区域左上角做原点。(根据 angle 和 radius 计算出的)极向量范围内的区域将被绘制。 以上两者共同决定了 pos 的值。

angle link
Type:

float

该特性给出极坐标系下某个坐标的角度信息。角度的单位是度(degree)，0度时在屏幕正上方，90度时在屏幕右方。

Ren’Py会将角度的值控制在0到360度的区间内，有0度不包含360度。 当数值超过这个区间范围时，Ren’Py使用前会处理成等效角度。(角度值设置为-10度，等效于将角度设置为350度。)

radius link
Type:

position

极坐标系下坐标的半径。

如果值是浮点数，会被自动缩小到刚好能适用于宽度和高度的某个值。

极坐标系的锚点 link

Note

使用极坐标系时同时也启用了锚点。通常最简单的处理就是将 anchor 设置为(0.5, 0.5)，即可视组件的中心。

anchoraround link
Type:

(position, position)

该特性指定了一个起点坐标，以整个区域左上角做原点。(根据 anchorangle 和 anchorradius 计算出的)极向量范围内的区域将被绘制。 以上两者共同决定了 anchor 的值。

anchorangle link
Type:

(float)

极坐标系下锚点坐标的角度。角度的单位是度(degree)，0度表示正上方，90度表示右方。

Ren’Py会将角度的值控制在0到360度的区间内，有0度不包含360度。 当数值超过这个区间范围时，Ren’Py使用前会处理成等效角度。(角度值设置为-10度，等效于将角度设置为350度。)

anchorradius link
Type:

(position)

极坐标系下锚点坐标的半径。 若该值是浮点数，将乘以可视组件的宽和高，计算得到结果。如果可视组件的高和宽不相等，计算结果不是absolute类型，最终会沿椭圆旋转。 因此，推荐将该特性设置为 int 或 absolute 类型的值。

剪裁与重新调整尺寸 link

crop link
Type:

None 或 (position, position, position, position)

Default:

None

若该值非None，会使用给定的矩形剪裁可视组件。指定的矩形是一个(x, y, width, height)形式的元组。

如果各种corner特性与crop特性同时出现，crop的优先级高于各种corner特性。

corner1 link
Type:

None 或 (position, position)

Default:

None

若该值非None，指定剪裁框的左上角坐标。剪裁时优先使用各corner特性值。 若crop_relative为启用状态，且该值为浮点型与子组件的尺寸相关。

corner2 link
Type:

None 或 (position, position)

Default:

None

若该值非None，指定剪裁框的右下角坐标。剪裁时优先使用各corner特性值。 若crop_relative为启用状态，且该值为浮点型与子组件的尺寸相关。

xysize link
Type:

None 或 (position, position)

Default:

None

若该值非None，将可视组件伸缩至给定的尺寸。等效于，将入参元组的第一元素赋值给 xsize，将入参元祖的第二元素赋值给 ysize。

该值受到 fit 影响。

xsize link
Type:

None 或 position

Default:

None

若该值非None，可是组件会按照给定的宽度缩放。

该值受到 fit 影响。

ysize link
Type:

None 或 position

Default:

None

若该值非None，可是组件会按照给定的高度缩放。

该值受到 fit 影响。

fit link
Type:

None 或 string

Default:

None

若该值非None，会按下面表格的方式调整尺寸。表格中的“维度”分别为：

  • 若 xsize 和 ysize 都不为None，这两项都会用作维度。

  • 若 xsize 和 ysize 只有其中一项不是None，则两个维度都使用非None项的值。

  • 若 xsize 和 ysize 都为None，且fit项不是None，则根据Transform中的宽度和高度作为两个维度的值。

若fit、xsize和ysize都是None，则该特性不生效。

值

描述

contain

在不超过任何维度尺寸的原则下近可能大。保持宽高比。

cover

在不超过任何维持尺寸的原则下尽可能小。保持宽高比。

None 或 fill

将可视组件拉伸/挤压，以匹配各维度指定大小。

scale-down

类似 contain，但不会增加可视组件的尺寸。

scale-up

类似 cover，但不会增加可视组件的尺寸。

全景图和平铺 link

xpan link
Type:

None 或 float

Default:

None

若该值非None，其被看作某个360度全景图中的经度。图像中央是0度，图像左端和右端分别是-180度和180度。

ypan link
Type:

None 或 float

Default:

None

若该值非None，其被看作某个360度全景图中的纬度。图像中央是0度，图像顶部和底部分别是-180度和180度。

xtile link
Type:

int

Default:

1

图像水平方向使用图像平铺的次数。

ytile link
Type:

int

Default:

1

图像垂直方向使用图像平铺的次数。

转场 link

详见 ATL转场 。

delay link
Type:

float

Default:

0.0

如果该变换(transform)用作转场(transition)，这个值定义了转场时间。

events link
Type:

boolean

Default:

True

若该值为True，事件消息会传给该变换(transform)的子组件。若该值为False，事件消息会被屏蔽。(这个机制可以用在ATL变换中，放置事件消息达到某些old_widget。)

其他 link

show_cancels_hide link
Type:

boolean

Default:

True

通常，某个同名或带同名标签(tag)的可视组件或界面，从隐藏状态转为显示状态时，将移除组件或界面的隐藏属性，变换中hide部分的效果将取消。 如果该特性为False，则不会中断和取消hide变换，而是会将hide变换的效果处理完。

此外，其他几组变换特性可以在文档其他地方找到：

3D舞台特性：

perspective、point_to、orientation、xrotate、yrotate、zrotate、matrixanchor、matrixtransform、zpos、zzoom

基于模型渲染特性：

blend、 mesh、 mesh_pad、 shader

GL特性：

GL特性

uniforms：

以 u_ 开头的特性可以用于 自定义着色器 中的uniform变量。

特性生效顺序 link

这些特性按照以下顺序生效：

  1. mesh, blur

  2. tile

  3. pan

  4. crop, corner1, corner2

  5. xysize, size, maxsize

  6. zoom, xzoom, yzoom

  7. point_to

  8. orientation

  9. xrotate, yrotate, zrotate

  10. rotate

  11. zpos

  12. matrixtransform, matrixanchor

  13. zzoom

  14. perspective

  15. nearest, blend, alpha, additive, shader

  16. matrixcolor

  17. GL Properties, Uniforms

  18. position properties

  19. show_cancels_hide

过期的变换特性 link

Warning

下列特性不应再使用近期开发的游戏中，可能会与其他功能特性发生冲突。 暂时保留这些特性是考虑到兼容性。

alignaround link
Type:

(float, float)

将 anchor、 around 和 anchoraround 设置为相同的值。

crop_relative link
Type:

boolean

Default:

True

若为False，crop 的值将作为像素数的值，而不再是原图像的宽度或高度的比例。

如果计算结果是某个绝对数值像素数，应该将 absolute() 实例应用到 crop 特性，而不使用crop_relative特性。 必要时，不确定类型的数值可以传给 absolute() 函数处理。

size link
Type:

None or (int, int)

Default:

None

xysize 的一个旧版本，将浮点值作为像素数的值进行插值操作。

maxsize link
Type:

None or (int, int)

Default:

None

若该值非None，可以使可视组件在box当中以合适的尺寸放大或缩小显示，同时保持横纵比。（请注意，这意味着长或宽其中一个尺寸可能小于此box的尺寸。）

若要实现同样结果，可以将 xysize 设定为同样的值，并把 fit 设置为“contain”。

圆周运动 link

当某个interpolation语句汇总包含关键词 clockwise 或 counterclockwise ，该语句就会触发圆周运动。 Ren’Py会比较起始坐标点(通过 pos、align、angle 和 radius)并找出极坐标中心(即 around)。 Ren’Py接着会计算运动角度。如果还出现了circles分句，Ren’Py会确保旋转对应的圈数。

外部事件消息 link

下列事件是自动触发的：

start

一种伪事件，进入 on 语句时触发，前提是没有更高优先级的事件出现。

show

使用 show 或者 scene 语句显示transform，并且给定标签(tag)没有对应已显示的图像时触发。

replace

使用 show 语句中的transform根据给定标签(tag)替换某个图像时触发。

hide

使用 hide 语句或等效的python语句中的transform时触发。

需要注意的是，transform被scene语句清除，或者退出其所在的上下文(比如退出游戏菜单)时，hide事件是不会触发的。

replaced

transform被另一个transform替换时触发。原transform的图像实际上并不会隐藏或移除，直到整个ATL语句块(block)执行完。

update

目前正在显示的界面发生更新，并且不是被另一个界面替换的情况时触发。随着这种情况很罕见却确实会出现，比如游戏加载资源时或者风格或者语言切换时。

hover、idle、selected_hover、selected_idle、insensitive、selected_insensitive

当包含此transform的按钮或者被此transform包含的按钮，出现对应的状态名称时触发。

替换变换 link

使用 Transform() 类定义的变换可以使用另一个同类对象替换。变换的特性从前一个变换对象中继承。

如果 show 语句中的at关键字后列出了多个变换待替换，则新变换列表从后往前依次替换，直到新替换变换列表全部换完。例如：

show eileen happy at a, b, c
"我们稍等一下。"
show eileen happy at d, e

e 变换替换了 c， d 变换替换了 b，而没有变换会替换 a。

替换时，旧变换的特性值由新变换继承。如果旧变换正处于动画中，则新变换继承的可能是中间的某个值。例如：

transform bounce:
    linear 3.0 xalign 1.0
    linear 3.0 xalign 0.0
    repeat

transform headright:
    linear 15 xalign 1.0

label example:
    show eileen happy at bounce
    pause
    show eileen happy at headright
    pause

这个例子中，精灵(sprite)会左右横跳，直到用户点击鼠标。 当用户点击鼠标后， bounce 中的 xalign 特性值将被 headright 继承。 精灵在x轴方向坐标移动的初始值，即是用户点击鼠标时的值。

位置相关特性(包括 xpos、ypos、xanchor 和 yanchor)继承时有一项特殊规则： 子组件设置的值会覆盖父组件的值。这样设计是考虑到可视组件往往只有一项位置信息，需要优先保证设置的值不受影响。 对位置特性的设置有多种方式，例如，xalign 会同时设置xpos和xanchor。

最后，如果某个 show 语句不包含 at 从句，则不需要搞特性值继承问题。为了避免继承，可以直接显示/隐藏对应的可视组件。

ATL转场 link

可以使用ATL变换定义一个转场(transition)。 这样定义的转场需要接受 old_widget 和 new_widget 入参，分别指定转场的起始和结束使用的可视组件。

ATL转场必须设置 delay 特性，表示转场时间，单位为秒。 还可以使用 events 特性，使旧组件屏蔽事件消息。

transform spin(duration=1.0, new_widget=None, old_widget=None):

    # 设置变换耗时
    delay duration

    # 置于正中
    xcenter 0.5
    ycenter 0.5

    # 转动旧组件
    old_widget
    events False
    rotate 0.0
    easeout (duration / 2) rotate 360.0

    # 转动新组件
    new_widget
    events True
    easein (duration / 2) rotate 720.0

特殊ATL关键词参数 link

Ren’Py中可以向ATL传入一些特殊参数。

child

ATL用作一个变换时，child参数将向原来的子组件传入变换并应用于子组件。 这用于精准控制。例如，可以实现子组件与其他可视组件之间的切换。

transform lucy_jump_scare(child):
    child      # 显示原来的子组件
    pause 5
    "lucy mad" # “jump scare”式惊吓.
    pause .2
    child      # 再显示原来的子组件.

还可以在 contains 语句块中放置原来的子组件：

transform marquee(width, height=1.0, duration=2.0, child=None):
    xcenter 0.5
    ycenter 0.5

    crop_relative True
    crop (0, 0, 0.5, 500)

    contains:
        child
        xanchor 0.0 xpos 1.0
        linear duration xanchor 1.0 xpos 0.0
old_widget, new_widget

当ATL语句块用作转场时，以上两个参数分别用作转场的起始和结束画面。