動畫和變換語言 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 語句或者 ui 的函數時。)

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函數。 (即，將線性時間轉為非線性時間。)可以使用在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

    # 設置旋轉圓心
    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)

    # 同時修改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)的執行總時長。

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 或 old_widget 參數)的情況下，該變換會包含在表達式中，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對象之外，該函數不應該包含其他作用。 在可以在任意時間傳入任意值，以啟用預載入。

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 訪問。該模組包含了上述所有函數。

我們可以在一個 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設置為相同的值。

offset link
Type:

(int, int)

Default:

(0, 0)

可視組件在兩個方向偏離的像質數。向右和向下偏離時是正數。

xoffset link
Type:

int

Default:

0.0

可視組件在水平方向偏離的像質數。向右偏離時是正數。

yoffset link
Type:

int

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。

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，則指定了極坐標系的中心點坐標值，以整個區域的左上角為原點。 之後 angle 和 radius 特性會使用該坐標作為極坐標原點。

angle link
Type:

float

該特性給出極坐標系下某個坐標的角度資訊。角度的單位是度(degree)，0度時在螢幕正上方，90度時在螢幕右方。

Ren’Py會將角度的值控制在0到360度的區間內，有0度不包含360度。 當數值超過這個區間範圍時，Ren’Py使用前會做處理。(角度值設置為-10度，等效於將角度設置為350度。)

radius link
Type:

position

極坐標系下坐標的半徑。該值的類型與最後一次設置的半徑值類型相同，默認類型為絕對(absolute)像素點數。

如果值是浮點數，會被自動縮小到剛好能適用於寬度和高度的某個值。

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)

極坐標系下錨點坐標的半徑。該值的類型應該與 anchoraround 和 anchor 值的類型一致。

alignaround link
Type:

(float, float)

該特性會將 around 和 anchoraround 設置為同一值。

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，給定了剪裁框的左上角坐標。crop優先度高於該項。

corner2 link
Type:

None 或 (position, position)

Default:

None

若該值非None，給定了剪裁框的右下角坐標。crop優先度高於該項。

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 不為空的情況而定。

值

描述

contain

在不超過任何維度尺寸的原則下近可能大。保持寬高比。

cover

在不超過任何維持尺寸的原則下盡可能小。保持寬高比。

None 或 fill

將可視組件拉伸/擠壓，以匹配各維度指定大小。

scale-down

類似 contain，但不會增加可視組件的尺寸。

scale-up

類似 cover，但不會增加可視組件的尺寸。
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不同版本的模糊細節可能存在差異。模糊的結果可能存在瑕疵，尤其是模糊數值不斷發生修改的情況下。

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變數。

這些特性按照以下順序應用：

  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

下列特性不應再使用近期開發的遊戲中，可能會與其他功能特性發生衝突。 暫時保留這些特性是考慮到相容性。

crop_relative link
Type:

boolean

Default:

True

若為False，crop 的值將作為像質數的值，而不再是原圖像的寬度或高度的比例。

如果計算結果是某個絕對數值像質數，應該將 absolute 實例應用到 crop 特性，而不是crop_relative特性。 必要時，不確定類型的數值可以傳給 absolute 做處理。 如果需要使用某個指定的數值，就應該使用 crop property 而不是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會比較起始坐標點並找出極坐標中心。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、insensitive、selected_insensitive

當包含此transform的按鈕或者被此transform包含的按鈕，出現對應的狀態名稱時觸發。

替換變換 link

使用 Transform() 類定義的變換可以使用另一個同類對象替換。變換的特性從前一個變換對象中繼承。

When the show statement has multiple transforms in the at list, the transforms are matched from last to first, until one list runs out. For example, in 如果 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語句塊用作轉場時，以上兩個參數分別用作轉場的起始和結束畫面。