其他函數和配置變數

此頁面記錄的是，其他地方沒有列出的各類函數和變數。

Ren’Py版本相關

renpy.version(tuple=False)

若 tuple 為False，返回一個帶有“Ren’Py”的字串，字串後半部分是Ren’Py的當前版本資訊。

若 tuple 為True，返回一個元組。元組內每個元素分別表示版本資訊的一個整數部分。

renpy.version_string

Ren’Py的版本號，類似於字串“Ren’Py 1.2.3.456”的格式。

renpy.version_only

Ren’Py的版本號，不帶Ren’Py前綴，類似於字串“1.2.3.456”的格式。

renpy.version_tuple

Ren’Py的版本號，類似於元組(1, 2, 3, 456)的格式。

renpy.version_name

一個人類可能的版本名稱，類似“Example Version”的格式。

renpy.license

一個表示許可證文本的字串，這個字串應該在遊戲的“關於”界面中顯示。

平台檢測

Ren’Py包含許多變數需要基於運行的平台進行設置。

renpy.windows

在Windows平台運行時為True。

renpy.macintosh

在macOS平台運行時為True。

renpy.linux

在Linux或者POSIX類操作系統運行時為True。

renpy.android

在安卓平台運行時為True。

renpy.ios

在iOS平台運行時為True。

renpy.emscripten

在瀏覽器內運行時為True。

renpy.mobile

在安卓、iOS平台或瀏覽器運行時為True。

只有在實際設備運行而非模擬器上運行時，才會設置這些配置項。 這些配置項對平台敏感的Python是有用的。對顯示布局(layout)的問題，詳見 界面變種.

記憶體分析

renpy.diff_memory(update=True, skip_constants=False)

分析Ren’Py和遊戲使用的對象(object)、貼圖(surface)和紋理(texture)記憶體。將上次調用該函數時和這次調用該函數的內容使用差異，並(在memory.txt和stdout)記錄下。

計算方式是，按照儲存區的名稱和Ren’Py實現中所有可達的記憶體。 如果某個對象通過多個名稱可達，就聲明為最短可達路徑。

skip_constants

若為True，除錯器將不會掃描巨大的Ren’Py容器，因為那些內存在啟動後就不會變化。

由於透過該函數可以掃描所有Ren’Py使用的記憶體，所以執行完畢相當耗時。

renpy.profile_memory(fraction=1.0, minimum=0, skip_constants=False)

分析Ren’Py和遊戲使用的對象(object)、貼圖(surface)和紋理(texture)記憶體。將使用的記憶體總數寫入memory.txt和stdout。

計算方式是，按照儲存區的名稱和Ren’Py實現中所有可達的記憶體。 如果某個對象通過多個名稱可達，就聲明為最短可達路徑。

fraction

顯示使用記憶體總數的比例。1.0會顯示所有使用的記憶體，.9顯示最高的90%。

minimum

如果某個名稱的記憶體使用小於 minimum 字長，就不會顯示。

skip_constants

若為True，除錯器將不會掃描巨大的Ren’Py容器，因為那些內存在啟動後就不會變化。

由於透過該函數會掃描所有Ren’Py使用的記憶體，所以執行完畢相當耗時。

renpy.profile_rollback()

分析回滾系統使用的記憶體。將回滾系統使用的記憶體寫入到memory.txt和stdout。該函數嘗試計算各種儲存變數用於回滾的記憶體量，以及回滾系統內部使用的記憶體量。

renpy.random

這個對象是一個隨機數生成器，實現了 Python隨機數生成介面 。調用這個對象衍生的各種方法可以生成需要的隨機數。詳見Python中的完整列表。最常用的幾個如下：

• renpy.random.random()

  返回一個位於(0.0, 1.0)開區間的隨機浮點數。

• renpy.random.randint(a, b)

  返回一個整數N，a <= N <= b。

• renpy.random.choice(seq)

  從非空序列 seq 隨機返回一個元素。

• renpy.random.shuffle(seq)

  打亂序列 seq 中元素的順序。該函數不會返回列表，而是直接修改原列表。

與標準的Python隨機數生成器不同，這個對象可以與回滾相容，無論回滾多少次都生成相同的隨機數。所以可以使用這個對象代替標準Python隨機模組。

# 返回一個介於0到1之間的隨機浮點數。
$ randfloat = renpy.random.random()

# 返回一個介於1到20之間的隨機整數。
$ d20roll = renpy.random.randint(1, 20)

# 返回列表中的一個隨機元素。
$ randfruit = renpy.random.choice(['apple', 'orange', 'plum'])

• renpy.random.Random(seed=None)

  返回一個新的隨機數生成器對象。與主隨機數生成器不同，新的對象使用指定的值作為種子。

SDL

通過函數 renpy.get_sdl_dll() 可以接入SDL2動態連結庫(dll)，之後即可直接使用SDL2的函數了。 不過，通常要求有一些Python ctypes模組的知識，才能正確使用SDL2的函數。

Ren’Py不保證包含的SDL2版本編譯後包含或不包含某些特性(feature)。 某些平台可以運行，但其他平台可能會報錯。 使用這些函數的返回值之前需要確認是否返回了None。

下面的例子中，窗口位置資訊來源於SDL2：

init python:

    import ctypes

    def get_window_position():
        """
        通過SDL2檢查窗口坐標。返回以窗口左上角為原點坐標的(x, y)值。如果是未知坐標也會返回(0, 0)。
        """

        sdl = renpy.get_sdl_dll()

        if sdl is None:
            return (0, 0)

        win = renpy.get_sdl_window_pointer()

        if win is None:
            return (0, 0)

        SDL_GetWindowPosition = sdl.SDL_GetWindowPosition

        x = ctypes.c_int()
        y = ctypes.c_int()

        result = sdl.SDL_GetWindowPosition(win, ctypes.byref(x), ctypes.byref(y))

        return result

renpy.get_sdl_dll()

該函數返回一個ctypes.cdll對象，指向Ren’Py正在使用的SDL2實例中的庫。

如果無法獲取，則返回None。

renpy.get_sdl_window_pointer()

Return type:

ctypes.c_void_p | None

返回主窗口的指針。如果主窗口沒有顯示(或發生其他問題)，返回None。

其他林林總總

renpy.add_python_directory(path)

將 path 添加在Python模組(module)和包(package)的路徑列表中。這個路勁應該是一個遊戲目錄相對路勁的字串。必須在import語句之前調用該函數。

renpy.add_to_all_stores(name, value)

在創作者定義的命名空間中，添加名為 name 的變數，值為 value 。 如果同名變數已存在，則不做任何操作。 該函數只能在init代碼塊中運行。遊戲啟動後再運行該函數將報錯。

renpy.can_fullscreen()

當前平台支持全螢幕模式就返回True，否則返回False.

renpy.capture_focus(name='default')

若某個可視組件當前獲得焦點，捕獲該組件的包圍矩形，並將其儲存為 name。 若沒有可視組件獲得焦點，移除名為 name 的儲存內容。

保存遊戲時，捕獲的焦點區域不會同時保存。

name

該參數應是一個字串。入參值“tooltip”是特殊的，會自動捕獲可視組件提示區域。

renpy.choice_for_skipping()

告訴Ren’Py即將出現一個選項。該函數當前有兩種影響：

• 如果Ren’Py正在跳過(skip)，並且“跳過後面選項”設置為停止跳過，那麼跳過就會終止。

• 觸發自動保存。

renpy.clear_capture_focus(name='default')

清除名為 name 的焦點捕獲。

renpy.clear_game_runtime()

重設遊戲運行時間計數器。

renpy.clear_retain(layer='screens', prefix='_retain')

清空所有留存的界面。

renpy.confirm(message)

該函數可以彈出一個包含指定資訊的 “確認/取消” 提示界面，並在用戶點擊任意選項後隱藏界面。

如果用戶點擊“確認”則返回True，如果用戶點擊“取消”則返回False。

message

需要顯示的提示資訊。

Confirm() 是一個類似功能的行為(action)。

renpy.count_dialogue_blocks()

返回遊戲原生語言的對話段落數量。

renpy.count_newly_seen_dialogue_blocks()

返回本次會話(session)中用戶首次看到的對話段落數量。

renpy.count_seen_dialogue_blocks()

返回用戶在當前遊戲進度中看過的所有對話段落數量。

renpy.display_notify(message)

renpy.notify() 函數的默認實現。

renpy.focus_coordinates()

該函數會嘗試找到當前獲得焦點可視組件的坐標。如果成功找到，返回一個(x, y, w, h)元組。如果沒有找到，返回一個(None, None, None, None)元組。

renpy.force_autosave(take_screenshot=False, block=False)

強制後台自動存檔。

take_screenshot

若為True，進行新的截圖。若為False，使用已存在的截圖。

block

若為True，將屏蔽所有事件和操作，直到自動存檔完成。

renpy.free_memory()

嘗試釋放一些記憶體。在運行基於renpy的minigame前很有用。

renpy.full_restart(transition=False, label='_invoke_main_menu', target='_main_menu', save=False)

讓Ren’Py重啟，將用戶帶回到主選單。

transition

如果給定了轉場，就運行轉場；如果這項是None則不運行轉場；如果這項是False，就用 config.end_game_transition() 。

save

若為True，將先存檔在 _quit_slot，然後讓Ren’Py重啟，將用戶帶回到主選單。

renpy.get_game_runtime()

返回遊戲運行時間計數器。

遊戲運行時間計數器返回用戶從頂層上下文(context)等待用戶輸入經過的秒數。(在主選單和遊戲菜單消耗的時間不計入。)

renpy.get_image_load_log(age=None)

圖像載入啟用日誌生成器。對最後100項圖像載入來說，該函數返回：

• 圖像載入的時間(1970-01-01 00:00:00 UTC開始計算的秒數)。

• 載入圖像檔案名。

• 如果圖像預載入返回True，如果延遲載入返回False。

輸出結果按從新到舊排序。

age

如果不是None，只統計經過 age 秒之後載入的圖像。

在config.developer = True的情況下，才保存圖像載入日誌。

renpy.get_menu_args()

返回一個元組，其中包含傳給當前menu語句的所有入參(以元組形式)和所有關鍵字入參(以字典形式)。

renpy.get_mouse_name(interaction=False)

返回顯示滑鼠名稱。

interaction

若為True，根據互動類型獲取滑鼠名稱。(極少使用)

renpy.get_mouse_pos()

返回一個(x, y)元組，表示滑鼠指針或當前觸摸位置的坐標。如果設備不支持滑鼠並且當前沒有被觸摸，x和y值無意義。

renpy.get_on_battery()

如果Ren’Py當前運行設備使用內部電池供電，則返回True； 如果當前運行設備使用外部電源，則返回False。

renpy.get_physical_size()

返回物理窗口的尺寸。

renpy.get_refresh_rate(precision=5)

返回當前螢幕的刷新率，這是一個fps浮點數。

precision

Ren’Py能獲得的裸數據，fps向下取整。就是說，如果顯示器運行在59.95fps，那麼函數返回的就是59fps。 precision參數進一步降低了實際顯示的幀數，只能能pricision的整倍數。

由於所有顯示器幀率都是5的整倍數(25、30、60、75和120)，該函數可能會提高準確性。將precision設置為1表示禁用這個功能。

renpy.get_renderer_info()

返回一個字典，表示Ren’Py當前使用的渲染器資訊。自定中包含下列鍵(key)：

"renderer"

"gl" 或 "sw" ，分別對應OpenGL和軟體渲染。

"resizable"

僅當窗口可重新調整尺寸的情況下為True。

"additive"

僅當那個渲染器支持額外混合(blend)的情況下為True。

"model"

如果支持基於模型渲染器，則為True。

另外，鍵值也可能存在特定渲染器。這個字典應該被認為是不能修改的。可視組件啟動後(也就是初始化段落已經結束)，該函數應該只被調用一次。

renpy.get_say_attributes()

獲得與當前say語句相關的屬性(attribute)，如果沒有相關屬性(attribute)則返回None。

只有執行或預載入一條say語句時，該函數才可用。

renpy.get_skipping()

如果Ren’Py跳過中則返回True，如果Ren’Py快速跳過中則返回“fast”，如果Ren’Py不在跳過狀態則返回False。

renpy.get_transition(layer=None)

獲取 lay 的轉場(transition)，如果 layer 為None則獲取整個場景(scene)的轉場。該函數返回了在下次交互行為中，隊列上層的轉場(transition)。如果不存在符合條件的轉場則返回None。

renpy.iconify()

遊戲窗口最小化。

renpy.include_module(name)

類似於 renpy.load_module() ，但不會直接載入對應模組，而是根據當前AST碼穿插進入初始化隊列。

載入初始化優先度數值不能比包含模組的代碼塊更小。 比如，你的模組包含一個優先度為init 10的代碼塊，那載入的最低優先度數值也至少是10.

載入模組的部分只能用在初始化程式碼塊(init block)中。

invoke_in_main_thread(fn, *args, **kwargs)

在主執行緒中使用指定入參運行指定函數。該函數運行在類似於事件處理器的交互上下文中。 這是為了能從其他執行緒調用該函數。其他執行緒可以使用 renpy.invoke_in_thread() 函數創建。

如果在單一執行緒中存在多個可調用的函數，這些函數並不一定會按預計的順序依次執行。

def ran_in_a_thread():
    renpy.invoke_in_main_thread(a)
    renpy.invoke_in_main_thread(b)

在這個例子中，a 肯定先返回，然後再調用 b。從幾個不同執行緒的調用則不一定按此順序。

在初始化階段不能調用該函數。

renpy.invoke_in_thread(fn, *args, **kwargs)

使用後台執行緒調用函數 fn ，傳入該函數收到的所有入參。執行緒返回後重新啟動交互行為。

該函數創建一個守護執行緒(daemon thread)，當Ren’Py關閉後這個執行緒也會自動停止。

該執行緒使用Ren’Py的API能做的事情非常受限。可以調用下列函數修改儲存區的變數：

• renpy.restart_interaction()

• renpy.invoke_in_main_thread()

• renpy.queue_event()

最好在主執行緒中使用其他Ren’Py的API。

然而該函數還無法在Web平台正常運行，僅僅能在不報錯的情況下直接返回。

renpy.is_init_phase()

當Ren’Py正在執行init代碼時返回True，其他情況返回False.

renpy.is_mouse_visible()

如果滑鼠光刻可見則返回True，否則返回False。

renpy.is_seen(ever=True)

如果用戶已經看過當前的行，則返回True。

如果 ever 為True，我們檢查用戶是否看過該行。如果 ever 為False，我們檢查該行是否在當前遊戲過程中被看過。

renpy.is_skipping()

如果Ren’Py當前正處於跳過(skipping)狀態則返回True，否則返回False。

renpy.is_start_interact()

如果在當前交互行為中調用了restart_interaction，就返回True。該函數可以用於確定是否某個交互行為已經開始，或者已重新開始。

renpy.language_tailor(chars, cls)

該函數可用於替換unicode字元的換行類。例如，字串的換行類可以將其設置為某個象形文字的編碼，這個字元的前後就會換行。

chars

一個字串，包含訂製的每一個字元。

cls

A string giving a character class. This should be one of the classes defined in Table 1 of UAX #14: Unicode Line Breaking Algorithm. 一個字串，指定字串類。其須是下表定義中的其中一個類：UAX #14: Unicode Line Breaking Algorithm。

last_say()

返回一個對象，包含最後一條say語句的資訊。

在某個say語句中調用該函數，若是某個普通Character對象使用say語句，則返回結果就是 當前 這條say語句，而不是上一句。

who

發言角色。通常是一個 Character() 對象，不一定有。

what

一個字串，表示對話內容。如果對話還未顯示，則可能是None。這種情況會發生在遊戲剛啟動時。

args

一個元組，包含傳入最後一條say語句的入參。

kwargs

一個字典，包含傳入最後一條say語句的關鍵字入參。

Warning

與其他類似函數一樣，該函數的返回對象短期內還在被其他地方使用或修改。不建議在存檔或回滾相關操作中使用此函數的返回對象。

renpy.load_module(name)

該函數載入名為 name 的Ren’Py模組(module)。Ren’Py模組包含的Ren’Py腳本會載入進通用(儲存)命名空間。Ren’Py腳本包含在名為name.rpym或name.rpymc的文件中。如果某個.rpym文件存在，並且比對應的.rpymc文件更新，就載入.rpym文件並創建新的.rpymc文件。

模組中所有的初始化語句塊(block)(以及其他初始化程式碼)都在函數返回前運行。模組名未找到或有歧義的情況下會報錯。

應該僅在初始化語句塊(init block)中載入模組。

renpy.load_string(s, filename='<string>')

將 s 作為Ren’Py腳本載入。

返回 s 中第一個語句的名稱。

filename 是載入 s 後生成的所有語句對應的檔案名稱。 (譯者註：該函數內部調用renpy.game.script.load_string，要求必須有一個檔案名入參。)

renpy.maximum_framerate(t)

強制Ren’Py在 t 秒內以最大幀率重繪界面。如果 t 是None，則不要求使用最大幀率。

renpy.munge(name, filename=None)

munge式命名 name ，開頭必須是雙下劃線“__”。

filename

需要使用munge處理的檔案名。若為None，就使用調用此次munge的檔案名。

renpy.not_infinite_loop(delay)

將無限循環探測計時器重設為 delay 秒。

renpy.notify(message)

讓Ren’Py使用notify界面顯示 message 。默認情況下，顯示的 message 消息會以dissolve方式出現，顯示2秒，最後以dissolve方式消失。

對一些不會產生回調函數的行為(action)，比如截圖和快速保存，該函數很有效。

一次只能顯示一條通知。顯示第二條通知時，會直接替換第一條通知。

該函數只是調用 config.notify 。可以通過配置項重新實現並替換原函數。

renpy.prediction()

若Ren’Py處於預載入階段則返回True。

renpy.queue_event(name, up=False, **kwargs)

使用給定的 name 將某個事件放入消息隊列。 name 應該是在 config.keymap() 中列出的事件名稱之一，或者是這些事件組成的列表。

up

當事件開始階段(例如，鍵盤按鍵被按下)時，這項應該是False。當事件結束(比如按鍵被鬆開)是，這項才會變成True。

當調用該函數時，事件會被同時放入消息隊列。該函數不能替換事件——替換會修改事件的順序。(替換事件可以使用 config.keymap() 。)

該函數是執行緒安全的(threadsafe)。

renpy.quit(relaunch=False, status=0)

該函數讓Ren’Py完全退出。

relaunch

若為True，Ren’Py會在退出前運行自身的一個副本。

status

Ren’Py返回給操作系統的狀態代碼。大體來說，0表示成功，負數表示失敗。

renpy.quit_event()

觸發一個退出(quit)事件，比如用戶點擊了窗口的退出按鈕。

renpy.reset_physical_size()

嘗試將物理窗口尺寸設置為renpy.config配置的指定值。(就是配置的screen_width和screen_height。)這在全螢幕模式下超出螢幕的情況有副作用。

renpy.restart_interaction()

重新啟動當前交互行為。包括以下內容，將顯示的圖像添加到場景(scene)，重新規劃界面(screen)，並啟動所有隊列中的轉場(transition)。

僅在某個交互行為中，該函數才會執行所有工作。交互行為之外，該函數不產生任何效果。

renpy.screenshot(filename)

將截螢幕保護程式存為 filename 。

如果截螢幕保護程式存成功就返回True。如果由於某些原因保存失敗就返回False。

renpy.screenshot_to_bytes(size)

以二進位制對象形式返回一個截圖，可以作為參數傳入 im.Data() 。該二進位制對象將是一張png格式圖片，例如：

$ data = renpy.screenshot_to_bytes((640, 360))
show expression im.Data(data, "screenshot.png"):
    align (0, 0)

將顯示一個截圖圖像。這個二進位制對象可以儲存到存檔文件和持久化數據中。不過這個對象可能很大，注意不要儲存太多類似的對象。

size

截圖後重新縮放的目標尺寸。若為None，截圖將按用戶窗口的尺寸進行調整，不包含窗口的標題欄。

該函數運行可能比較慢，通常用在類似存檔的截圖需求中，而不應該用在需要即時生效的功能中。

renpy.scry()

返回當前語句的scry對象。

scry對象告知Ren’Py當前語句哪些部分未來必定會是True。目前的版本中，scry對象有下列欄位：

nvl_clear

如果在下一個交互行為之前會執行一個 nvl clear 語句則為True。

say

如果在下一個交互行為之前會執行一個 say 語句則為True。

menu_with_caption

如果在下一個交互行為之前會執行一個含標題的 menu 語句則為True。

who

如果在下一個交互行為之前會執行一個 say 語句或含標題的 menu 語句，則角色對象將使用該欄位。

scry對象有一個next()方法，可以返回下一條將執行語句的scry對象。如果沒有下一條將執行的語句，則返回None。

Warning

與其他類似函數一樣，該函數的返回對象短期內還在被其他地方使用或修改。不建議在存檔或回滾相關操作中使用此函數的返回對象。

renpy.set_mouse_pos(x, y, duration=0)

讓滑鼠指針跳到入參x和y指定的位置。如果設備沒有滑鼠指針，則沒有效果。

duration

執行滑鼠指針移動的時間，單位為秒。這段時間內，滑鼠可能不響應用戶操作。

renpy.set_physical_size(size)

嘗試將物理窗口的尺寸設置為 size 。這對全螢幕模式下的有顯示超出螢幕的副作用。

renpy.shown_window()

調用該函數確認窗口已經顯示。使用“window show”語句的交互行為，會顯示一個空窗口，無論該函數是否被調用。

renpy.split_properties(properties, *prefixes)

將 properties 切割為多個字典，每一個都帶上前綴 prefix 。 該函數輪流使用每一個 prefix 檢查 properties 中每一個鍵(key)。 如果匹配到某個前綴，將就鍵(key)的前綴部分去掉作為最終字典的鍵(key)。

如果沒有匹配到前綴，會拋出異常。(空字串，“”，可以用作最後一個前綴，創建一個全匹配字典。)

例如，下面的語句將“text”開頭的properties分割：

text_properties, button_properties = renpy.split_properties("text_", "")

renpy.transition(trans, layer=None, always=False)

設置下次交互行為使用的轉場(transition)。

layer

轉場應用於這個參數表示的圖層(layer)。若為None，轉場應用於整個場景(scene)。

always

若為False，函數遵循定義的轉場環境設定設置。若為True，使用運行轉場。

renpy.vibrate(duration)

讓設備震動 duration 秒。現在只支持安卓。

layout.yesno_screen(message, yes=None, no=None)

該函數產生一個yes/no提示界面，並顯示給定的提示資訊。當用於選擇了yes或者no之後，就隱藏界面。

message

顯示的提示消息。

yes

用戶選擇yes後運行的行為(action)。

no

用戶選擇no後運行的行為(action)。