其他函數和配置變數 link

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

Ren’Py版本相關 link

renpy.version(tuple=False) link

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

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

renpy.version_string link

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

renpy.version_only link

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

renpy.version_tuple link

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

renpy.version_name link

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

renpy.license link

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

平台檢測 link

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

renpy.windows link

在Windows平台運行時為True。

renpy.macintosh link

在macOS平台運行時為True。

renpy.linux link

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

renpy.android link

在安卓平台運行時為True。

renpy.ios link

在iOS平台運行時為True。

renpy.emscripten link

在瀏覽器內運行時為True。

renpy.mobile link

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

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

記憶體分析 link

renpy.(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) link

分析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() link

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

上下文(context) link

renpy.context() link

返回一個對象,這個對象對當前上下文(context)唯一。進入一個新的上下文時,這個對象會複製一個副本。但對副本的修改不會影響原來的對象。

這個對象在回滾中會被保存和恢復。

renpy.context_nesting_level() link

返回當前上下文的嵌套等級。最外層的上下文的等級是0(例如保存、讀取和回滾),非0等級其他上下文有菜單和重播等。

renpy.random link

這個對象是一個隨機數生成器,實現了 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 link

這些函數允許創作者使用Python的ctypes模組調用SDL中dll的函數。 Ren’Py不保證自身的SDL2版本包含所有功能特性。其他地方可以運行的函數也不一定能在Ren’Py裡運行,因此在實際使用前需要檢查對應函數是否為空。

renpy.get_sdl_dll() link

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

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

renpy.get_sdl_window_pointer() link

該函數返回(ctypes.c_void_p類型)主窗口坐標。主窗口沒有顯示或發生問題時,返回None>

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()

        SDL_GetWindowPosition(win, ctypes.byref(x), ctypes.byref(y))

其他林林總總 link

renpy.add_python_directory(path) link

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

renpy.add_to_all_stores(name, value) link

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

renpy.call_stack_depth() link

返回當前上下文(context)調用棧(stack)的深度——這個數表示調用棧中還沒有返回或彈出,但依然在運行的調用數量。

renpy.capture_focus(name='default') link

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

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

name

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

renpy.choice_for_skipping() link

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

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

  • 觸發自動保存。

renpy.clear_capture_focus(name='default') link

清除名為 name 的焦點捕獲。

renpy.clear_game_runtime() link

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

renpy.clear_keymap_cache() link

清空快捷鍵快取。該函數允許對 config.keymap() 的修改立刻生效,而不需要重啟Ren’Py。

renpy.context_dynamic(*vars) link

該函數可以將一個或多個變數作為入參。函數讓變數根據當前上下文(context)動態調整。當調用返回後,變數會重設為原來的值。

一個調用的樣例如下:

$ renpy.context_dynamic("x", "y", "z")
renpy.count_dialogue_blocks() link

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

renpy.count_newly_seen_dialogue_blocks() link

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

renpy.count_seen_dialogue_blocks() link

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

renpy.display_notify(message) link

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

renpy.dynamic(*vars, **kwargs) link

可以向該函數傳入一個或多個入參。該函數可以透過本地調用生成動態變數作用域。 調用該函數並返回時,對應的變數值將會被設置為傳入的值。

如果變數以關鍵字參數傳入,會根據變數名匹配並設置對應變數。

調用樣例為:

$ renpy.dynamic("x", "y", "z")
$ renpy.dynamic(players=2, score=0)
renpy.focus_coordinates() link

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

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

強制後台自動存檔。

take_screenshot

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

block

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

renpy.free_memory() link

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

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

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

transition

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

save

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

renpy.get_adjustment(bar_value) link

傳入一個 BarValue 對象 bar_value ,返回 ui.adjustment() 。adjustment對象定義了下列屬性(attribute):

value link

條(bar)的當前值。

range link

條(bar)的當前值域。

renpy.get_game_runtime() link

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

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

renpy.get_image_load_log(age=None) link

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

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

  • 載入圖像檔案名。

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

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

age

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

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

renpy.get_mouse_name(interaction=False) link

返回顯示滑鼠名稱。

interaction

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

renpy.get_mouse_pos() link

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

renpy.get_physical_size() link

返回物理窗口的尺寸。

renpy.get_refresh_rate(precision=5) link

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

precision

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

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

renpy.get_renderer_info() link

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

"renderer"

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

"resizable"

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

"additive"

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

"model"

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

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

renpy.get_say_attributes() link

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

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

renpy.get_skipping() link

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

renpy.get_transition(layer=None) link

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

renpy.iconify() link

遊戲窗口最小化。

renpy.include_module(name) link

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

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

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

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

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

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

該執行緒使用Ren’Py的API能做的事情非常受限。可以調用 renpy.queue_event() 修改儲存區的變數。 最好在主執行緒中使用其他Ren’Py的API。

該函數的主要用途是:通過web API創建第二執行緒,調用該函數修改儲存區變數,通過互動行為在界面上展示變數的變化。

然而該函數還無法在Web平台運行。

renpy.is_init_phase() link

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

renpy.is_mouse_visible() link

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

renpy.is_seen(ever=True) link

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

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

renpy.is_skipping() link

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

renpy.is_start_interact() link

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

renpy.language_tailor(chars, cls) link

該函數可用於替換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

renpy.load_module(name) link

該函數載入名為 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>') link

s 作為Ren’Py腳本載入。

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

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

renpy.maximum_framerate(t) link

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

renpy.munge(name, filename=None) link

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

filename

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

renpy.not_infinite_loop(delay) link

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

renpy.notify(message) link

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

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

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

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

renpy.pop_call() link

從調用棧(stack)彈出當前調用,並不再返回那個位置。

如果調用方決定不需要返回到那個腳本標籤(label)的情況下,可以使用該函數。

renpy.prediction() link

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

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

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

up

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

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

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

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

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

relaunch

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

status

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

renpy.quit_event() link

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

renpy.reset_physical_size() link

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

renpy.restart_interaction() link

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

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

renpy.screenshot(filename) link

將截螢幕保護程式存為 filename

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

renpy.screenshot_to_bytes(size) link

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

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

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

size

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

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

renpy.scry() link

返回當前語句的scry對象。

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

nvl_clear

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

say

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

menu_with_caption

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

who

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

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

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

duration

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

renpy.set_physical_size(size) link

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

renpy.shown_window() link

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

renpy.split_properties(properties, *prefixes) link

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

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

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

text_properties, button_properties = renpy.split_properties("text_", "")
renpy.substitute(s, scope=None, translate=True) link

對字串 s 應用多語言支持(translation)和新樣式格式。

scope

若不是None,格式中使用的scope,添加到默認儲存區。

translate

決定是否啟用何種語言支持。

返回多語言支持和格式的字串。

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

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

layer

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

always

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

renpy.vibrate(duration) link

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

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

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

message

顯示的提示消息。

yes

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

no

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