用戶在Ren’Py遊戲中所有的可見元素可以分為圖像和用戶介面兩大類。圖像通過scene、show和hide語句向用戶展示,也是故事敘述的大頭。其他所有可見的元素都屬於用戶介面。用戶介面可以通過界面實現訂製化。
界面有下列4種方式顯示:
可以一次顯示多個界面。
界面有兩個主要功能。第一個是向用戶顯示訊息。訊息的顯示可以使用文本、條(bar)和圖像(image)。使用這種方法顯示某些訊息是遊戲的需要。例如, say 界面用於向用戶顯示對話,包括說話人的名字和說話內容。
界面的另一個功能是允許用戶與遊戲交互。按鈕和條(bar)允許用戶觸發某些行為(action)和調整數值。Ren’Py包含一個預定義行為的池,允許用戶快進、個性化控制、讀檔和存檔等。創作者還可以使用Python編寫新的行為。
每次交互行為的啟動或重啟,都會更新界面。
界面的改變不應該引發界面之外可視區域的副作用。 Ren’Py會根據需要多次運行同一個界面。Ren’Py會在界面顯示之前運行一些運行圖像預載入進程。因此,如果界面有副作用,在預載入階段就會發生。
每個界面有一個作用範圍(scope)與其關聯,並有一些給定的變數值。如果某些界面中包含變數,首先在界面的作用範圍(scope)內查找變數,然後再查找全局變數。
界面語言是顯示界面最正式的辦法。它包含定義新界面的語句、添加可視組件至界面的語句和控制型語句。
這是一個界面的樣例:
screen say(who, what):
window id "window":
vbox:
spacing 10
text who id "who"
text what id "what"
這段腳本的第一行是一個screen語句。Ren’Py中使用screen語句定義一個界面。界面的名字是 say,所以該界面用於顯示對話。其有兩個入參,分別是 who 和 what。
界面包含一個窗口,窗口id就叫“window”。窗口中包含一個垂直的框(box),框內的空間為10個像素。它包含兩個文本欄位(field),一個是發言者的名字,另一個是發言者的id。
大多數界面語言語句使用通用的語法。(某些控制語句使用其他語法。)語句的開頭以某個關鍵字進入。
如果語句使用參數,參數就跟著開頭的關鍵字後面。參數列表是使用空格分隔的簡單表達式,除非有特殊情況。
固定位置參數後面會跟一個特性(property)列表。一個特性包括特性名稱和特性值組成。特性值是簡單表達式,除非有特殊情況。特性列表中各個特性使用空格分隔。
如果某個語句以英文冒號(:)結尾,後面就會跟一個語句塊(block)。語句塊的每一行可能是以下兩者之一:
screen
語句在Ren’Py腳本語言中用於定義一個新的界面。其使用界面語言通用語法。
screen語句使用一個參數,即界面名。界面名不是一個簡單表達式,可以使用以下特性:
screen hello_world():
tag example
zorder 1
modal False
text "Hello, World."
界面可以使用一個參數列表:
screen center_text(s, size=42):
text s size size
用戶介面語句用於創建可視組件並添加至界面或某個封閉的可視組件。它們允許向用戶顯示訊息,用戶與遊戲的互動,以及遊戲中各種事件消息的相互作用。
所有用戶介面語句使用下列通用特性:
一個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就不會接收到事件消息。
用戶介面語句的標識號。當某個界面顯示時,特性值可以透過給定的標識符提供給可視組件。某些界面會根據創建的標識號請求某個可視組件。
默認情況下,這個 id
是自動生成的。
向可視組件及其子組件的樣式提供了一個前綴,例外情況是某些子組件用一個指定的樣式或樣式前綴。
樣式名由樣式前綴、下劃線和樣式後綴組成。樣式後綴通過樣式後綴 style_suffix 或可視組件決定。
例如,如果某個vbox有一個樣式前綴 "pref"
,這個vbox的樣式名就是 "pref_vbox"
。除非設置了某個指定的樣式或者樣式前綴,vbox內的按鈕會用樣式
"pref_button"
。
如果樣式不存在的話,使用這種方式接入的樣式會被自動創建。將前綴設置為 None
會將可視組件及其子組件的所有前綴都移除。
指定後綴,與 style_prefix 連在一起創建一個樣式名。如果後綴是 "small_button"
,前綴是 "pref"
,實用的樣式名就是 "pref_small_button"
。
如果不使用樣式前綴,就是直接使用樣式名。樣式後綴就會只應用於某一個可視組件,而不會用於其子組件。
GetTooltip()
函數。詳見 Tooltips 章節。
傳入工具提示框的對象必須支持相等性(equality)。如果不支持比較相等,可能會導致無限死循環。許多用戶介面語句使用樣式特性類或者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
分句,後面帶一個變數名,不需要引號。
語句創建的可視組件對象將聲明為變數。(在這裡可以找到一個樣例 拖拽組件.)
在界面上添加一個圖像或其他的可視組件。添加時可以選擇使用 transform特性列表。如果至少使用了一項 Transform
特性,用於wrap圖像的transform就會被創建,特性值會賦予這個transform。
如果可視組件為None,那不會有任何東西添加到界面上。
add語句不使用任何子組件。
screen add_test():
add "logo.png" xalign 1.0 yalign 0.0
創建一個原本水平的條(bar),可用於查看和調整數據。其使用以下特性:
ui.adjustment()
對象。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)不接受參數,可以使用下列特性。
它還可以使用下列特性:
按鈕使用一個子組件。如果0個、兩個或者更多子組件被應用,他們全部會自動整合為一個固定布局(fixed),並添加到按鈕上。
fixed創建了一塊用於添加子組件的區域。默認情況下,固定布局(fixed)會擴展並填充整個可用區域,但 xmaximum
和 ymaximum
特性可以改變這點。
子組件們使用自身的位置樣式特性實現布局。如果沒有合適的設置位置,它們可能會重疊。
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)是窗口,該窗口包含一個背景,可用於顯示用戶介面元素,例如按鈕、條(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在一個網格系統中顯示其子組件。每個子組件都會分配相同的區域大小,這個區域大小可以容納最大的子組件。
grid使用兩個參數。第一個參數是網格的行號,第二個參數是網格的列號。其使用下列特性:
其還使用以下特性:
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的各個子組件會邊靠著邊顯示,都在一個不可見的水準方塊(box)內。其不接受參數,後面跟以下特性:
UI可視組件的子組件會被添加到方框(box)中。
screen hbox_text():
hbox:
text "Left"
text "Right"
創建一個包含圖像的按鈕,當指針懸停在按鈕上時,圖像狀態會發生改變。其不接受參數,使用下列特性:
按鈕使用圖片自動定義。這個特性是個包含 %s 的字串。如果某個圖片特性是省略的,%s會被替換為對應特性名稱,並使用對應值作為對應特性的預設值。
例如,如果 auto 是 “button_%s.png”,並且 idle 特性省略,那麼idle的預設值就是 “button_idle.png”。類似的,如果 auto 是“button %s”,那麼 button idle
圖像就會被應用。
auto 特性的具體行為可以修改
config.imagemap_auto_function
實現訂製化。
它還可以使用下列特性:
圖片按鈕沒有子組件。
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")
創建一個文本輸入區域,允許用戶輸入文本。當用戶按下確認鍵,輸入的文本會通過交互行為返回。(如果界面是通過 call screen
喚起的,輸入結果會存放在 _return
變數中。)
input語句不接受參數,可以跟下列特性:
此次輸入使用的 input value 對象。輸入值對象決定了以下情況的默認處理方式:預設值從哪裡獲取,文本改變時會發生什麼事,用戶輸入回車後會發生什麼事,以及文本是否可編輯。
value 應跟 default 和 changed 在相同的時間點給定。
輸入框還使用下列特性:
輸入框不包含子組件。
screen input_screen():
window:
has vbox
text "Enter your name."
input default "Joseph P. Blow, ESQ."
key語句創建一個鍵盤按鍵綁定,可以通過按鍵運行某個行為。key語句的應用場景比較寬泛,可以支持手把和滑鼠事件。
key語句有一個固定位置參數,一個需要綁定的按鍵名字串。詳見 訂製按鍵映射 。key語句使用一個特性:
key不包含子組件。
screen keymap_screen():
key "game_menu" action ShowMenu('save')
key "p" action ShowMenu('preferences')
key "s" action Screenshot()
使用腳本標籤(label)樣式創建一個窗口(window),並且將文本內容放置在窗口內。這種聯合體用於在某個框架(frame)中將某些元素標籤化。
label語句包含一個固定位置參數,即標籤的文本。其使用下列特性:
"_text"
會自動添加到字串後面作為預設的文本樣式。label語句還可以使用以下特性:
label語句不包含任何子組件。
screen display_preference():
frame:
has vbox
label "Display"
textbutton "Fullscreen" action Preference("display", "fullscreen")
textbutton "Window" action Preference("display", "window")
null語句在界面中插入了一塊空的區域。其可以用於物體分隔開。null語句不包含參數,可以使用下列特性:
null語句可以使用以下樣式:
null語句不包含子組件:
screen text_box():
vbox:
text "The title."
null height 20
text "This body text."
mousearea是界面上劃出一塊區域,用於檢測滑鼠的進入或離開。與按鈕(button)不同的是,滑鼠區域不能獲得焦點,所以在按鈕內部可以存在一塊滑鼠區域。mousearea語句不接受參數,可以使用下列特性:
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語句把可視組件放置在一個網格的角落或者中間。其使用一個字串型參數,字串內包含空格樣式的位置訊息列表,用於配置子組件。列表中的每個元素都應該是下列字串之一:
‘c’, ‘t’, ‘b’, ‘l’, ‘r’, ‘tl’, ‘tr’, ‘bl’, ‘br’
‘c’表示中間,’t’表示上部,’tl’表示左上,’br’表示右下,以此類推。
side語句使用下列的特性:
side語句還可以使用如下特性:
當渲染時,先渲染四角,然後是四邊,最後是中間。四角和四邊在渲染階段的初始可用區域是0,所以有必要提供一個最小尺寸(使用
xminimum
或 yminimum
),以確保渲染成功。
添加子組件的順序(或者使用入參的子字串順序)控制顯示順序,最後添加的顯示在最上層。
可以通過配置項 config.keep_side_render_order
禁用。
使用各子組件時分別占據網格單元列表中的一個位置,所以網格單元應與子組件數量相同。
screen side_test():
side "c tl br":
text "Center"
text "Top-Left"
text "Bottom-Right"
text語句會顯示文本。其使用一個參數,就是用於顯示的文本內容。其也使用下列特性:
text語句沒有子組件。
screen hello_world():
text "Hello, World." size 40
創建一個包含腳本標籤(label)的按鈕。按鈕使用一個參數,即按鈕內顯示的文本內容。其可以使用下列特性:
"_text"
會自動添加到字串後面作為預設的文本樣式。textbutton還可以使用如下特性:
其不包含子組件。
screen textbutton_screen():
vbox:
textbutton "Wine" action Jump("wine")
textbutton "Women" action Jump("women")
textbutton "Song" action Jump("song")
timer語句會創建一個計時器,當預訂的時間結束後運行某個行為。其使用一個固定位置參數,給出計時的時間值,單位為秒。timer語句使用下列特性:
timer不包含子組件。
screen timer_test():
vbox:
textbutton "Yes." action Jump("yes")
textbutton "No." action Jump("no")
timer 3.0 action Jump("too_slow")
等效於原生垂直的 bar 。 使用特性與條 bar 一樣。
screen volume_controls():
frame:
has hbox
vbar value Preference("sound volume")
vbar value Preference("music volume")
vbar value Preference("voice volume")
縱向排列子組件的不可是垂直方框(box)。vbox不接受參數,可以使用下列特性:
UI可視組件作為子組件添加到vbox:
screen vbox_test():
vbox:
text "Top."
text "Bottom."
視口(viewport)是界面中的某塊區域,可以使用滑鼠滾輪或者滾動條進行滾動。視口可以用於顯示某些比界面更大的東西。其使用以下特性:
該值可以是下列之一:
key "viewport_wheeldown" action Return()
,當視口滾動到底部時就會觸發界面返回。)當滑鼠到達視口邊緣時,控制滾動行為。若該值非空,應該是一個2元或者3元的元組。
ui.adjustment()
對象,用作視口x軸的調整。當該特性省略時,就會創建一個新的adjustment對象。ui.adjustment()
對象,用作視口y軸的調整。當該特性省略時,就會創建一個新的adjustment對象。若不為None,滾動條會添加到視口上。scrollbar會創建一個單邊布局(layout),並把視口放在單邊的中間。如果 scrollbars 的值是 “horizontal”,就在視口上創建一個水平的滾動條。如果 scrollbars 的值是 “vertical”,就在視口上創建一個垂直的滾動條。如果 scrollbars 的值是 “both”,水平和垂直滾動條都會被創建。
若 scrollbars 不為None,視口會使用前綴為 “side”. 的特性。這些特性會傳給創建的單邊布局(layout)。
除此之外,視口還使用以下特性。
視口含有一個子組件。如果實際上提供的子組件並非一個,那就會創建一個固定位置布局容納所有子組件。
想讓一個視口可滾動,最好的辦法通常是聲明一個視口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(viewport grid)將視口與網格(grid)結合為單個的可視組件。vpgrid(像grid一般)包含多個子組件,並且經過最佳化使得視口內只有可以顯示的子組件才會被渲染。
vpgrid假設是由子組件都是相同尺寸,該尺寸來源於第一個子組件。若某個vpgrid渲染結果不正確,請檢查並確保所有子組件的尺寸是相同的。
vpgrid必須至少給定 cols 和 rows 特性。如果有其中之一省略或者是None,另一個特性就會根據子組件的尺寸、空間和數量自動決定。如果沒有足夠的子組件填充所有網格單元,就會渲染為空的網格單元。
vpgrid使用下列特性:
除此之外,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)
創建界面的簡易方法,特別是對於那些想要創建可視化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語句用於指定一個imagemap。其不接受參數,後面跟下列特性:
自動定義imagemap使用的圖像。圖像名是一個字串,包含“%s”。如果文件存在,且某個圖像特性是省略的,“%s”會使用對應特性名替換,其值作為特性的預設值。
例如,如果 auto 後面的字串是 “imagemap_%s.png”,且 idle 省略,idle的預設值就是 “imagemap_idle.png”。如果 auto 後面的字串是 “imagemap %s”就使用
imagemap idle
圖像。
auto 的行為可以修改
config.imagemap_auto_function
實現訂製化。
imagemap使用下列特性:
imagemap會創建一個固定位置布局,允許任意子組件被添加到那個布局(不僅限於hotspot和hotbar)。
hotspot是由imagemap內一部分圖像組成的按鈕。其使用一個參數,一個(x, y, width, height)形式的元組,給定了imagemap內組成按鈕的區域。其也使用下列特性:
hotspot使用下列特性:
hotspot會創建一個固定位置布局,允許子組件被添加到那個布局。固定位置布局有一個與hotspot尺寸大小相同的區域,這意味著所有子組件都會根據hotspot放置。
hotspot可以被賦予 alt
樣式特性,允許Ren’Py的自動語音特性能工作。
hotbar是由imagemap內一部分圖像組成的條(bar)。其使用一個參數,一個(x, y, width, height)形式的元組,給定了imagemap內組成條(bar)的區域。其也使用下列特性:
ui.adjustment()
對象。hotbar必須給定一個 value 或者一個 adjustment 對象。除此之外,還可以使用下列特性:
hotbar沒有子組件。
hotbar可以被賦予 alt
樣式特性,允許Ren’Py的自動語音特性能工作。
除了以上常用語句,界面語言還有一些語句針對高級可視組件。從可視組件到具體語句的映射是簡單的。可視組件的固定位置參數可以直接用作語句的固定位置參數。可視組件的關鍵字參數和等效樣式特性可轉為界面語言特性。
高級可視組件語句包括:
drag
Drag
對象。drag對象可以給定一個可選的子組件,或者可以用於這個子組件的 child
樣式特性,以及子組件獲得變相獲得焦點的行為。drag也能使用 focus_mask
樣式特性。draggroup
DragGroup
組。drag組可以有任意個drag作為其子組件。has語句允許你指定一個容器用於容納單個子組件,而不使用固定網格(fixed)。has語句只能用在語句內部包含一個子組件的情況。關鍵字 has
後面(同一個邏輯行)會接另一個語句,那個語句會創建一個包含多個子組件的容器型可視組件。
has語句改變了包含它的語句塊(block)的處理方式。在語句塊(block)中創建為子組件的可視組件會被添加到容器中,而不是父組件中。父組件的關鍵字參數不允許出現在has語句後面。在一個語句塊(block)中可以使用多個has語句。
has語句可以使用下列語句創建的子組件:
has語句可以使用下列語句創建的容器:
screen volume_controls():
frame:
has vbox
bar value Preference("sound volume")
bar value Preference("music volume")
bar value Preference("voice volume")
界面語言包括了各種控制語句,用於條件執行、循環、包含其他界面、事件消息觸發行為和執行任意的Python語句。
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
語句類似於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
語句與Python/Ren’Py的 if
語句相同。其支持 if
、elif
和 else
分句。
screen skipping_indicator():
if config.skipping:
text "Skipping."
else:
text "Not Skipping."
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
語句允許一個界面包含另一個界面。其使用待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語句也可以包含一個界面語言的語句塊(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語句。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
語句含有一個條件判斷。只有當條件為True時,其子組件會顯示;條件為False時,子組件隱藏。當showif的子組件含有transform時,其會向子組件提供ATL事件,用於管理子組件的顯示和隱藏。Ren’Py也可以據此實現顯示和隱藏的序列化。
showif
語句將它的子組件裝進一個可視組件並管理顯示和隱藏過程。
多個showif語句可以組成一個 showif
/ elif
/ else
結構體,類似於一個if語句。 與if語句不同之處在於,showif執行其下所有的語句塊(block),包括Python語句,儘管某些條件結果是False。 這是由於showif語句需要先創建子組件然後再隱藏子組件。
showif語句會向其子組件傳送三種事件消息:
appear
show
hide
基於這些需求,當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語句,還有三種Ren’Py腳本語言語句可以喚起界面。
其中兩種使用一個關鍵字入參列表。這個列表是Python入參列表,使用圓括號,只由關鍵字參數組成。固定位置參數,額外的固定位置參數 (*),以及額外的關鍵字參數 (**) 都不允許存在。
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
語句用於隱藏當前正在顯示的界面。如果指定的界面並沒有顯示,不會發生任何事。
如果帶有 with
分句,則與show語句的語法相同。
hide screen rare_screen
hide screen clock_screen with dissolve
hide screen overlay_screen
hide screen clock
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
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"
"medium"
應代替 "tablet"
。)"phone"
"small"
應代替 "phone"
。)"touch"
"tv"
"ouya"
"tv"
和 "small"
)"firetv"
"tv"
和 "small"
)"android"
"ios"
"tablet"
和 "medium"
)和iPhone(表示同時為 "phone"
和 "small"
)。"mobile"
"pc"
"web"
None
定義一個界面變種的樣例如下:
# 一個變種的hello_world界面,使用小型觸控螢幕設備。
screen hello_world():
tag example
zorder 1
modal False
variant "small"
text "Hello, World." size 30