等效語句 link

為了允許Ren’Py能夠在Python中腳本化，每個Ren’Py語句都有一條等效的Python語句。每條等效Python語句通常包含一個Python函數，也可能包含一個Python正則表達式，執行一個等效行為。

注意，在使用原生Python等效語句的地方，往往會移除 Lint 檢查和預載入最佳化，讓遊戲不利於檢查問題並可能運行不那麼流暢。某些情況下會導致部分功能特性不可用。

對話 link

Warning

某些功能特性，比如快速跳過已看過對話，不能使用Python語句，只能使用原生say語句。

Ren’Py的 say語句等效於以一個函數的形式調用角色對象。顯示旁白也使用了同樣的辦法，用的是 narrator 角色。：

e "Hello, world."
$ e("Hello, world.")

"And then the sun exploded."
$ narrator("And then the sun exploded.")

代理函數 link

角色和函數對象的等效語句在其他方面也能正常運行。還可以定義一個Python函數，然後在角色對象的地方使用那個函數。例如，下面定義的函數使用一個變數，在兩個角色中選擇一個。

define lucy_normal = Character("Lucy")
define lucy_evil = Character("Evil Lucy")

init python:

    def l(what, **kwargs):
        if lucy_is_evil:
            lucy_evil(what, **kwargs)
        else:
            lucy_normal(what, **kwargs)

label start:

    $ lucy_is_evil = False

    l "大多數情況下，我都是個普通人。"

    $ lucy_is_evil = True

    l "不過有時候，瘋起來我自己都害怕！"

這種使用函數的方式，要嘛忽略未知的關鍵字入參，要嘛將那些入參傳給某個角色函數。這樣做可以在未來版本的Ren’Py出現新關鍵字入參時，使遊戲依然能運行。

注意，與其他語句不同，interact=True 總是會傳入該函數，除非手工傳入 (interact=False)。帶有參數的say語句章節可以看到傳入參數的情況，例如：

e "Hello, world." (what_size=32)

完全展開的話是：

e("Hello, world.", what_size=32, interact=True)

調用角色對象時不需要顯式傳入 interact=True。下面這種寫法沒有問題：

$ e("Hello, world.", what_size=32)

若e是一個角色對象，還可以進一步等效為：

$ Character(kind=e, what_size=32)("Hello, world.")

但可能需要使用 config.say_arguments_callback 或將 e 扭轉為某個角色對象才能實現其他功能。

還有一種在Python中替代say語句的方法：

renpy.say(who, what, *args, **kwargs) link

say語句的等效語句。

who: None表示旁白，不然是發言角色對象，或表示角色名的字串。最後那種情況， func:say() 函數會創建發言角色。
what: 一行發言內容的字串。字串裡帶百分號(%)的部分會被替換(substitution)。
interact: 若為True，Ren’Py顯示對話並等待用戶輸入。若為False，Ren’Py顯示對話，但不執行互動行為。(互動行為會以關鍵字入參傳入相應的處理函數。)

該函數極少直接使用，因為下面三行語句是完全等效的。

e "Hello, world."
$ renpy.say(e, "Hello, world.")
$ e("Hello, world.")

對話窗口管理 link

通過設置 _window 和 _window_auto 可以實現窗口管理。下面兩個函數也用於對話窗口管理：

_window_hide(trans=False, auto=False) link

window hide 語句的Python等效。

trans: 若為False，使用預設的窗口隱藏轉場。若為None，不使用轉場。否則，使用指定的轉場。
auto: 若為True，此函數等效於 window auto hide 語句。

_window_show(trans=False, auto=False) link

window show 語句的Python等效。

trans: 若為False，使用預設的窗口顯示轉場。若為None，不使用轉場。否則，使用指定的轉場。
auto: 若為True，此函數等效於 window auto show 語句。

選項菜單 link

menu語句有一個等效的Python函數。

menu(items, interact=True, screen='choice') link

該函數向用戶顯示一個菜單。 item 應該是一個二元元組列表。在每個元組中，第一個元素是一個文本標籤(label)，第二個參數是該元素被選中時的返回值。如果返回值是None，第一個元素會用作整個菜單的標題。

該函數使用多個入參，這份文件中只列出了其中一部分。除了 items 之外，所有都是關鍵字入參。

interact: 若為False，顯示菜單，但不執行任何互動行為。
screen: 顯示菜單的界面名。

renpy.display_menu(items, interact=True, screen='choice') link

該函數向用戶顯示一個菜單。 item 應該是一個二元元組列表。在每個元組中，第一個元素是一個文本標籤(label)，第二個參數是該元素被選中時的返回值。如果返回值是None，第一個元素會用作整個菜單的標題。

該函數使用多個入參，這份文件中只列出了其中一部分。除了 items 之外，所有都是關鍵字入參。

interact: 若為False，顯示菜單，但不執行任何互動行為。
screen: 顯示菜單的界面名。

顯示圖像 link

image、scene、show和hide語句都一個等效的Python函數(詳見顯示圖像)。

renpy.get_at_list(name, layer=None) link

將圖層 layer 上圖像標籤名為 tag 的圖像所應用的變換(transform)，以列表形式返回。如果沒有使用任何變換(transform)則返回一個空列表，如果圖像不顯示則返回None。

如果 layer 為None，就是用給定圖像標籤(tag)所在的默認圖層。

renpy.hide(name, layer=None) link

從某個圖層中隱藏某個圖像。hide語句的等效Python語句。

name: 需要隱藏的圖像名稱。只是用圖像標籤(tag)，所有帶相同標籤的圖像都將被隱藏(圖像全名不重要)。
layer: 該函數操作的圖層名。若為None，使用圖像標籤(tag)關聯的默認圖層。

renpy.image(name, d) link

定義一個圖像。該函數是image語句的等效Python語句。

name: 需要顯示的圖像名稱，是一個字串。
d: 與圖像名關聯的可視組件。

該函數可能僅能在init語句塊(block)中運行。遊戲開始後運行該函數會觸發一個報錯。

renpy.scene(layer='master') link

從圖層 layer 移動所有可視組件。當scene語句沒有指定一個需要顯示的圖像時，這是scene語句的等效Python語句。

一個完整的scene語句等效於調用renpy.scene之後再調用 renpy.show() 。舉例：

scene bg beach

等效於：

$ renpy.scene()
$ renpy.show("bg beach")

renpy.show(name, at_list=[], layer='master', what=None, zorder=0, tag=None, behind=[]) link

在某個圖層上顯示某個圖像。這是show語句的等效Python語句。

name: 需要顯示的圖像名稱，是一個字串。
at_list: 應用於圖像的變換(transform)列表。等效於 at 特性(property)。
layer: 一個字串，表示圖像顯示使用的圖層名。等效於 onlayer 特性(property)。若為None，使用圖像標籤(tag)關聯的默認圖層。
what: 若非None，這是一個代替圖像的可視組件。(等效於show表達式語句。)當給定了一個 what 參數時， name 可以用於將圖像與標籤(tag)關聯。
zorder: 一個整數，等效於 zorder 特性(property)。若為None，zorder會保留之前的值，否則設置為0。
tag: 一個字串，用於指定顯示圖像的標籤(tag)。等效於 as 特性(property)。
behind: 一個字串列表，表示需要顯示的圖像在哪些圖像標籤(tag)後面。等效於 behind 特性(property)。

renpy.show_layer_at(at_list, layer='master', reset=True) link

show layer layer at at_list 語句的等效Python語句。

reset: 若為True，當圖層顯示時，變換(transform)狀態會重設為開始狀態。若為False，變換狀態會保持，允許新的變換更新狀態。

轉場 link

with語句等效於 renpy.with_statement() 函數。

renpy.with_statement(trans, always=False) link

觸發一個轉場(transition)。這是with語句的Python等效語句。

trans: 轉場(transition)名。
always: 若為True，在用戶禁用轉場的情況下依然顯示轉場效果。

當用戶中斷轉場時該函數返回True，其他情況返回False。

jump語句 link

jump語句的等效於 renpy.jump() 函數。

renpy.jump(label) link: 結束當前語句，並讓主控流程跳轉到給定的腳本標籤(label)。

call語句 link

call語句的等效於 renpy.call() 函數。

renpy.call(label, *args, **kwargs) link

結束當前Ren’Py語句，並跳轉到 label 處。當jump返回後，主控流程會返回到之前的語句。

from_current: 若為True，主控流程會返回到當前語句，而不是當前語句的下一句。(這會導致當前語句運行兩次。這項必須作為關鍵字入參傳入。)

renpy.return_statement() link: 觸發Ren’Py從當前Ren’Py級別的調用返回。

pause語句 link

pause語句語句等效於 renpy.pause() 函數。

renpy.pause(delay=None, *, hard=False, predict=False, modal=False) link

使Ren’Py暫停。用戶點擊使暫停結束將返回True，暫停超過設定時間或暫停被跳過則返回False。

delay: 指定Ren’Py暫停時間。單位為秒。

下列是關鍵字參數：

hard

必須作為關鍵字參數傳入。該入參為True時，Ren’Py將屏蔽用戶點擊操作，暫停無法被取消。如果用戶啟用了跳過(skipping)，此暫停依然可以跳過。某些情況下hard暫停會提早結束後無法正常屏蔽用戶操作，這些都不是bug。

總體來說，使用hard暫停是魯莽的。當用戶使用點擊推進遊戲時——這算一種明確的需求，用戶希望遊戲劇情可以前進。在用戶需求之上做功能設計的前提是，創作者比用戶自己更了解用戶需求。

調用renpy.pause可以保證界面內容至少顯示1幀，以讓用戶能夠確實看到內容。

總結：盡量不要調用 renpy.pause 時 hard=True。

predict

若為True，Ren’Py會等到所有預載入完成後再暫停。預載入包括使用 renpy.start_predict() 和 renpy.start_predict_screen() 函數的場景。

將該項設置為True時，Ren’Py在暫停期間將優先處理預載入任務，而將圖像平滑顯示的任務放在預載入後面。因為推薦不要在預載入期間播放動畫動效。

modal

若為True或None，顯示某個模態界面將不會結束此次暫停。若為False，顯示某個模態界面將結束此次暫停。

層疊式圖像 link

group語句沒有直接的等效語句：group名稱需要通過 Attribute 類賦值， auto 功能需要使用 renpy.list_images() 函數實現。

class Attribute(group, attribute, image=None, default=False, group_args={}, **kwargs) link

該類用於表示LayeredImage對象中受某個屬性控制的圖層。單個屬性可以控制多個圖層，使這些圖層同時顯示或隱藏。

group: 一個字串，表示屬性所屬的組(group)名稱。可以是None，表示 group 與 attribute 相同。
attribute: 一個字串，表示屬性名稱。
image: 若不是None，該入參應該是與屬性關聯顯示的某個可視組件。
default: 若為True並且組中沒有其他屬性時，這就是預設的屬性。

下列關鍵字入參與層疊式圖像語句的group定義相同：

at: 應用於圖層的一個變換(transform)或變換的列表。
if_all: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只有所有特定的屬性都出現時，才顯示圖層(layer)。
if_any: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只要有任意特定的屬性出現時，就顯示圖層(layer)。
if_not: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只有所有特定的屬性都不出現時，才顯示圖層(layer)。

其他關鍵字入參會當作變換特性使用。這種情況下，就是用變換對象處理圖像。 (例如，入參 pos=(100, 200) 會用來將圖像分別向水平方向平移100像素、垂直方向平移200像素。)

如果 image 參數被省略或值為None，且LayeredImage對象被指定了 image_format 參數，那麼image_format參數用於生成圖片檔案名。

class Condition(condition, image, **kwargs) link

當條件表達式結果為True時，顯示圖層。否則，不顯示圖層。

該類用於實現layeredimage語句中的單條 if、elif 或者 else 條件表達式(遇到 else 的情況必須為“True”)，將一些Condition對象傳入 ConditionGroup 可以模擬一套完整的 if/elif/else 條件語句。

condition: 該參數是一個字串，表示一個Python條件表達式，判斷圖層是否顯示。
image: 若不是None，該參數應是一個可視組件，當條件表達式為True時顯示。
if_all: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只有所有特定的屬性都出現時，才顯示圖層(layer)。
if_any: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只要有任意特定的屬性出現時，就顯示圖層(layer)。
if_not: 屬性(attribute)名稱的字串或字串列表。如果出現了這項特性，只有所有特定的屬性都不出現時，才顯示圖層(layer)。
at: 應用於圖層的一個變換(transform)或變換的列表。

其他關鍵字入參會當作變換特性使用。這種情況下，就是用變換對象處理圖像。 (例如，入參 pos=(100, 200) 會用來將圖像分別向水平方向平移100像素、垂直方向平移200像素。)

class ConditionGroup(conditions) link

將一個 Condition 類型的列表組合為一個 ConditionSwitch()。

實現 if/elif/else 語句。

class LayeredImage(attributes, at=[], name=None, image_format=None, format_function=None, attribute_function=None, offer_screen=None, **kwargs) link

這是一個類似圖像的對象，可以使用合適的屬性集，顯示可視組件。此可視組件由關聯屬性合成。

attributes: This must be a list of Attribute, Condition, ConditionGroup or displayable objects. Each one reflects a displayable that may or may not be displayed as part of the image. The items in this list are in back-to-front order, with the first item further from the viewer and the last closest. Passing a displayable directly is the equivalent of the always layeredimage statement. 該參數必須是一個Attribute對象、Condition對象、ConditionGroup對象或 displayable 對象構成的列表。
at: 一個變換(transform)或變換的列表，會參數化之後應用到可視組件。
name: 層疊式圖像名稱，是完整圖像組件名的一部分。
image_format: 當給定的圖像是一個字串，同時提供了此參數時，會使用檔案名加上 image_format 生成圖片檔案名。例如，“sprites/eileen/{image}.png”會在對應的目錄中搜索圖片。(不會被auto組使用，auto組只搜尋圖像對象而不搜索圖片文件。)
format_function: 此函數用於代替 layeredimage.format_function 將圖像資訊格式為可視組件。
attribute_function: 若不是None，此參數是一個函數。使用一個屬性集作為參數調用該函數並應用到指定圖像，函數返回一個屬性集用於選擇圖層。在選擇完屬性之後，判斷圖層是否顯示時會調用該函數。該函數可用於處理屬性之間複雜的依賴關係，或者需要隨機性的情況。
offer_screen: 該參數決定子組件的位置和大小是否要根據目標區域做調整。若該項為False則進行調增，若為True則保持原狀。若為None，則根據配置項 config.layeredimage_offer_screen 決定。

額外的關鍵字入參可能包含變換特性(transform property)。如果出現這種情況，將創建變換對象並處理結果圖像。剩下的關鍵字入參將傳給一個Fixed組件用於放置圖層。除非顯式覆蓋，該Fixed組件的xfit和yfit特性會設置為True，將會在使用最小尺寸填充指定區域以匹配圖層上所有顯示圖像。

LayeredImage對象不是可視組件，也不能完全跟可視組件一樣使用。因為LayeredImage對象必須有圖像名稱(大多數時候還必須有圖像屬性)。所以，其要麼使用scene或show語句來顯示，要麼像可視組件一樣透過圖像名字串來調用。

add(a) link

a: 一個Atrribute、Condition、ConditionGroup或 displayable 對象。

該方法為圖層指定了層疊式圖像的圖層列表，會作為 attributes 入參傳給構造器。