命令行互動界面

Ren’Py包含一個命令行互動界面(CLI)，可用於自動處理某些開發任務，允許持續集成和腳本打包。 但對於大多數需求，都不必用到CLI——Ren’Py啟動器就可以完成大部分任務。

本頁文件中的例子，都假設創作者在Ren’Py SDK目錄下運行CLI(即包含renpy.py、renpy.sh和renpy.exe的目錄)。 後續內容分別為Linux、macOS和Windows操作系統提供了樣例。

CLI目前還不穩定。不同版本Ren’Py的CLI可能會有很大差異。本頁內容基於Ren’Py 8.5.3。

快速任務

下列這些快速工作流可以“複製黏貼”之後用作新任務的起點。新建任務之需要替換一些文件路徑和語言編碼。

運行項目

cd /path/to/renpy
./renpy.sh /path/to/project run

構建發行版

使用啟動器工具構建桌面電腦系統(Windows/macOS/Linux)的發行版。

cd /path/to/renpy
./renpy.sh launcher distribute /path/to/project --destination /path/to/output

生成/更新翻譯文件

生成或更新翻譯文件，並為翻譯人員導出對話和字串。

cd /path/to/renpy
./renpy.sh /path/to/project translate french
./renpy.sh /path/to/project dialogue french --strings

語法

Note

本頁內容關注點如下：

  • <name> 表示需要替換的值，比如項目路徑或語言編碼。

  • [item] 是可選內容，不強制使用。

./renpy.sh [global options...] [<basedir>] [<command>] [command options...]
<basedir>
Default:

Ren’Py可執行程序(啟動器)所在目錄。

後續的命令中，<basedir>表示項目的基礎目錄。

<command>
Default:

run

指定要執行的命令。

全局可選項

下列標誌位可以用在任何命令中：

--savedir <directory>

指定目錄用於存放存檔文件和持久化數據。

--trace <level>

指定Ren’Py寫入trance.txt的日誌追蹤等級。(1=每次調用，2=每行)

--version

顯示使用的Ren’Py版本號。

--compile

運行前強制所有 .rpy 文件重新編譯。

--compile-python

強制所有Python文件重新編譯，不讀取 game/cache/bytecode-*.rpyb。

--keep-orphan-rpyc

編譯時，若存在與 .rpy 或 _ren.py 檔案名不同的 .rpyc 文件，則要求Ren’Py保留這些文件。

--errors-in-editor

使用文本編輯器打開報錯日誌。

--safe-mode

強制Ren’Py使用安全模式運行，允許玩家配置圖形選項。

--help, -h

顯示幫助資訊，包括命令和語法。該命令會顯示最新的命令資訊。

Ren’Py可以把遊戲相關資訊寫入一個標準Json文件。 下列可選項可以讓創作者設置文件資訊和文件內容。

--json-dump <file>

指定Json檔案名。

--json-dump-private

Json文件中包含私有變數名。(私有變數以下劃線 _ 開頭)

--json-dump-common

Json文件中包含在通用目錄中定義的變數名。

Note

不同版本中的命令行有所區別。若需要查看最新版本的命令和標識，可以運行：

./renpy.sh --help

若要查看特定命令的最新版標識，運行：

./renpy.sh <basedir> <command> --help

核心工作流命令

run命令

正常運行當前項目的命令。在沒有其他命令的情況下，這是預設會執行的命令。

./renpy.sh <basedir> run [options...]
--profile-display

匯報繪製整個螢幕的耗時。

等效於 config.profile 設置為True。

--debug-image-cache

將 image cache 資訊寫入 image_cache.txt 文件。

等效於 config.debug_image_cache 設置為True。

--warp <filename:linenumber>

嘗試跳轉到指定的某一行。需要的參數是一對 filename:linenumber (檔案名:行號)。

The warp feature requires config.developer to be True to operate. 需要將 config.developer 設置為True才能執行 跳轉 命令。

quit命令

立刻退出遊戲的命令。

./renpy.sh <basedir> quit

compile命令

編譯遊戲，根據 .rpy 文件創建 .rpyc 文件。 等效於Ren’Py啟動器中的“強制重新編譯”按鈕。

./renpy.sh <basedir> compile [--keep-orphan-rpyc]
--keep-orphan-rpyc

編譯時，若存在與 .rpy 或 _ren.py 檔案名不同的 .rpyc 文件，則要求Ren’Py保留這些文件。

director命令

啟動 互動式編導器(interactive director) 並運行遊戲。

./renpy.sh <basedir> director

rmpersistent命令刪除持久化數據

刪除 持久化數據 。使用該命令可以處理持久化數據分散在多個地方的情況：

./renpy.sh <basedir> rmpersistent

Warning

該命令會重設遊戲進度，包括解鎖內容、已讀資訊和配置項。

update命令

從某個web伺服器下載和安裝Ren’Py遊戲更新內容。詳見 HTTPS/HTTP更新器 。

此命令使用的參數與 updater.update() 方法的參數一致。

./renpy.sh <basedir> update <url> [options...]
<url>

指定 updates.json 文件的URL。

--base <directory>

指定待更新遊戲的基礎目錄。預設值為當前遊戲。

--force

即使版本號相同也強制更新。

--key <key>

用於更新的公鑰文件。

--simulate <option>

運行模擬模式，用於測試更新GUI，實際不執行更新。 該項的可選值包括，available、 not_available 和 error。

Warning

更新會修改遊戲內的文件。使用時請謹慎。

驗證與測試命令

lint命令檢查腳本

該命令會在當前遊戲項目運行 Lint 並產生報告。運行lint會檢查腳本錯誤並列印統計資訊。 等效於啟動器的“使用Lint檢查腳本”功能。

./renpy.sh <basedir> lint [<filename>] [options...]
<filename>

若指定該參數，lint會將檢查結果寫入指定文件，而不使用標準輸出列印結果。

--error-code
若出現lint報錯，則退出並返回錯誤代碼1。在使用持續集成(CI)系統中使用Lint時，該項會很有用。
--no-orphan-tl

不報告在翻譯文件中存在但找不到對應主語言文本的翻譯條目。

--reserved-parameters

報告Ren’Py語句參數中使用Ren’Py或Python預留的變數名。

主要用於尋找 label、 screen 和 ATL 語句中可能誤用預留變數名的情況。

--by-character

報告每個角色對話的段落、(英語)單字和字元的總數。

--check-unclosed-tags

報告未閉合的text文本標籤。

--all-problems

報告某個類型的全部問題，而不是預設的僅限前10個問題。

運行測試案例

test命令可以對某個遊戲進行 自動化測試。

樣例腳本：
./renpy.sh <basedir> test [<testcase>] [options...]

這條命令可以讓遊戲運行 自動測試樣例 <testcases> 文件。

<testcase>

運行的測試樣例或測試套件名稱。若未指定，默認運行“global”測試套件。

--enable_all

若啟用該項，將忽略 enable 特性並執行所有測試樣例和測試套件。

--overwrite_screenshots

若啟用該項，運行 screenshot語句 產生的截圖將覆蓋已存在的截圖文件。

--hide-header

若啟用該項，測試樣例的開頭部分會被禁用。

--hide-execution [no|hooks|testcases|all]

若啟用該項，測試結果會被隱藏。--hide-execution hooks 會隱藏hooks部分，--hide-execution testcases 會隱藏測試樣例和hooks部分， --hide-execution all 則隱藏所有結果。

--hide-summary

若啟用該項，測試結果結尾的總結將會被禁用。

--report-detailed

若啟用該項，運行測試時每條測試明細都會被顯示。

--report-skipped

若啟用該項，被跳過的測試資訊會被顯示。該項應與 --report-detailed 一起使用。

構建與發布

Note

作為構建流程的一部分，Ren’Py會創建包含遊戲載入資訊的 .rpyc 文件。 一個持續集成系統應該在生成完成後保留這些 .rpyc 文件，在下個生成中直接應用這些文件，或移動到old-game目錄裡。 不這樣做可能會導致遊戲無法讀檔。

add_from命令

向每個不包含 from 從句的 call語句 添加一個 from 從句。 一般情況下，這步應該在生成正式版(release版)之前完成，這會修改遊戲程序，以幫助Ren’Py準確定位到每個call語句的返回點。

可選項為 --compile。

./renpy.sh <basedir> add_from

Warning

這條命令會修改遊戲腳本文件。

distribute命令

為Windows、macOS和Linux系統 構建發行版。

./renpy.sh launcher distribute <basedir> [options...]
--destination <directory>

指定發布目錄。預設使用當前目錄下名為 “name-version-dists” 的子目錄，其中的name和version分別使用 build.name 和 build.version。

--format <format>

強制使用指定的格式進行構建。

--macapp <app>

指定用於簽署Mac套裝軟體的macapp路徑，而非Ren’Py自帶的macapp。

--no-archive

不會將文件添加到 歸檔文件 中。

--no-update

不生成更新文件，即禁用 HTTPS/HTTP更新器。

--package <package>

指定打包類型，package參數可以是“pc”、“mac”或“markets”。該選項可以有多個參數，依次生成不同類型的打包文件。 默認則會生成所有類型的打包文件。

--packagedest <package>

指定輸出包體名稱(不包含副檔名)。需要先指定1個 --package.

android_build命令

該命令會生成一個遊戲的 安卓(Android) 版本。需要啟動器已經安裝了安卓SDK，生成了金鑰併合理配置過整個項目。

./renpy.sh launcher android_build <basedir> [options...]
--destination <directory>

輸出目錄。默認目錄為當前目錄下名為 “name-version-dists” 的子目錄。 版本號version從 build.name 和 build.version 獲取。

--bundle

使用該選項後，Ren’Py會生成一個 .aab 包。如果不使用該選項，Ren’Py會生成 .apk 文件。

--install

使用該選項後，Ren’Py會在連接設備上直接安裝 .apk 或 .aab 文件。

--launch

使用該選項後，Ren’Py會在連接設備上運行遊戲。該選項會與 --install 一起使用。

--package <package>

指定構建的包名稱。默認構建的包名為“android”。

ios_create命令

創建一個Xcode項目，用於構建遊戲的 iOS 版本。此命令執行前需要在啟動器上安裝iOS的相關支持。

./renpy.sh launcher ios_create <basedir> <destination>
<basedir>

指定Ren’Py項目路徑。

<destination>

指定創建iOS項目(Xcode)的路徑。

ios_populate命令

將遊戲複製到某個使用 ios_create 生成的Xcode項目。 在使用相同Ren’Py版本的前提下，該命令可用於項目更新。

./renpy.sh launcher ios_populate <basedir> <destination>
<basedir>

指定Ren’Py項目路徑。

<destination>

指定待更新的項目目錄。

web_build命令

生成一個遊戲的Web發布版。 此命令執行前需要在啟動器上安裝web的相關支持，並且所有設定檔(例如 progressive_download.txt)都已放在合適位置。

./renpy.sh launcher web_build <basedir> [options...]
--destination <directory>

指定Web版包文件目錄位置。

--launch

構建完成後啟動一個web伺服器並啟動遊戲。

多語言支持和在地化

See also

translate命令

為某個項目創建或更新 tl/<language> 目錄中的翻譯文件。 該命令會在保留已存在的多語言入口(entry)的情況下添加缺少的對話和字串入口。

./renpy.sh <basedir> translate <language> [options...]
<language>

指定生成翻譯文件的語言名。

--count

不生成文件，只列印缺少的翻譯入口統計數。

--rot13

生成翻譯文件時使用rot13加密。

--piglatin

生成翻譯文件時使用pig latin加密。該項會被 --rot13 覆蓋。

--empty

生成翻譯文件時內部只填寫空字串。該項會被 --rot13 和 --piglatin 覆蓋。

--min-priority <int>

翻譯文件內的字串優先度將大於該值。

--max-priority <int>

若 config.translate_launcher 為True，該項使用預設值499。 否則該項的值為299。

翻譯文件內的字串優先度將小於該值。

--strings-only

翻譯文件內只有字串(沒有對話)。

--common-only

翻譯文件內只有正常編碼的字串。

--no-todo

生成的翻譯文件開頭沒有TODO標識內容。

--string <string>

指定翻譯文件中的一個字串。該選項可以出現多次，分別指定不同的字串。

dialogue命令

默認情況下將對話導出到 dialogue.tab 文件。如果使用了選項 --text 則導出到 dialogue.txt 文件。

如果選擇了目標語言，輸出中會有對應語言的文本。否則只輸出源語言。

./renpy.sh <basedir> dialogue <language> [options...]

Note

該命令是一個導出/報告式命令，本身不會創建 tl/<language> 文件。

<language>

指定生成對話的源語言。

--text

將對話輸出為純文本。若未指定該項，則輸出製表符分隔的文件。

--strings

輸出對話和所有待翻譯的字串。 此處輸出的大多數字串多是在 _() 和 __() 開頭的函數以及 分支選項菜單 中定義的。

--notags

剔除對話中的文本標籤。

--escape

轉義引號等特殊字元。

extract_strings命令

將遊戲中已存在的多語言導出到一個Json文件中。

./renpy.sh <basedir> extract_strings <language> <destination> [options...]
<language>

指定生成待翻譯字串的源語言。

<destination>

指定輸出的Json文件。

--merge

輸出結果與當前文件的內容合併，不覆蓋已有內容。

--force

如果源語言不存在時不拋異常。

merge_strings命令

從Json文件導入多語言到遊戲中。

可選項 --compile 。

./renpy.sh <basedir> merge_strings <language> <source> [options...]
<language>

指定待合併的目標語言。

<source>

指定讀取的Json文件。

--reverse

反轉Json文件中的源語言和目標語言關係。

--replace

替換非平凡(non-trivial)的語言。平凡(trivial)語言是指，不存在的語言類型或與主語言相同的語言類型。

啟動器命令

這些命令可用於在CLI中控制Ren’Py啟動器。

generate_gui命令

為某個已存在的Ren’Py遊戲項目生成一套GUI。

./renpy.sh launcher generate_gui <basedir> [options...]
--width <width>
Default:

1280

指定GUI的畫面寬度。

--height <height>
Default:

720

指定GUI的畫面高度。

--accent <color>
Default:

#00B8C3

指定GUI的高亮顏色。

--boring <color>
Default:

#000000

指定GUI背景的單色。

--light

採用亮色主題。

--template <directory>
Default:

“gui”

指定一個包含模板原始碼的目錄。

--language <language>
Default:

None

指定一種語言作為內建字串和注釋的預設語言。

--start

創建一個新項目，替換當前圖片和代碼。

--replace-images

覆蓋已存在的圖片。

--replace-code

覆蓋已存在的 gui.rpy 文件。

--update-code

更新已存在的 gui.rpy 文件。

--minimal

值更新 option.rpy 和多語言支持部分。

gui_images命令

基於 GUI變數 生成圖片(例如按鈕、條、多選按鈕等)。

./renpy.sh launcher gui_images <basedir> [options...]

get_projects_directory命令

列印Ren’Py啟動器用於存放項目的目錄。

./renpy.sh launcher get_projects_directory

set_projects_directory命令

設置Ren’Py啟動器儲存項目的目錄。該選項適用於某些簡化的系統上運行Ren’Py，那些系統上可能無法透過其他方式選擇項目目錄。

只有未運行啟動器時，此命令才會生效。

./renpy.sh launcher set_projects_directory <projects>
<projects>

指定項目目錄的路徑。

set_project命令

將當前項目設置為指定項目。該命令會項目目錄改為啟動器當前選中的目錄。

只有未運行啟動器時，此命令才會生效。

./renpy.sh launcher set_project <project>
<project>

需要設置為當前項目的項目完整路徑。

update_old_game命令

將 <basedir>/game 中的 .rpyc 文件複製到 <basedir>/old-game 。

./renpy.sh launcher update_old_game <basedir>

See also

自訂命令

除了上述預定義的命令之外，還可以針對特定項目使用 renpy.arguments.register_command() 函數創建自訂命令。

當需要運行一條命令時，遊戲首先需要初始化，然後再實際運行對應的命令。

renpy.arguments.register_command(name, function, uses_display=False)

註冊一條命令，可以在Ren’Py命令行模式下調用該命令。 命令運行時，講以無參數形式調用 function。

name
Type:

str

指定命令名稱。

function
Type:

function

指定命令運行時調用的函數。以無參形式調用 function 。

如果 function 需要命令行中傳入參數，就要生成一個 renpy.arguments.ArgumentParser 實例對象並調用 parse_args() 處理該實例對象。若不需要傳入參數，默認調用 renpy.arguments.takes_no_arguments()。

如果 function 返回結果為True，Ren’Py會繼續正常流程。否則，Ren’Py命令行會退出。

See also

關於命令行的處理，詳見 ArgumentParser文件。

uses_display
Type:

bool

若為True，Ren’Py會初始化顯示設置。若為False，Ren’Py會啟動模擬影音驅動。

樣例

init python:

    def compute_area_command():
        ap = renpy.arguments.ArgumentParser(description='Compute the area of various shapes.')
        ap.add_argument("dimensions", nargs="*", type=float, help="The dimension of the shape.")
        ap.add_argument("--square", action="store_true", help="If given, compute the area as a square.")
        ap.add_argument("--rectangle", action="store_true", help="If given, compute the area as a rectangle.")
        ap.add_argument("--circle", action="store_true", help="If given, compute the area as a circle.")

        args = ap.parse_args()

        if args.square:
            print(f"Square: {args.dimensions[0] ** 2}")

        elif args.rectangle:
            print(f"Rectangle: {args.dimensions[0] * args.dimensions[1]}")

        elif args.circle:
            print(f"Circle: {3.14 * args.dimensions[0] ** 2}")

        # Terminate and do not run Ren'Py normally
        return False

    renpy.arguments.register_command("compute_area", compute_area_command)

註冊的命令可以按下列方式調用：

> ./renpy.sh <basedir> compute_area 3 --square

Square: 9.0

> ./renpy.sh <basedir> compute_area 3 2 --rectangle

Rectangle: 6.0

> ./renpy.sh <basedir> compute_area 1 --circle

Circle: 3.14

> ./renpy.sh <basedir> compute_area --help