顯示圖像

若要定義出視覺小說的重點，通過其名字就能得到，重點是“視覺”。Ren’Py中，提供了4種語句用於控制圖像顯示，並提供了一種模式用於控制圖像顯示順序。這些特性可以使視覺小說和敘事性遊戲中，合理展示圖像變得十分方便。

與圖像相關的4種語句分別是：

• image - 定義一個新的圖像(image)。

• show - 在圖層上(layer)顯示一個圖像。

• scene -清空圖層(layer)，並可選是否在那個圖層上顯示一個圖像。

• hide - 將圖層(layer)上的某個圖像移除。

圖像的突然變化顯得很突兀，Ren’Py提供了 with 語句，可以在場景切換時提供各種效果。

本頁中出現的大多數語句都會使用 Lint 檢查，但他們的等效Python語句則不會檢查。

一些概念

圖像(image)

圖像(image)是可以使用show語句顯示在界面上的一類東西的統稱。圖像(image)由一個名稱和一個可視組件構成。當某個圖像展示在某個圖層上時，也表示那個圖像關聯的可視組件顯示在圖層上。

一個 圖像名稱 可能包含一個或更多欄位，由空格分隔。圖像名稱的第一個欄位稱作 圖像標籤(tag)。 後面的欄位被稱作 圖像屬性(attribute)。

舉例來說，假設圖像名稱為 mary beach night happy 。圖像標籤就是 mary ，而圖像屬性(attribute)就是 beach 、 night 和 happy 。

可視組件是可以展現在界面上的一類東西的統稱。最常用來展現的是靜態圖像，只需要以字串形式給定圖片檔案名稱就可以使用了。在上面的樣例中，我們可以使用 mary_beach_night_happy.png 這樣的檔案名 除了靜態圖片之外，圖像(image)可以使用 Ren’Py支持的所有可視組件 。 用於顯示圖像的語句也可以用來顯示動畫、純色和其他可視組件。

圖層(layer)

圖層是一個可以顯示在界面上的可視組件列表。Ren’Py支持多圖層，包括使用自訂圖層。圖層(layer)的順序在遊戲內設置(被 config.layers 變數控制)， 而圖層內可視組件的順序由scene和show語句的順序及語句中的特性(property)共同決定。

以下圖層由Ren’Py內部定義：

master

該圖層是在scene、show和hide語句中預設使用的圖層。master圖層主要用於背景和角色精靈(sprite)。

transient

UI函數使用的默認圖層。在每次互動結束後，該圖層都會被清空。

screens

該圖層用於界面系統。

overlay

當UI函數被覆蓋(overlay)函數調用時，預設使用的圖層。當一個互動行為重新啟動時，該圖層會被清空。

若需要定義新的圖層，可以調用 renpy.add_layer() 函數，並設置圖層相關 配置項。 使用 camera statement，時，一個圖層可以同時應該多個變換。

定義圖像(image)

有兩種定義圖像(image)的方式。你可以將圖片文件放在images目錄裡，或者使用image語句定義一個圖像(image)。圖像的定義格式比較簡單，只要放入目錄中的圖片文件命名符合轉換規則，就能直接轉換為圖像並使用，還允許使用非圖像文件定義圖像。

使用image語句的優先度高於通過image目錄定義的圖像。

images目錄

圖像目錄名為“images”，放置在game目錄下。當一個副檔名為.jpg、.jpeg、.jxl、.png或.webp的文件被放入這個目錄時，文件的副檔名會被忽略，檔案名的其餘部分強制轉為小寫，最終生成的檔案名會被用作圖像(image)的名稱，前提是那個名稱沒有在之前其他地方被顯示定義過。

這種設計會處理所有images目錄下的子目錄。例如，以下所有文件都會被定義為圖像(image) eileen happy ：

game/images/eileen happy.png
game/images/Eileen Happy.jpg
game/images/eileen/eileen happy.png

如果指定圖片名後沒有在game目錄中找到，則會再次在images目錄搜索。

過採樣

默認情況下，圖片的尺寸決定了實際顯示時的大小。 比如，一個1920×1080像素的圖片，使用 gui.init() 運行在1920×1080解析度下時，將填滿整個螢幕。

啟用過採樣之後，圖片顯示時的尺寸會比實際的要小。 例如，原圖片為3480×2160像素，過採樣係數為2。 那麼兩個軸向的尺寸都會減半，最終圖像將顯示為1920×1080。

在圖片需要縮放同時要求細節時，過採樣技術十分有用。 當使用更高細節的圖形重製遊戲時，過採樣可以用來解決 config.physical_width 和 config.physical_height 與素材間的矛盾。

圖片名出去副檔名，以一個 ‘@’ 符號加數字形式結尾時，將自動啟用過採樣。 例如，eileen happy@2.png 表示2倍過採樣， eileen happy@3x.png 表示3倍過採樣。 使用 Image() 函數時指定關鍵字參數 oversample 的值也可以啟用過採樣。

image語句

image語句用於定義圖像(image)。一條image語句由以下部分組成：以關鍵字 image 開頭的一條邏輯行，後接一個圖像名，一個等號(=)和一個可視組件。舉例：

image eileen happy = "eileen_happy.png"
image black = "#000"
image bg tiled = Tile("tile.jpg")

image eileen happy question = VBox(
    "question.png",
    "eileen_happy.png",
    )

如果某個圖片文件並不直接放在game目錄下，創作者需要給出文件路徑。例如，對圖片 game/eileen/happy.png，需要這樣寫：

image eileen happy = "eileen/happy.png"

image語句在初始化階段就運行，在開始標籤(label)運行或者初始菜單展現之前。就算image語句不放在初始化語句塊(block)中，它們依然會獲得初始化語句塊同樣的優先度級別500。

其他資訊可以參考 ATL的image語句變種 。

show語句

show語句用於在某個圖層(layer)上顯示一個圖像(image)。一條show語句由以下部分組成：以關鍵字 show 開頭的一條邏輯行，後接一個圖像名，以及0個或多個特性(property)。

如果show語句被給定了某個已存在的圖像(image)的準確名稱，對應的圖像就會被顯示。如果給定圖像名不存在，Ren’Py就會嘗試尋找符合以下條件的圖像：

• 在show語句中擁有相同特定標籤(tag)。

• 在show語句中擁有給定的所有屬性(attribute)。

• 若擁有相同標籤(tag)的某個圖像正被顯示，與那個圖像共享最大數量的屬性(attribute)。

若沒有任何一個符合條件的圖像(image)被找到，就會發生異常。

若帶有相同圖像標籤(tag)的圖像已經在圖層上顯示了，新的圖像就會替換原來的圖像。否則，該圖像會覆蓋在同一圖層所有其他圖像之上。(對設計者來說)圖像的相互覆蓋順序可以通過調整zorder和behind特性(property)。

show語句不會觸發互動行為。由於圖像實際上已經向用戶展示，後面必須執行一個能夠觸發互動行為的(say、menu、pause或with)語句。

show語句可以使用以下特性(property)：

as

as特性(property)使用一個名稱。當某個圖像被顯示時，as特性(property)的名稱被用作該圖像的標籤(tag)的別名。這種設計可以讓同樣的圖像在界面上出現兩次。

at

at特性(property)使用一個或多個英文逗號分隔的簡單表達式。每一個簡單表達式必須能換算成一個變換(transform)。變換(transform)被以從左到右的順序應用到圖像上。

如果沒有給定at分句的情況下，Ren’Py會保持之前任何已經存在併應用到圖像上使用ATL或 Transform 創建的變換(transform)。如果沒有指定變換(transform)，圖像會使用默認 default 變換(transform)顯示。

使用標籤(tag)進行變換特性的修改和替換的內容，詳見 變換替換 章節。

behind

behind特性(property)使用一列英文逗號分隔的變數名。每個變數名都代表一個圖像標籤(tag)。分句開頭變數名指代的圖像，顯示在帶有指定標籤(tag)的所有圖像之後。

onlayer

onlayer特性(property)使用一個變數名。在變數名對應的圖層(layer)上顯示圖像。

zorder

zorder特性(property)使用一個整數值。該整數指定了同一個圖層(layer)內各個圖像在z軸上的位置。數值越大，圖像距離用戶越近。zorder主要不是用於Ren’Py遊戲中，而對從其他引擎移植過來的視覺小說可能有用。 zorder還有個用處，可以將某些始終要顯示在最上層的圖像的zorder設置得很大，避免了設置圖層的麻煩。

假設我們定義了如下的圖像：

image mary night happy = "mary_night_happy.png"
image mary night sad = "mary_night_sad.png"
image moon = "moon.png"

show語句樣例如下：

# 最基礎的顯示
show mary night sad

# 由於‘mary night sad’已經顯示了，下個語句等價於：
# show mary night happy
show mary happy

# 在界面右邊顯示圖像
show mary night happy at right

# 同樣的圖像顯示兩次
show mary night sad as mary2 at left

# 在兩個圖像後面顯示圖像
show moon behind mary, mary2

# 在用戶自訂的圖層上顯示圖像
show moon onlayer user_layer

屬性(attribute)管理

綜上所述，屬性可以設置、添加和替換。

還可以使用減號移除：

# 顯示正常的蘇珊
show susan

# 顯示高興的蘇珊
show susan happy

# 再次顯示正常的蘇珊
show susan -happy

show expression

show語句的一個變種，使用關鍵字 expression 代替圖像名，後面跟一個簡單表達式。表達式必須能解析為一個可視組件，而該可視組件會在圖層上顯示。若要隱藏該可視組件，必須使用as語句指定一個圖像標籤(tag)。

舉例:

show expression "moon.png" as moon

show layer

show layer 語句將跟後面的 camera 語句 一起討論。

scene語句

scene語句會移除圖層(layer)上所有的可視組件，並在該圖層上顯示一個圖像。場景語句開頭是關鍵字 scene ，後面跟一個圖像名，最後可能有若干個特性(property)。scene語句中，圖像的顯示方式和特性的使用效果與show語句一致。

scene語句經常用於，在背景圖層上顯示一個圖像。例如:

scene bg beach

scene表達式。 與show語句類似，場景語句也能使用表達式代替圖像名。

清空圖層。 如果圖像名為空，scene語句會清空圖層上所有可視組件，並且不會顯示任何東西。

hide語句

hide語句將一個圖像從圖層中移除。該語句以關鍵字 hide 開頭，後跟一個圖像名，再後面可能包含一個特性(property)。hide語句從圖片名中獲取圖片標籤(tag)，並將圖層上該標籤(tag)所對應的所有圖像都移除。

hide語句很少用到。如果一個精靈(sprite)表示一個角色，那麼只有當角色離開場景時hide語句才會被用到。當角色改變表情時，使用show語句更好，因為顯示語句會自動替換帶有同名標籤(tag)的角色圖片。

hide語句擁有以下特性(property):

onlayer

該特性擁有一個變數名。隱藏該變數名對應圖層(layer)上的圖像(iamge)。

舉例:

e "我要離開這裡。"

hide eileen

下面這段是反例，請勿模仿這種寫法:

hide eileen
show eileen happy

正確的寫法是:

show eileen happy

with語句

with語句用於在場景切換時應用轉場(transition)效果，使得圖像的出現和隱去不顯得突兀。with語句以關鍵字 with 開頭，後跟一個簡單表達式，該簡單表達式可以轉換為一個轉場(transition)對象或者特殊值 None 。

轉場(transition)效果會被應用於某次互動行為後上一個界面所有內容的消隱，跟show和hide語句執行後新界面的展現之間。

with語句會觸發等待一個互動行為。該互動行為存在期間由用戶控制，用戶可以通過互動更快結束這個過程。

所有可用的轉場(transition)效果列表，詳見 轉場。

with語句的樣例:

show bg washington
with dissolve

show eileen happy at left
show lucy mad at right
with dissolve

這段腳本觸發了兩段過渡(transitions)效果。第一個with語句使用 dissolve 效果將界面場景切換至背景“washington”。( dissolve 預設為歷時0.5秒的溶解效果。)

第二個with語句在Eileen和Lucy出場之後使用了轉場(transition)效果。這條語句使得原本只包含背景畫面的場景切換到包含三個圖像的場景——新登場的兩個角色圖像一齊使用溶解效果出現。

With None

在上述的例子中，使用了兩次dissolve效果。但如果我們希望背景即刻出現，而角色登場使用dissolve效果的話，應該怎樣做？在第一個with語句中只是不帶任何值的話，3個圖像依然會使用dissolve效果顯示——我們需要一種方式聲明背景需要立刻出現。

with語句使用特殊值 None ，就可以滿足我們的要求。 with None 語句會簡單地觸發一個互動行為，不改變用戶所看到的畫面。當下一個轉場(transition)發生時，這種效果會從with None語句定義的語句塊開始直到互動行為完成。

例如，這段腳本:

show bg washington
with None

show eileen happy at left
show lucy mad at right
with dissolve

只有一個轉場(transition)效果發生，發生在只有背景“washington”到背景加兩個角色的場景。

scene、show和hide語句中的with分句

scene、show和hide語句可以帶一個with分句，該分句使得圖片的顯示和隱藏可以直接關聯一個轉場(transition)效果。with分句跟在其他語句的同一個邏輯行結尾，以關鍵字 with 開頭，後接一個簡單表達式。

with分句等效於在原有語句前面先加了一行 with None 語句，附加分句的過渡效果相當於原有語句後加了一行with語句 with 語句。舉例：:

show eileen happy at left with dissolve
show lucy mad at right with dissolve

等效於:

with None
show eileen happy at left
with dissolve

with None
show lucy mad at right
with dissolve

注意，儘管這種用法可以對 show screen 和 hide screen 語句生效， 但 call screen 語句則不行。

camera和show layer語句

camera 語句允許我們將某個變換(transform)或者ATL變換(transform)應用於整個圖層(layer)，比如“master”圖層上。語法如下：

camera at flip

或：

camera:
    xalign 0.5 yalign 0.5 rotate 180

若要停用圖層上的格式，則使用：

camera

camera語句可以選擇指定圖層名稱，圖層名放在 camera 和 at 或 : 之間：

camera mylayer at flip

show layer 語句相當於一個舊版本的 camera 語句，有一些區別，也依然可以使用。

show layer master:
    blur 10

兩者的區別是：

• 使用 show layer 應用的變換會在下一個 scene 語句後清除，而 camera 語句則需要顯式清除。

• show layer 語句需要指定圖層名稱，而 camera 默認應用到master圖層。

hide和show窗口

當某個角色不處於發言狀態時，window語句用於控制窗口顯示。(例如，在過渡效果或者暫停狀態下。)window show語句顯示窗口，而window hide語句隱藏窗口。

轉場(transition)效果是可選的，若指定了過渡效果，就會應用在窗口的顯示和隱藏。若沒有指定，預設使用 config.window_show_transition 和 config.window_hide_transition 的值。指定None則不使用任何過渡效果。

窗口自身可以透過調用 config.empty_window 顯示。 窗口默認旁白說了一句話，內容為空字串。

show bg washington
show eileen happy
with dissolve

window show dissolve

"我可以說話……"

show eileen happy at right
with move

"……和移動，在窗口顯示的情況下。"

window hide dissolve

圖像(image)函數

renpy.add_layer(layer, above=None, below=None, menu_clear=True, sticky=None)

界面中添加一個新的圖層。如果已存在同名圖層，則該函數沒有任何效果。

behind 或 above 參數至少一項不能為None。

layer

一個字串，指定待添加圖層的名稱。

above

若不是None，應該是一個字串，表示待添加的新圖層需要在對應圖層的上層。

below

若不是None，應該是一個字串，表示待添加的新圖層需要在對應圖層的下層。

menu_clear

若為True，進入遊戲菜單上下文時該圖層將清空，離開遊戲菜單上下文時恢復圖層顯示內容。

sticky

若為True，所有實用tag標籤在該圖層顯示的內容都可將該圖層設置為默認圖層，直到該圖層隱藏。 若為None，僅當其他黏滯圖層存在時，該圖層才會替換其他黏滯圖層並成為新的黏滯圖層。

renpy.can_show(name, layer=None, tag=None)

該函數判斷入參 name 代表的圖像是否能顯示。函數把入參 name 看做一個圖像標籤(tag)和屬性(attribute)。該函數依據目前正顯示在 圖層 上的所有 tag 來嘗試確認唯一的圖像。若存在唯一可顯示圖像，則以元組形式返回圖像名。否則返回None。

tag

圖像標籤(tag)屬性。若為空，預設使用入參name的第一個組件。

layer

需要確認的圖層(layer)名。若為空，則預設使用 tag 所在圖層。

renpy.change_zorder(layer, tag, zorder)

修改圖層 layer 上標籤為 tag 圖像的zorder值。

renpy.check_image_attributes(tag, attributes)

根據給定的tag和attributes檢查是否存在唯一圖像。若存在，按順序返回圖像屬性(attribute)。否則返回None。

renpy.clear_attributes(tag, layer=None)

清楚帶有 tag 標籤的圖像屬性(attribute)。 如果tag不帶任何圖像屬性，則無事發生。

layer

待檢查的圖層。若為None，則使用 tag 對應的默認圖層。

renpy.copy_images(old, new)

複製圖像，並更換新圖像的前綴名。樣例：

renpy.copy_images("eileen", "eileen2")

將複製所有以“eileen”開頭的圖像並創建以“eileen2”開頭的新圖像。若“eileen happy”存在，則創建“eileen2 happy”。

old

原圖片名的字串，圖片名各部分以空格分隔。

new

新圖片名的字串，圖片名各部分以空格分隔。

renpy.flush_cache_file(fn)

該函數會將所以引用文件 fn 的圖像快取都清空。 需要Ren’Py強制更新圖像文件時可以調用該函數。

renpy.get_attributes(tag, layer=None)

根據入參圖片標籤 tag ，返回對應圖像屬性(attribute)的元組。若圖像整在顯示，則返回None。

layer

待檢圖層(layer)。若為空，使用 tag 所在的默認圖層。

renpy.get_available_image_tags()

返回一個列表，包含所有已定義的圖像標籤。

renpy.get_ordered_image_attributes(tag, attributes=(), sort=None)

返回圖像標籤(tag)列表，按照對用戶來說合理的方式排序。

attributes

若該值不為空，只尋找與給定屬性(attribute)相容的結果。(相容的意思是，各類屬性在同一時間裡能找到對應唯一圖像。)

sort

若不為None，返回的屬性(attribute)列表就是排序後的。該單入參函數應當用作中斷器(tiebreaker)。 詳見 這篇教學 。

renpy.get_placement(d)

該函數獲取到可視組件d的位置。返回的位置資訊可信度很低，因為可視組件在渲染後可能被改變了，也可能可視組件在首次渲染之前根本不存在。

該函數返回的對象包含以下欄位(field)，每一個都對應一項樣式特性(property)：

- pos - xpos - ypos - anchor - xanchor - yanchor - offset - xoffset - yoffset - subpixel

renpy.get_registered_image(name)

如果有 已註冊 的同名圖像則返回圖像對象。 否則返回None。

renpy.get_say_image_tag()

返回當前發言角色對應的圖像標籤(tag)(角色獲得的圖像入參)。如果當前沒有角色發言或當前發言角色沒有對應的圖像標籤(tag)則返回None。

renpy.get_showing_tags(layer='master')

返回入參 layer 圖層上顯示的所有圖像標籤(tag)的集。

renpy.get_zorder_list(layer)

返回圖層 layer 的(tag, zorder)列表。

renpy.has_image(name, exact=False)

若入參name為名的圖像存在返回真(true)，若不存在返回假(false)。

name

一個圖像名的字串，或者圖像名各組件的元組。

exact

只有跟name全匹配的圖像名存在時才返回真(true)——部分匹配則返回假(false)。

renpy.mark_image_seen(name)

將對應名稱的圖像在當前用戶系統上標記為顯示過。

renpy.mark_image_unseen(name)

將對應名稱的圖像在當前用戶系統上標記為未顯示過。

renpy.seen_image(name)

若名為name的圖像在用戶系統中至少被看到過一次，就返回真(true)。圖像被看到的定義是，其在show、scene語句或者renpy.show()函數中出現過。(注意這裡的“被看到”並不意味著真的被用戶看見過，比如show語句後面馬上跟一個hide語句的情況也屬於“被看到”過。)

renpy.showing(name, layer='master')

若與name同名標籤的圖像整在圖層 layer 上顯示，則返回真(true)。

image

可能是一個給定圖像名的字串，或者給定圖像名各組件的元組。還可以只是給定圖像標籤(tag)的字串。

layer

待檢圖層(layer)。若為None，使用 tag 所在默認圖層。

renpy.start_predict(*args)

該函數接受一個或多個可視組件作為入參。該函數觸發Ren’Py在每次交互行為中預載入入參中的可視組件，直到使用 func:renpy.stop_predict() 移除預載入的那些可視組件。 如果可視組件名稱字串一個包含1個或多個 \* 字元，則視為一個通配表達式。 如果字串中至少存在一個英文句號 . ，表達式將對整個檔案名進行匹配，否則將不匹配文件副檔名。 例如：

$ renpy.start_predict("eileen *")

預載入所有名為eileen的所有圖片。而：

$ renpy.start_predict("images/concert*.*")

匹配images目錄下所有以concert開頭的文件。

renpy.stop_predict(*args)

該函數接受一個或多個可視組件作為入參。該函數觸發Ren’Py停止在每次互動行為中預載入入參中的可視組件。

其他參考

等效語句 ：關於如何在Python中使用本章節提到的大部分功能。

可視組件 ：其他可顯示對象，不限於基本的圖片。