命令行交互界面

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