动画和变换语言 link

Ren’Py脚本语句 link

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

atl_transform ::=  "transform" name "(" parameters ")" ":"
                      atl_block

transform left_to_right:
    xalign 0.0
    linear 2.0 xalign 1.0
    repeat

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 ::=  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 语句或者 ui 的函数时。)

ATL语句 link

下面这些都是ATL语句。

atl_interp ::=  ( warper simple_expression | "warp" simple_expression simple_expression )?
                ( property simple_expression ( "knot" simple_expression )*
                | "clockwise"
                | "counterclockwise"
                | "circles" simple_expression
                | simple_expression )*

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

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

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

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

atl_time ::=  "time" simple_expression

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

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

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

atl_pass ::=  "pass"

atl_repeat ::=  "repeat" (simple_expression)?

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

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

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

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

    pause 1.0
    repeat

atl_parallel ::=  "parallel" ":"
                     atl_block

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

atl_event ::=  "event" name

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

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

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

atl_counts ::=  "contains" ":"

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

atl_function ::=  "function" expression

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

atl_animation ::=  "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

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/

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

python early hide:

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

transform特性列表 link

transform存在以下特性(property)：

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

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

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设置为相同的值。

xoffset link

Type:	float
Default:	0.0

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

yoffset link

Type:	float
Default:	0.0

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

xcenter link

Type:	float
Default:	0.0

将xpos设置为指定的特性值(整个区域xpos最大值的一半)，将xanchor设置为0.5。

ycenter link

Type:	float
Default:	0.0

将ypos设置为指定的特性值(整个区域ypos最大值的一半)，将yanchor设置为0.5。

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，锚点会定位在关联的子组件上，当子组件发生变换时拉伸并旋转。实际效果是，当子组件拉伸或旋转时，这项值可以指定子组件以指定的锚点拉伸或旋转。

zoom link

Type:	float
Default:	1.0

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

xzoom link

Type:	float
Default:	1.0

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

yzoom link

Type:	float
Default:	1.0

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

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。

around link

Type:	(position, position)
Default:	(0.0, 0.0)

若该值非None，则指定了极坐标系的中心点坐标值，以整个区域的左上角为原点。在position模式下，设置的中心点可用于圆周运动。

alignaround link

Type:	(float, float)
Default:	(0.0, 0.0)

若该值非None，则指定了极坐标系的中心点坐标值，以整个区域的左上角为原点。在align模式下，设置的中心点可用于圆周运动。

angle link

Type:	float

获取极坐标系中角度的值。极坐标中心未设置的情况下不能获取。

radius link

Type:	position

获取极坐标系中半径的值。极坐标中心未设置的情况下不能获取。

crop link

Type:	None 或 (int, int, int, int) 或 (float, float, float, float)
Default:	None

若该值非None，会使用给定的矩形剪裁可视组件。指定的矩形是一个(x, y, width, height)形式的元组。如果 crop_relative 为True并且元组内元素的值是浮点数(float)，width和height用作比例值，与原图像的宽和高分别相乘输出结果。否则，数值代表像素数。

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

crop_relative link

Type:	boolean
Default:	False

如果crop_relative为True，crop元组里的width和height用作分数，与原图像的宽和高分别相乘输出结果。

corner1 link

Type:	None 或 (int, int)
Default:	None

若该值非None，给定了剪裁框的左上角坐标。crop优先级高于该项。

corner2 link

Type:	None 或 (int, int)
Default:	None

若该值非None，给定了剪裁框的右下角坐标。crop优先级高于该项。

size link

Type:	None 或 (int, int)
Default:	None

若该值非None，将可视组件伸缩至给定的尺寸。

xsize link

Type:	None 或 int
Default:	None

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

该值受到 fit 影响。

ysize link

Type:	None 或 int
Default:	None

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

该值受到 fit 影响。

fit link

Type:	None 或 string
Default:	None

若该值非None，会按下面表格的方式调整尺寸。表格中的“维度”视 xsize 和 ysize 不为空的情况而定。

值	描述
contain	在不超过任何维度尺寸的原则下近可能大。保持宽高比。
cover	在不超过任何维持尺寸的原则下尽可能小。保持宽高比。
None 或 fill	将可视组件拉伸/挤压，以匹配各维度指定大小。
scale-down	类似 contain，但不会增加可视组件的尺寸。
scale-up	类似 cover，但不会增加可视组件的尺寸。

maxsize link

Type:	None 或 (int, int)
Default:	None

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

subpixel link

Type:	boolean
Default:	False

若该值为True，使用子像素(subpixel)坐标系统在界面上放置子物体。

子像素(subpixel)位置会对绘入像素的色彩(包括不透明度)产生影响，但不会对像素原来的色彩产生影响。 当子像素位置与运动图像一起出现时(常见情况)，图像应该在运动方向保留一点透明的边。

举例来说，如果某个角色精灵(sprite)会水平移动，最好在左右两侧遇到透明的边界。 避免出现角色边缘与背景颜色发生混合的问题。

delay link

Type:	float
Default:	0.0

如果某个变换(transform)如同转场(transition)般使用，这个值定义了转场时间。

events link

Type:	boolean
Default:	True

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

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

图像水平方向使用tile方式码放图像的次数。(如果给定了xpan的值则忽略本项。)

ytile link

Type:	int
Default:	1

图像垂直方向使用tile方式码放图像的次数。(如果给定了ypan的值则忽略本项。)

matrixcolor link

Type:	None 或 矩阵 或 MatrixColor对象
Default:	None

若该值非None，该特性值用于将此变换下的所有子组件上色。详见 Matrixcolor 。

blur link

Type:	None 或 float
Default:	None

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

使用该特性的前提是启用基于模型的渲染器，将 config.gl2 设置为True。

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

3D舞台特性：

perspective、 matrixanchor、 matrixtransform、 zpos、 zzoom

基于模型渲染特性：

blend、 mesh、 mesh_pad、 shader

GL特性：

GL特性

uniforms：

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

这些特性按照以下顺序应用：

1. tile
2. mesh, blur
3. crop, corner1, corner2
4. size, maxsize
5. zoom, xzoom, yzoom
6. pan
7. rotate
8. zpos
9. matrixtransform, matrixanchor
10. zzoom
11. perspective
12. nearest, blend, alpha, additive, shader.
13. matrixcolor
14. GL Properties, Uniforms
15. position properties

圆周运动 link

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

Ren’Py会合理运用angle和radius特性，触发圆周运动。如果transform处于align模式，设置angle和radius同时也会设置align特性。否则，就会设置pos特性。

外部事件消息 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

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