界面和界面語言 link

用戶在Ren’Py遊戲中所有的可見元素可以分為圖像和用戶介面兩大類。圖像通過scene、show和hide語句向用戶展示,也是故事敘述的大頭。其他所有可見的元素都屬於用戶介面。用戶介面可以通過界面實現訂製化。

界面有下列4種方式顯示:

  • 隱含在腳本語句執行中。例如,say語句會觸發 say 界面的顯示。
  • 自動顯示。例如,Ren’Py啟動後或者用戶退回到主選單時,會顯示 main_menu 界面。
  • 作為一個用戶行為,與按鈕、滑鼠按鍵或者鍵盤按鍵相關聯。默認情況下, save 界面是用戶滑鼠右擊或者按下退出(Esc)鍵才會展示。也可以定義一個on-screen按鈕用於顯示 save 界面。
  • 明確使用某些語句觸發界面顯示的情況。

可以一次顯示多個界面。

界面有兩個主要功能。第一個是向用戶顯示訊息。訊息的顯示可以使用文本、條(bar)和圖像(image)。使用這種方法顯示某些訊息是遊戲的需要。例如, say 界面用於向用戶顯示對話,包括說話人的名字和說話內容。

界面的另一個功能是允許用戶與遊戲交互。按鈕和條(bar)允許用戶觸發某些行為(action)和調整數值。Ren’Py包含一個預定義行為的池,允許用戶快進、個性化控制、讀檔和存檔等。創作者還可以使用Python編寫新的行為。

每次交互行為的啟動或重啟,都會更新界面。

界面的改變不應該引發界面之外可視區域的副作用。 Ren’Py會根據需要多次運行同一個界面。Ren’Py會在界面顯示之前運行一些運行圖像預載入進程。因此,如果界面有副作用,在預載入階段就會發生。

每個界面有一個作用範圍(scope)與其關聯,並有一些給定的變數值。如果某些界面中包含變數,首先在界面的作用範圍(scope)內查找變數,然後再查找全局變數。

界面語言 link

界面語言是顯示界面最正式的辦法。它包含定義新界面的語句、添加可視組件至界面的語句和控制型語句。

這是一個界面的樣例:

screen say(who, what):
    window id "window":
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

這段腳本的第一行是一個screen語句。Ren’Py中使用screen語句定義一個界面。界面的名字是 say,所以該界面用於顯示對話。其有兩個入參,分別是 whowhat

界面包含一個窗口,窗口id就叫“window”。窗口中包含一個垂直的框(box),框內的空間為10個像素。它包含兩個文本欄位(field),一個是發言者的名字,另一個是發言者的id。

界面語言語法 link

大多數界面語言語句使用通用的語法。(某些控制語句使用其他語法。)語句的開頭以某個關鍵字進入。

如果語句使用參數,參數就跟著開頭的關鍵字後面。參數列表是使用空格分隔的簡單表達式,除非有特殊情況。

固定位置參數後面會跟一個特性(property)列表。一個特性包括特性名稱和特性值組成。特性值是簡單表達式,除非有特殊情況。特性列表中各個特性使用空格分隔。

如果某個語句以英文冒號(:)結尾,後面就會跟一個語句塊(block)。語句塊的每一行可能是以下兩者之一:

  • 一個特性列表。
  • 一條界面語言語句。

screen語句 link

screen 語句在Ren’Py腳本語言中用於定義一個新的界面。其使用界面語言通用語法。

screen語句使用一個參數,即界面名。界面名不是一個簡單表達式,可以使用以下特性:

modal
若為True,該界面是一個模態框(modal)。一個模態框界面防止用於與它下層的可視組件發生互動,除了預設的keymap類。
sensitive
決定界面是否被啟用的表達式。每次交互行為時,該表達式都至少會被計算一次。
tag
被當作一個變數名處理,而不是一個表達式。該特性指定一個與界面關聯的圖像標籤(tag)。顯示某個界面會替換帶用相同圖像標籤的其他界面。這可以用來確保在相同的上下文環境下,同一時間只有顯示一個菜單界面。
zorder
該特性用於控制向用戶顯示界面的遠近。數值越大,界面距離用戶越近。預設值是0。
variant
如果該特性出現,應該是一個字串或者字串的列表,給定了待定義的變種界面。詳見 界面變種
style_prefix
該特性是一個字串,用於向界面所有子組件的樣式提供一個前綴, 如下描述
layer
該特性是一個字串,給定了顯示界面的默認圖層(layer)名。
screen hello_world():
     tag example
     zorder 1
     modal False

     text "Hello, World."

界面可以使用一個參數列表:

screen center_text(s, size=42):
     text s size size

用戶介面語句 link

用戶介面語句用於創建可視組件並添加至界面或某個封閉的可視組件。它們允許向用戶顯示訊息,用戶與遊戲的互動,以及遊戲中各種事件消息的相互作用。

所有用戶介面語句使用下列通用特性:

at

一個transform、transform的列表或者匿名transform(未定義直接在at中使用的transform)。

transform hello_t:
    align (0.7, 0.5) alpha 0.0
    linear 0.5 alpha 1.0

screen hello_title():
    text "Hello." at hello_t
    text "Hello.":
        at transform:
            align (0.2, 0.5) alpha 0.0
            linear 0.5 alpha 1.0

可用於wrap可視組件。show、hide、replace和replaced external事件消息會傳入transform,前提是transform是被直接添加到界面上的。

例如,如果某個vbox在某transform中被wrap,並直接添加到界面上,事件消息就會傳給那個transform。但如果某個按鍵文本是添加到vbox再被加入transform中被warp,那麼第二層的transform就不會接收到事件消息。

default_focus
如果出現了該特性,並且值為True,默認情況下該可視組件會得到焦點。只有一個可視組件可以擁有該特性。
id

用戶介面語句的標識號。當某個界面顯示時,特性值可以透過給定的標識符提供給可視組件。某些界面會根據創建的標識號請求某個可視組件。

默認情況下,這個 id 是自動生成的。

style
應用於可視組件的樣式名。其可能是一個字串名,也可能是一個樣式對象。該樣式指定樣式特性的預設值。
style_prefix

向可視組件及其子組件的樣式提供了一個前綴,例外情況是某些子組件用一個指定的樣式或樣式前綴。

樣式名由樣式前綴、下劃線和樣式後綴組成。樣式後綴通過樣式後綴 style_suffix 或可視組件決定。

例如,如果某個vbox有一個樣式前綴 "pref" ,這個vbox的樣式名就是 "pref_vbox" 。除非設置了某個指定的樣式或者樣式前綴,vbox內的按鈕會用樣式 "pref_button"

如果樣式不存在的話,使用這種方式接入的樣式會被自動創建。將前綴設置為 None 會將可視組件及其子組件的所有前綴都移除。

style_group
style_prefix 的一個別名,用在舊版本的Ren’Py中。
style_suffix

指定後綴,與 style_prefix 連在一起創建一個樣式名。如果後綴是 "small_button" ,前綴是 "pref" ,實用的樣式名就是 "pref_small_button"

如果不使用樣式前綴,就是直接使用樣式名。樣式後綴就會只應用於某一個可視組件,而不會用於其子組件。

focus
該特性使用一個字串或整數,並出於獲取焦點的需求,給出一個可視組件的名稱。Ren’Py會搜索與focus結構相似的特性名,並決定在某交互行為開始後最先獲取到focus的可視組件。如果某個框(box)給定了一個focus名,並且框內的第三個按鈕在交互行為結束時獲取到焦點,某個同名框(box)的第三個按鈕會在下一個交互行為開頭顯示為高亮。
tooltip
聲明某個可視組件的工具提示框。當可視組件獲得焦點時,該特性值會啟用 GetTooltip() 函數。詳見 Tooltips 章節。 傳入工具提示框的對象必須支持相等性(equality)。如果不支持比較相等,可能會導致無限死循環。
arguments
一個元組或列表,包含傳入可視組件的額外固定位置入參。
properties
一個字典,包含傳入可視組件的額外特性。

許多用戶介面語句使用樣式特性類或者transform特性。這些特性可以使用相關聯的樣式前綴,前綴決定了特性被應用的時機。例如,如果帶有 hover_size 特性,就會設置文本在滑鼠懸停狀態時的文本字號。

User interface statements take an as clause, which takes a variable name, without any quotes. The displayable that the statement creates is assigned to the variable. (An example can be found in the drag and drop documentation.) UI語句可以使用 as 分句,後面帶一個變數名,不需要引號。 語句創建的可視組件對象將聲明為變數。(在這裡可以找到一個樣例 拖拽組件.)

add link

在界面上添加一個圖像或其他的可視組件。添加時可以選擇使用 transform特性列表。如果至少使用了一項 Transform 特性,用於wrap圖像的transform就會被創建,特性值會賦予這個transform。

如果可視組件為None,那不會有任何東西添加到界面上。

add語句不使用任何子組件。

screen add_test():
    add "logo.png" xalign 1.0 yalign 0.0

bar link

創建一個原本水平的條(bar),可用於查看和調整數據。其使用以下特性:

value
條(bar)的當前值。可以是一個 條(bar)值 對象,或者一個數值。
range
條(bar)的最大值。如果 value 是一個數值的話,這個特性是必須的。
adjustment
該條(bar)所調整的 ui.adjustment() 對象。
changed
若該值存在,應該是一個Python函數。當 adjustment 改變時,這個函數會用調整後的值被調用。
hovered
當條(bar)獲取焦點後的行為。
unhovered
當條(bar)失去焦點後的行為。

value 或者 adjustment 之一必須給定。除此之外,該函數還是用以下特性:

條(bar)不包含任何子組件。

screen volume_controls():
    frame:
        has vbox

        bar value Preference("sound volume")
        bar value Preference("music volume")
        bar value Preference("voice volume")

按鈕(button) link

創建界面的一塊區域,可以通過點擊啟動並運行一個行為。按鈕(button)不接受參數,可以使用下列特性。

action
當按鍵啟動時會執行的行為。按鈕被點擊時會被啟動,用戶也可以使用其他方法選中按鈕並按下鍵盤“Enter”鍵。在 sensitive 特性沒有提供的情況下,它還能控制讓按鈕啟用sensitive;同樣,在 selected 特性沒有提供的情況下,它也嗯呢個控制按鈕被選中。
alternate
使用轉化過的辦法在按鈕啟動後運行的行為。當用戶在基於滑鼠的平台上那個點擊滑鼠右鍵,或者用戶在基於觸控的平台上長按某個按鈕,都會觸發。
hovered
當按鈕獲取焦點時運行的行為。
unhovered
當按鈕失去焦點時運行的行為。
selected
決定按鈕是否被選擇的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被選擇。
sensitive
決定按鈕是否被啟用的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被啟用。
keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的行為。
alternate_keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的可選變換行為。

它還可以使用下列特性:

按鈕使用一個子組件。如果0個、兩個或者更多子組件被應用,他們全部會自動整合為一個固定布局(fixed),並添加到按鈕上。

fixed link

fixed創建了一塊用於添加子組件的區域。默認情況下,固定布局(fixed)會擴展並填充整個可用區域,但 xmaximumymaximum 特性可以改變這點。

子組件們使用自身的位置樣式特性實現布局。如果沒有合適的設置位置,它們可能會重疊。

fixed語句不接受參數,後面跟以下特性:

fix使用多個子組件,它們會被添加到固定布局中。

顯示創建一個固定布局可視組件通常並不是必要的。每個界面都被包含在一個固定布局可視組件中,並且很多界面語言語句會自動創建一個固定布局的可視組件,前提是他們有兩個或更多子組件。

screen ask_are_you_sure:
    fixed:
         text "Are you sure?" xalign 0.5 yalign 0.3
         textbutton "Yes" xalign 0.33 yalign 0.5 action Return(True)
         textbutton "No" xalign 0.66 yalign 0.5 action Return(False)

框架(frame) link

框架(frame)是窗口,該窗口包含一個背景,可用於顯示用戶介面元素,例如按鈕、條(bar)和文本。其使用下列特性:

frame使用一個子組件。如果0個、兩個或者更多子組件被應用,他們全部會自動整合為一個固定布局(fixed),並添加到按鈕上。

screen test_frame():
    frame:
        xpadding 10
        ypadding 10
        xalign 0.5
        yalign 0.5

        vbox:
            text "Display"
            null height 10
            textbutton "Fullscreen" action Preference("display", "fullscreen")
            textbutton "Window" action Preference("display", "window")

grid link

grid在一個網格系統中顯示其子組件。每個子組件都會分配相同的區域大小,這個區域大小可以容納最大的子組件。

grid使用兩個參數。第一個參數是網格的行號,第二個參數是網格的列號。其使用下列特性:

transpose
若值為False,網格轉置。

其還使用以下特性:

grid中必須給定“行數×列數”的子組件。如果給出其他數量的子組件會發生錯誤。

screen grid_test:
     grid 2 3:
         text "Top-Left"
         text "Top-Right"

         text "Center-Left"
         text "Center-Right"

         text "Bottom-Left"
         text "Bottom-Right"

hbox link

hbox的各個子組件會邊靠著邊顯示,都在一個不可見的水準方塊(box)內。其不接受參數,後面跟以下特性:

UI可視組件的子組件會被添加到方框(box)中。

screen hbox_text():
    hbox:
         text "Left"
         text "Right"

圖片按鈕(imagebutton) link

創建一個包含圖像的按鈕,當指針懸停在按鈕上時,圖像狀態會發生改變。其不接受參數,使用下列特性:

auto

按鈕使用圖片自動定義。這個特性是個包含 %s 的字串。如果某個圖片特性是省略的,%s會被替換為對應特性名稱,並使用對應值作為對應特性的預設值。

例如,如果 auto 是 “button_%s.png”,並且 idle 特性省略,那麼idle的預設值就是 “button_idle.png”。類似的,如果 auto 是“button %s”,那麼 button idle 圖像就會被應用。

auto 特性的具體行為可以修改 config.imagemap_auto_function 實現訂製化。

insensitive
當按鈕不可用狀態時,使用在按鈕上的圖像。
idle
當按鈕沒有得到焦點狀態時,使用在按鈕上的圖像。
hover
當按鈕得到焦點狀態時,使用在按鈕上的圖像。
selected_idle
當按鈕被選中但是沒有得到焦點狀態時,使用在按鈕上的圖像。
selected_hover
當按鈕被選中而且得到焦點狀態時,使用在按鈕上的圖像。
action
當按鈕被啟動時運行的行為。當 sensitiveselected 特性沒有提供的情況下, action 特性也控制那兩種特性表現。
alternate
使用轉化過的辦法在按鈕啟動後運行的行為。當用戶在基於滑鼠的平台上那個點擊滑鼠右鍵,或者用戶在基於觸控的平台上長按某個按鈕,都會觸發。
hovered
當按鈕獲取焦點時運行的行為。
unhovered
當按鈕失去焦點時運行的行為。
selected
決定按鈕是否被選擇的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被選擇。
sensitive
決定按鈕是否被啟用的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被啟用。
keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的行為。
alternate_keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的變換行為。

它還可以使用下列特性:

圖片按鈕沒有子組件。

screen gui_game_menu():
     vbox xalign 1.0 yalign 1.0:
          imagebutton auto "save_%s.png" action ShowMenu('save')
          imagebutton auto "prefs_%s.png" action ShowMenu('preferences')
          imagebutton auto "skip_%s.png" action Skip()
          imagebutton auto "afm_%s.png" action Preference("auto-forward mode", "toggle")

輸入框(input) link

創建一個文本輸入區域,允許用戶輸入文本。當用戶按下確認鍵,輸入的文本會通過交互行為返回。(如果界面是通過 call screen 喚起的,輸入結果會存放在 _return 變數中。)

input語句不接受參數,可以跟下列特性:

value

此次輸入使用的 input value 對象。輸入值對象決定了以下情況的默認處理方式:預設值從哪裡獲取,文本改變時會發生什麼事,用戶輸入回車後會發生什麼事,以及文本是否可編輯。

value 應跟 defaultchanged 在相同的時間點給定。

default
在輸入框中的默認文本。
length
輸入框中允許的最大文本長度。
pixel_width
輸入框最大像素寬度。如果輸入一個字元會導致輸入超出這個寬度,按鍵(keypress)事件消息就會被忽略。
allow
包含所有允許輸入字元的字串。(默認情況下允許輸入任何字元。)
exclude
包含不允許輸入字元的字串。(默認情況下為空“{}”。)
copypaste
若為True,可以在這個輸入欄中啟用複製黏貼功能。(預設禁用。)
prefix
一個不可變的字串,自動添加在用戶輸入前面。
suffix
一個不可變的字串,自動添加在用戶輸入後面。
changed
當用於輸入字串改變時,使用輸入字串調用的一個Python函數。

輸入框還使用下列特性:

輸入框不包含子組件。

screen input_screen():
    window:
        has vbox

        text "Enter your name."
        input default "Joseph P. Blow, ESQ."

key語句 link

key語句創建一個鍵盤按鍵綁定,可以通過按鍵運行某個行為。key語句的應用場景比較寬泛,可以支持手把和滑鼠事件。

key語句有一個固定位置參數,一個需要綁定的按鍵名字串。詳見 訂製按鍵映射 。key語句使用一個特性:

action
這個特性給定了按鍵(keypress)事件發生後觸發的行為。該特性必須存在。

key不包含子組件。

screen keymap_screen():
    key "game_menu" action ShowMenu('save')
    key "p" action ShowMenu('preferences')
    key "s" action Screenshot()

腳本標籤(label) link

使用腳本標籤(label)樣式創建一個窗口(window),並且將文本內容放置在窗口內。這種聯合體用於在某個框架(frame)中將某些元素標籤化。

label語句包含一個固定位置參數,即標籤的文本。其使用下列特性:

text_style
用於按鈕文本的樣式名。如果未提供並且樣式特性是一個字串的話, "_text" 會自動添加到字串後面作為預設的文本樣式。
text_-
其他有 text 前綴的特性會把前綴去掉,然後傳給文本組件(text displayable)。

label語句還可以使用以下特性:

label語句不包含任何子組件。

screen display_preference():
    frame:
        has vbox

        label "Display"
        textbutton "Fullscreen" action Preference("display", "fullscreen")
        textbutton "Window" action Preference("display", "window")

null link

null語句在界面中插入了一塊空的區域。其可以用於物體分隔開。null語句不包含參數,可以使用下列特性:

width
空區域的寬度,單位是像素。
height
空區域的高度,單位是像素。

null語句可以使用以下樣式:

null語句不包含子組件:

screen text_box():
    vbox:
         text "The title."
         null height 20
         text "This body text."

mousearea link

mousearea是界面上劃出一塊區域,用於檢測滑鼠的進入或離開。與按鈕(button)不同的是,滑鼠區域不能獲得焦點,所以在按鈕內部可以存在一塊滑鼠區域。mousearea語句不接受參數,可以使用下列特性:

hovered
當滑鼠進入滑鼠區域時運行的行為。
unhovered
當滑鼠離開滑鼠區域時運行的行為。
focus_mask
focus_mask 樣式特性,可以是某個可視組件或者None。如果是一個可視組件,滑鼠區域值應只放在可視組件不透明的部分上面。(那個可視組件不會展示給用戶。)

mousearea語句使用下列特性:

mousearea語句不含子組件。

通常來說,mousearea語句會給定區域樣式特性,控制滑鼠區域的大小和坐標。如果不控制滑鼠區域大小,就會自動占用整個界面,那種行為的用處比較小。

Note

由於Ren’Py遊戲可以使用鍵盤和手把,所以復用滑鼠區域功能就往往有其他的意義。

screen button_overlay():
    mousearea:
        area (0, 0, 1.0, 100)
        hovered Show("buttons", transition=dissolve)
        unhovered Hide("buttons", transition=dissolve)

screen buttons():
    hbox:
        textbutton "Save" action ShowMenu("save")
        textbutton "Prefs" action ShowMenu("preferences")
        textbutton "Skip" action Skip()
        textbutton "Auto" action Preference("auto-forward", "toggle")

label start:
    show screen button_overlay

side link

side語句把可視組件放置在一個網格的角落或者中間。其使用一個字串型參數,字串內包含空格樣式的位置訊息列表,用於配置子組件。列表中的每個元素都應該是下列字串之一:

‘c’, ‘t’, ‘b’, ‘l’, ‘r’, ‘tl’, ‘tr’, ‘bl’, ‘br’

‘c’表示中間,’t’表示上部,’tl’表示左上,’br’表示右下,以此類推。

side語句使用下列的特性:

spacing
網格中各行和各列之間的間隔。

side語句還可以使用如下特性:

當渲染時,先渲染四角,然後是四邊,最後是中間。四角和四邊在渲染階段的初始可用區域是0,所以有必要提供一個最小尺寸(使用 xminimumyminimum),以確保渲染成功。

添加子組件的順序(或者使用入參的子字串順序)控制顯示順序,最後添加的顯示在最上層。 可以通過配置項 config.keep_side_render_order 禁用。

使用各子組件時分別占據網格單元列表中的一個位置,所以網格單元應與子組件數量相同。

screen side_test():
     side "c tl br":
          text "Center"
          text "Top-Left"
          text "Bottom-Right"

text link

text語句會顯示文本。其使用一個參數,就是用於顯示的文本內容。其也使用下列特性:

text語句沒有子組件。

screen hello_world():
    text "Hello, World." size 40

textbutton link

創建一個包含腳本標籤(label)的按鈕。按鈕使用一個參數,即按鈕內顯示的文本內容。其可以使用下列特性:

action
當按鈕被啟動時運行的行為。當 sensitiveselected 特性沒有提供的情況下, action 特性也控制那兩種特性表現。
alternate
使用轉化過的辦法在按鈕啟動後運行的行為。當用戶在基於滑鼠的平台上那個點擊滑鼠右鍵,或者用戶在基於觸控的平台上長按某個按鈕,都會觸發。
hovered
當按鈕獲取焦點時運行的行為。
unhovered
當按鈕失去焦點時運行的行為。
selected
決定按鈕是否被選擇的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被選擇。
sensitive
決定按鈕是否被啟用的表達式。每次交互行為時,該表達式都至少會被計算一次。如果該特性沒有提供,用戶行為會最終決定按鈕是否被啟用。
keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的行為。
alternate_keysym
給定了一個 keysym 的字串。字串描述了鍵盤對應的按鍵,當那個按鍵被按下後,會調用按鈕的變換行為。
text_style
用於按鈕文本的樣式名。如果未提供並且樣式特性是一個字串的話, "_text" 會自動添加到字串後面作為預設的文本樣式。
text_-
其他有 text 前綴的特性會把前綴去掉,然後傳給文本組件(text displayable)。

textbutton還可以使用如下特性:

其不包含子組件。

screen textbutton_screen():
    vbox:
        textbutton "Wine" action Jump("wine")
        textbutton "Women" action Jump("women")
        textbutton "Song" action Jump("song")

timer link

timer語句會創建一個計時器,當預訂的時間結束後運行某個行為。其使用一個固定位置參數,給出計時的時間值,單位為秒。timer語句使用下列特性:

action
計時結束後會運行的行為。這項特性是必須存在的。
repeat
若為True,計時結束後重設時間並重新開始計時。

timer不包含子組件。

screen timer_test():
    vbox:
         textbutton "Yes." action Jump("yes")
         textbutton "No." action Jump("no")

    timer 3.0 action Jump("too_slow")

transform link

將一個transform應用於其子組件。transform沒有參數,可以使用下列特性:

transform下有一個子組件。

vbar link

等效於原生垂直的 bar 。 使用特性與條 bar 一樣。

screen volume_controls():
     frame:
         has hbox

         vbar value Preference("sound volume")
         vbar value Preference("music volume")
         vbar value Preference("voice volume")

vbox link

縱向排列子組件的不可是垂直方框(box)。vbox不接受參數,可以使用下列特性:

UI可視組件作為子組件添加到vbox:

screen vbox_test():
    vbox:
         text "Top."
         text "Bottom."

viewport link

視口(viewport)是界面中的某塊區域,可以使用滑鼠滾輪或者滾動條進行滾動。視口可以用於顯示某些比界面更大的東西。其使用以下特性:

child_size
待渲染子組件的尺寸,是一個 (xsize, ysize) 形式的元組。該值通常是省略的,子組件可以自己計算尺寸。如果所有組件的尺寸特性都為空,則使用子組件的尺寸訊息。
mousewheel

該值可以是下列之一:

False
忽略滑鼠滾輪。(預設值。)
True
垂直滾動。
“horizontal”
水平滾動。
“change”
垂直滾動視口,只有使用change操作才能觸發視口移動。如果change為空,滑鼠滾輪時間會傳給其他用戶介面。(例如,如果給定change的值,並在viewport語句之前放了 key "viewport_wheeldown" action Return() ,當視口滾動到底部時就會觸發界面返回。)
“horizontal-change”
與change模式一同使用,決定水平滾動的情況。
draggable
若為True,滑鼠拖動就能滾動視口。
edgescroll

當滑鼠到達視口邊緣時,控制滾動行為。若該值非空,應該是一個2元或者3元的元組。

  • 元組內第一個元素是從視口邊緣到edgescroll開始生效處的距離,單位是像素。
  • 元組內第二個元素是滾動率最大值,單位是像素每秒。
  • 如果元組內存在第三個元素,它是一個調整滾動速度的函數,取決於滑鼠指針與界面邊緣的距離。函數入參為一個介於-1.0和1.0之間的數值,返回一個同樣區間內的數值。函數預設值與輸入相同,且按比例進行滾動。函數返回值是-1.0還是1.0,取決於輸入值的符號,並實現勻速滾動。
xadjustment
ui.adjustment() 對象,用作視口x軸的調整。當該特性省略時,就會創建一個新的adjustment對象。
yadjustment
ui.adjustment() 對象,用作視口y軸的調整。當該特性省略時,就會創建一個新的adjustment對象。
xinitial
視口初始水平偏移量。其可以是一個整數,表示像質數;也可以是一個浮點數,表示一個可能的偏移比例。
yinitial
視口初始垂直偏移量。其可以是一個整數,表示像質數;也可以是一個浮點數,表示一個可能的偏移比例。
scrollbars

若不為None,滾動條會添加到視口上。scrollbar會創建一個單邊布局(layout),並把視口放在單邊的中間。如果 scrollbars 的值是 “horizontal”,就在視口上創建一個水平的滾動條。如果 scrollbars 的值是 “vertical”,就在視口上創建一個垂直的滾動條。如果 scrollbars 的值是 “both”,水平和垂直滾動條都會被創建。

scrollbars 不為None,視口會使用前綴為 “side”. 的特性。這些特性會傳給創建的單邊布局(layout)。

arrowkeys
若為True,視口可以使用上下左右方向鍵進行滾動。這種情況下方向鍵的作用優先於方向鍵的其他功能。當視口到達限制時,方向鍵會改變焦點。
pagekeys
若為True,視口可以使用翻頁鍵向上和向下滾動。這會讓翻頁鍵原本的功能失效。原本的功能是回滾和前進。

除此之外,視口還使用以下特性。

視口含有一個子組件。如果實際上提供的子組件並非一個,那就會創建一個固定位置布局容納所有子組件。

想讓一個視口可滾動,最好的辦法通常是聲明一個視口id,然後使用 XScrollValue()YScrollValue()

screen viewport_example():
    side "c b r":
         area (100, 100, 600, 400)

         viewport id "vp":
             draggable True

             add "washington.jpg"

         bar value XScrollValue("vp")
         vbar value YScrollValue("vp")

vpgrid link

vpgrid(viewport grid)將視口與網格(grid)結合為單個的可視組件。vpgrid(像grid一般)包含多個子組件,並且經過最佳化使得視口內只有可以顯示的子組件才會被渲染。

vpgrid假設是由子組件都是相同尺寸,該尺寸來源於第一個子組件。若某個vpgrid渲染結果不正確,請檢查並確保所有子組件的尺寸是相同的。

vpgrid必須至少給定 colsrows 特性。如果有其中之一省略或者是None,另一個特性就會根據子組件的尺寸、空間和數量自動決定。如果沒有足夠的子組件填充所有網格單元,就會渲染為空的網格單元。

vpgrid使用下列特性:

cols
網格(grid)的行數。
rows
網格(grid)的列數。
transpose
若為True,單位網格按列填充。該特性的預設值取決於 colsrows 的特性。如果 cols 出現,單元網格會先按列填充,否則按行填充。

除此之外,vpgrid使用所有 視口 可使用的特性,以及下列特性:

screen vpgrid_test():

    vpgrid:

        cols 2
        spacing 5
        draggable True
        mousewheel True

        scrollbars "vertical"

        # 由於我們有scrollbar,所以我們必須設置“邊”的位置,而不需要設置vpgrid。
        side_xalign 0.5

        for i in range(1, 100):

            textbutton "Button [i]":
                xysize (200, 50)
                action Return(i)

window link

window是個包含背景的窗口,用於顯示遊戲內對話。其使用下列特性:

window含有一個子組件。如果實際上提供的子組件並非一個,那就會創建一個固定位置布局容納所有子組件。

screen say(who, what):
    window id "window"
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

imagemap語句 link

創建界面的簡易方法,特別是對於那些想要創建可視化imagemap的人。當創建一個imagemap時,imagemap語句用於指定六個圖像。hotspot和hotbar用於從整個圖像中分割出矩形區域,並為那些區域添加行為和值。

這是一個preferences界面使用imagemap的樣例:

screen preferences():

    tag menu
    use navigation

    imagemap:
        auto "gui_set/gui_prefs_%s.png"

        hotspot (740, 232, 75, 73) action Preference("display", "fullscreen") alt _("Display Fullscreen")
        hotspot (832, 232, 75, 73) action Preference("display", "window") alt _("Display Window")
        hotspot (1074, 232, 75, 73) action Preference("transitions", "all") alt _("Transitions All")
        hotspot (1166, 232, 75, 73) action  Preference("transitions", "none") alt _("Transitions None")

        hotbar (736, 415, 161, 20) value Preference("music volume") alt _("Music Volume")
        hotbar (1070, 415, 161, 20) value Preference("sound volume") alt _("Sound Volume")
        hotbar (667, 535, 161, 20) value Preference("voice volume") alt _("Voice Volume")
        hotbar (1001, 535, 161, 20) value Preference("text speed") alt _("Text Speed")

imagemap link

imagemap語句用於指定一個imagemap。其不接受參數,後面跟下列特性:

auto

自動定義imagemap使用的圖像。圖像名是一個字串,包含“%s”。如果文件存在,且某個圖像特性是省略的,“%s”會使用對應特性名替換,其值作為特性的預設值。

例如,如果 auto 後面的字串是 “imagemap_%s.png”,且 idle 省略,idle的預設值就是 “imagemap_idle.png”。如果 auto 後面的字串是 “imagemap %s”就使用 imagemap idle 圖像。

auto 的行為可以修改 config.imagemap_auto_function 實現訂製化。

ground
用於imagemap的背景圖像,即不是hotspot也不是hotbar。
insensitive
當hotspot或者hotbar不啟用時使用的圖像。
idle
當hotspot沒有被選中且沒有獲得焦點時使用的圖像,也用於沒有獲得焦點hotbar空的部分。
hover
當hotspot沒有被選中但獲得焦點時使用的圖像,也用於獲得焦點hotbar空的部分。
selected_idle
當hotspot被選中但沒有獲得焦點時使用的圖像,也用於沒有獲得焦點hotbar滿的部分。
selected_hover
當hotspot被選中且獲得焦點時使用的圖像,也用於獲得焦點hotbar滿的部分。
alpha
若為True,也就是預設值,只有當滑鼠懸停在不透明圖像上方時,hotspot才會獲得焦點。若為False,無論滑鼠是否在imagemap矩形區域中,hotspot都會獲得焦點。
cache
若為True,也就是預設值,hotspot數據會快取,用於提升應用性能,代價是會消耗額外的磁碟空間。

imagemap使用下列特性:

imagemap會創建一個固定位置布局,允許任意子組件被添加到那個布局(不僅限於hotspot和hotbar)。

hotspot link

hotspot是由imagemap內一部分圖像組成的按鈕。其使用一個參數,一個(x, y, width, height)形式的元組,給定了imagemap內組成按鈕的區域。其也使用下列特性:

action
當button啟動時運行的行為。這也可用於控制按鈕啟用狀態下,被選中時的行為。
alternate
當hotspot使用變換方法啟動時運行的行為。變換啟動發生在兩種情況下,基於滑鼠平台時用戶點擊滑鼠右鍵,基於觸控平台時用戶長按。
hovered
當按鈕獲得焦點時運行的行為。
unhovered
當按鈕失去焦點時運行的行為。
selected
一個決定按鈕是否被選中的表達式。每次交互行為,這個表達式都會至少被計算一次。如果沒有提供表達式,這個行為會用於決定按鈕被選中。
sensitive
一個決定按鈕是否被啟用的表達式。每次交互行為,這個表達式都會至少被計算一次。如果沒有提供表達式,這個行為會用於決定按鈕啟用。
keysym
給出一個 keysym ,當對應鍵盤的按鍵被按下後,調用對應的按鍵行為。
alternate_keysym
給出一個 keysym ,當對應鍵盤的按鍵被按下後,調用對應的變換按鍵行為。

hotspot使用下列特性:

hotspot會創建一個固定位置布局,允許子組件被添加到那個布局。固定位置布局有一個與hotspot尺寸大小相同的區域,這意味著所有子組件都會根據hotspot放置。

hotspot可以被賦予 alt 樣式特性,允許Ren’Py的自動語音特性能工作。

hotbar link

hotbar是由imagemap內一部分圖像組成的條(bar)。其使用一個參數,一個(x, y, width, height)形式的元組,給定了imagemap內組成條(bar)的區域。其也使用下列特性:

value
條(bar)的當前值。可以是一個 條(bar)值 對象,也可以是一個數值。
range
條(bar)的最大值。當 value 是一個數值的情況下,range 是必須的。
adjustment
一個用於該條(bar)調整的 ui.adjustment() 對象。

hotbar必須給定一個 value 或者一個 adjustment 對象。除此之外,還可以使用下列特性:

hotbar沒有子組件。

hotbar可以被賦予 alt 樣式特性,允許Ren’Py的自動語音特性能工作。

高級可視組件 link

除了以上常用語句,界面語言還有一些語句針對高級可視組件。從可視組件到具體語句的映射是簡單的。可視組件的固定位置參數可以直接用作語句的固定位置參數。可視組件的關鍵字參數和等效樣式特性可轉為界面語言特性。

高級可視組件語句包括:

drag
創建一個 Drag 對象。drag對象可以給定一個可選的子組件,或者可以用於這個子組件的 child 樣式特性,以及子組件獲得變相獲得焦點的行為。drag也能使用 focus_mask 樣式特性。
draggroup
創建一個 DragGroup 組。drag組可以有任意個drag作為其子組件。

has語句 link

has語句允許你指定一個容器用於容納單個子組件,而不使用固定網格(fixed)。has語句只能用在語句內部包含一個子組件的情況。關鍵字 has 後面(同一個邏輯行)會接另一個語句,那個語句會創建一個包含多個子組件的容器型可視組件。

has語句改變了包含它的語句塊(block)的處理方式。在語句塊(block)中創建為子組件的可視組件會被添加到容器中,而不是父組件中。父組件的關鍵字參數不允許出現在has語句後面。在一個語句塊(block)中可以使用多個has語句。

has語句可以使用下列語句創建的子組件:

  • button
  • frame
  • window

has語句可以使用下列語句創建的容器:

  • fixed
  • grid
  • hbox
  • side
  • vbox
screen volume_controls():
     frame:
         has vbox

         bar value Preference("sound volume")
         bar value Preference("music volume")
         bar value Preference("voice volume")

控制語句 link

界面語言包括了各種控制語句,用於條件執行、循環、包含其他界面、事件消息觸發行為和執行任意的Python語句。

default link

default 語句在第一個界面設置某個變數的預設值。SetScreenVariable()

某個變數不會作為該界面的入參或者需要我們使用use語句繼承自某個界面的情況下,default語句設置變數的預設值。

screen scheduler():
    default club = None
    vbox:
         text "What would you like to do?"
         textbutton "Art Club" action SetScreenVariable("club", "art")
         textbutton "Writing Club" action SetScreenVariable("club", "writing")

         if club:
             textbutton "Select" action Return(club)

for link

for 語句類似於Python中的 for 語句,差別在於這裡的for語句不支持 else 分句。for語句支持使用數組型表達式,效果與使用變數一樣。

$ numerals = [ 'I', 'II', 'III', 'IV', 'V' ]

screen five_buttons():
    vbox:
        for i, numeral in enumerate(numerals):
            textbutton numeral action Return(i + 1)

for語句支持index子句:

screen five_buttons():
    vbox:
        for i, numeral index numeral in enumerate(numerals):
            textbutton numeral action Return(i + 1)

如果有 index 分句,應該包含返回一個可排列且可比較的值的表達式,對列表中的每一行都是唯一的。 Ren’Py 使用這個值來確保變換和其他狀態與正確的疊代相關聯。 如果在元素添加到正在疊代的列表中或從中刪除元素時看到奇怪的表現,則可能需要使用index子句。

if link

界面語言 if 語句與Python/Ren’Py的 if 語句相同。其支持 ifelifelse 分句。

screen skipping_indicator():
    if config.skipping:
         text "Skipping."
    else:
         text "Not Skipping."

on link

on 語句允許某個事件消息發生時,界面執行某個行為。其使用一個參數,即事件消息名的字串。事件名包括:

  • "show"
  • "hide"
  • "replace"
  • "replaced"

on語句使用 一個action特性,給定了事件發生時運行的行為。

screen preferences():
    frame:
        has hbox

        text "Display"
        textbutton "Fullscreen" action Preferences("display", "fullscreen")
        textbutton "Window" action Preferences("display", "window")

    on "show" action Show("navigation")
    on "hide" action Hide("navigation")

use link

use 語句允許一個界面包含另一個界面。其使用待use的界面名作為參數,也可以使用圓括號內的一個參數列表。

如果被use語句使用的界面包含參數,入參聲明後時會初始化為參數的值。另外,當前界面傳入的參數,會更新相同關鍵字參數的值。

screen file_slot(slot):
    button:
        action FileAction(slot)

        has hbox

        add FileScreenshot(slot)
        vbox:
            text FileTime(slot, empty="Empty Slot.")
            text FileSaveName(slot)


 screen save():
     grid 2 5:
         for i in range(1, 11):
              use file_slot(i)

use語句可能使用一個特性, id,可能出現在參數列表之後。僅當兩個帶有相同標籤(tag)的界面需要使用同一個界面的情況下才有用。那時,如果其中一個界面替換為另一個界面,使用界面的狀態會從old變為new。

transform t1():
    xpos 150
    linear 1.0 xpos 0

screen common():
    text "Test" at t1

screen s1():
    tag s
    use common id "common"
    text "s1" ypos 100

screen s2():
    tag s
    use common id "common"
    text "s2" ypos 100

label start:
    show screen s1
    pause
    show screen s2
    pause
    return

除了直接使用界面的名稱,還可以使用關鍵字 expression 然後接一個表達式描述使用的界面名稱。 如果需要傳入參數,必須使用 pass 關鍵字分割在表達式內分割參數。

screen ed(num):
    text "Ed"
    text "Captain"

screen kelly(num):
    text "Kelly"
    text "First Officer"

screen bortus(num):
    text "Bortus"
    text "Second Officer"

screen crew():
    hbox:
        for i, member in enumerate(party):
            vbox:
                use member.screen pass (i+1)

use和transclude語句 link

use語句也可以包含一個界面語言的語句塊(block),語句塊中可能存在 transclude 語句。 transclude 語句會被替換為use語句塊內容。

這就可以定義可復用的界面布局(layout)。例如,界面:

screen movable_frame(pos):
    drag:
        pos pos

        frame:
            background Frame("movable_frame.png", 10, 10)
            top_padding 20

            transclude

就意味著一個可復用的組件,可以warp其他組件。這是一個如何復用的樣例:

screen test:
    use movable_frame((0, 0)):
        text "你可以拖拽我。"

    use movable_frame((0, 100)):
        vbox:
            text "你也可以拖拽我。"
            textbutton "搞定!" action Return(True)

use和transclude結構是 創作者定義的界面語言語句 的基礎。

Python link

界面語言也可以包含單行和多行的Python語句。Python語句在對應界面的作用域範圍內運行。

Python禁止在界面之外引發可視的副作用。 Ren’Py在必要的情況下會多次運行某個界面。圖像會在界面正式顯示之前先預載入。因此,如果界面有副作用,在預載入階段就會出現。

screen python_screen:
    python:
        test_name = "Test %d" % test_number

    text test_name

    $ test_label = "test_%d" % test_label

    textbutton "Run Test" action Jump(test_label)

showif語句 link

showif 語句含有一個條件判斷。只有當條件為True時,其子組件會顯示;條件為False時,子組件隱藏。當showif的子組件含有transform時,其會向子組件提供ATL事件,用於管理子組件的顯示和隱藏。Ren’Py也可以據此實現顯示和隱藏的序列化。

showif 語句將它的子組件裝進一個可視組件並管理顯示和隱藏過程。

多個showif語句可以組成一個 showif / elif / else 結構體,類似於一個if語句。 與if語句不同之處在於,showif執行其下所有的語句塊(block),包括Python語句,儘管某些條件結果是False。 這是由於showif語句需要先創建子組件然後再隱藏子組件。

showif語句會向其子組件傳送三種事件消息:

appear
若條件判斷為True,首先顯示界面時,會傳送並立刻顯示子組件。
show
當條件判斷由False變為True時,會傳送給子組件。
hide
當條件判斷由True變為False時,會傳送給子組件。

基於這些需求,當if的主條件判斷為True時 elif 語句的條件判斷分句總是為False,而else分句只有當所有主要條件判斷都為False時才會為True。

舉例:

transform cd_transform:
    # 這句會在appear、show或hide之前運行
    xalign 0.5 yalign 0.5 alpha 0.0

    on appear:
        alpha 1.0
    on show:
        zoom .75
        linear .25 zoom 1.0 alpha 1.0
    on hide:
        linear .25 zoom 1.25 alpha 0.0

screen countdown():
    default n = 3

    vbox:
        textbutton "3" action SetScreenVariable("n", 3)
        textbutton "2" action SetScreenVariable("n", 2)
        textbutton "1" action SetScreenVariable("n", 1)
        textbutton "0" action SetScreenVariable("n", 0)

    showif n == 3:
        text "Three" size 100 at cd_transform
    elif n == 2:
        text "Two" size 100 at cd_transform
    elif n == 1:
        text "One" size 100 at cd_transform
    else:
        text "Liftoff!" size 100 at cd_transform

label start:
    call screen countdown

screen語句 link

除了screen語句,還有三種Ren’Py腳本語言語句可以喚起界面。

其中兩種使用一個關鍵字入參列表。這個列表是Python入參列表,使用圓括號,只由關鍵字參數組成。固定位置參數,額外的固定位置參數 (*),以及額外的關鍵字參數 (**) 都不允許存在。

show screen link

show screen 語句會觸發某個界面的顯示。其使用一個界面名作為參數,後面還有一個可選的Pythone入參列表。如果入參列表出現,這些參數用作初始化界面作用域(scope)內的變數。 還有幾個特殊關鍵字會傳入 show_screen()call_screen() 函數。

show screen語句使用一個可選的 nopredict 關鍵字,以防止界面預載入。當界面預載入時,傳入界面的入參會被計算。請確保作為界面入參的表達式不會引起不希望出現的副作用。

Warning

如果計算入參表達式會引發界面的副作用,你的遊戲可能會出現不希望出現的情況。

使用這種方式的界面會一直顯示,除非有明確的語句隱藏界面。這個設計可以用作界面的互相覆蓋。

show screen overlay_screen
show screen clock_screen(hour=11, minute=30)

if rare_case:
    show rare_screen nopredict

show screen 語句可以使用with分句,語法與 show 語句相同。

show screen clock_screen with dissolve

hide screen link

hide screen 語句用於隱藏當前正在顯示的界面。如果指定的界面並沒有顯示,不會發生任何事。 如果帶有 with 分句,則與show語句的語法相同。

hide screen rare_screen
hide screen clock_screen with dissolve
hide screen overlay_screen
hide screen clock

call screen link

call screen 語句會顯示一個界面,在當前互動行為之後會隱藏這個界面。如果界面會返回一個值,返回值會放在 _return 中。

這可以用來顯示一個imagemap。imagemap可以使用 Return() 行為將一個值放入 _return 變數,或者使用 Jump() 行為跳轉到某個腳本標籤(label)。

call screen語句使用一個可選的 nopredict 關鍵字,以防止界面前綴出現。當界面含有前綴時,傳入界面的入參會被計算。請確保作為界面入參的表達式不會引起不希望出現的副作用。

call screen語句使用一個可選的 with 關鍵字,後面跟一個轉場(transition)。界面首次顯示的時候會使用轉場(transition)效果。當界面顯示轉場效果之後,再跟一個with語句和轉場效果,就是界面隱藏使用的轉場。

Warning

如果評估螢幕上的參數會導致副作用發生,你的遊戲可能會出現不希望出現的情況。

call screen my_imagemap

call screen my_screen(side_effect_function()) nopredict

# 使用dissolve轉場顯示界面,使用fade轉場隱藏界面。
call screen my_other_screen with dissolve
with fade

界面變種 link

Ren’Py可以同時執行在兩種平台上:一種是傳統的鍵鼠設備平台,比如Windows系統、Mac系統和Linux PC版;另一種是新的觸控設備平台,比如基於安卓系統的智慧型手機和平板。界面變種允許一個遊戲根據不同的硬體訊息提供不同版本的界面。

Ren’Py通過順序搜索 config.variants 中的variant項來選擇使用何種界面,並使用找到第一個variant。

如果環境變數 RENPY_VARIANT存在,config.variants就會使用RENPY_VARIANT中用空格分隔的各項值進行初始化。將RENPY_VARIANT設置為針對安卓設備的 "medium tablet touch""small phone touch" ,就可以在PC端調測了。

如果環境變數不存在,變種列表會自動建立。建立時,會按順序搜索下表,找到匹配項後選擇對應平台的入口。

"large"
螢幕足夠大,字體小的文本也能輕鬆閱讀,按鈕可以被很容易點中。這主要用於電腦螢幕。
"medium"
螢幕不大,比較小的字體可以閱讀,但按鈕可能需要增大尺寸才能被比較舒服地按下。這用於平板。
"small"
螢幕比較小,文本必須放大才能閱讀。這用於手機和電視機。(電視機螢幕雖然比較大,但使用時距離用戶較遠,不利於閱讀文本。)
"tablet"
不小於6英寸的觸控屏設備。(大多數情況下, "medium" 應代替 "tablet" 。)
"phone"
小於6英寸的觸控屏設備。在這樣小的設備上,將按鈕做得足夠大才能讓用戶輕鬆選中。(大多數情況下, "small" 應代替 "phone" 。)
"touch"
觸控屏設備。
"tv"
電視機設備。
"ouya"
OUYA主機。(表示同時為 "tv""small")
"firetv"
亞馬遜的Fire TV主機。(表示同時為 "tv""small")
"android"
安卓設備。
"ios"
iOS設備,像iPad(表示同時為 "tablet""medium")和iPhone(表示同時為 "phone""small")。
"mobile"
手機平台,比如安卓、iOS手機和手機web瀏覽器。
"pc"
Windows、Mac OS X和Linux平台。PC表示會有鍵鼠設備,允許滑鼠懸停(hover)狀態和精確點擊。
"web"
在web瀏覽器上運行。
None
默認定義。

定義一個界面變種的樣例如下:

# 一個變種的hello_world界面,使用小型觸控螢幕設備。
screen hello_world():
     tag example
     zorder 1
     modal False
     variant "small"

     text "Hello, World." size 30