其他函數和配置變數 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)。