其他函數和配置變數 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.diff_memory(update=True) link

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

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

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

renpy.profile_memory(fraction=1.0, minimum=0) link

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

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

fraction
顯示使用記憶體總數的比例。1.0會顯示所有使用的記憶體,.9顯示最高的90%。
minimum
如果某個名稱的記憶體使用小於 minimum 字長,就不會顯示。

由於透過這個函數會掃描所有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_layer(layer, above=None, below=None, menu_clear=True) link

向界面添加一個新圖層。如果圖層已經存在,則不做任何事。

belowabove 必須提供至少一項。

layer
表示添加的新圖層名稱的字串。
above
如果不是None,表示被新圖層覆蓋的圖層的名稱字串。
below
如果不是None,表示覆蓋在新圖層上的圖層的名稱字串。
menu_clear
若為True,進入遊戲菜單上下文(context)時會清空這個圖層,並在離開××××時恢復。
renpy.add_python_directory(path) link

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

renpy.call_stack_depth() link

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

renpy.choice_for_skipping() link

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

  • 如果Ren’Py正在跳過(skip),並且“跳過後面選項”設置為停止跳過,那麼跳過就會終止。
  • 觸發自動保存。
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.focus_coordinates() link

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

renpy.force_autosave(take_screenshot=False) link

強制自動存檔。

take_screenshot
若為True,進行新的截圖。若為False,使用已存在的截圖。
renpy.force_full_redraw() link

強制界面完全重繪。直接使用pygame重繪界面之後需要調用這個函數。

renpy.free_memory() link

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

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

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

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

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

value link

條(bar)的當前值。

range link

條(bar)的當前值域。

renpy.get_autoreload() link

獲得自動載入標識(flag)。

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_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。

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

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.invoke_in_thread(fn, *args, **kwargs) link

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

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

renpy.is_init_phase() link

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

renpy.is_seen(ever=True) link

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

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

renpy.is_start_interact() link

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

renpy.load_module(name, **kwargs) 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 is the name of the filename that statements in the string will appear to be from.

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),比如截圖和快速保存,這個函數很有效。

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

renpy.pause(delay=None, music=None, with_none=None, hard=False, checkpoint=None) link

讓Ren’Py暫停。如果用戶點擊並結束了這個暫停,暫停超時或被跳過,這個函數會返回True。

delay
Ren’Py暫停的時間,單位為秒。
music
出於相容性考量而保留的參數。
with_none
決定暫停的結尾是否執行一個“with None”分句。
hard
若為True,點擊就不會打斷暫停。謹慎使用,因為很難區分硬性暫停和程序卡死。
checkpoint
若為True,會設置一個檢查點(checkpoint),用戶可以回滾到這個語句。若為False,不會設置檢查點(checkpoint)。若為None,僅當設置了 delay 後才會設置檢查點(checkpoint)。
renpy.pop_call() link

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

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

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

讓Ren’Py保存遊戲,重新載入腳本,並載入存檔。

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對象只有一個欄位(field):

nvl_clear
如果在下一個交互行為之前會執行一個 nvl clear 則為True。
renpy.set_autoreload(autoreload) link

設置自動重新載入標識(flag)。這個標識決定在文件發生變化後遊戲是否會自動重新載入。自動重新載入不是完全啟用,直到遊戲使用 renpy.utter_restart() 重新載入之後。

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