制作模块:从调研到发布

制作可靠游戏模块的完整流程:调研、用真实服务器测试、可移植运行时、隔离运行、控制台模式以及在真实 PC 上测试。

制作模块:从调研到发布

模块开发指南 说明模块包含什么。本页说明如何制作能在真实 PC 上运行的模块。

通过了全部单元测试的模块,在真实服务器上仍可能失败。Terraria 模块就是一个例子。它通过了全部单元测试和一致性检查,但在真实服务器上出现了 9 个缺陷。本页给出在发布前找出这类缺陷的流程。


1. 设计原则

以下原则适用于所有模块。

  • 工作由守护进程完成。 模块只描述游戏。不要绕过守护进程的契约。如果契约缺少你需要的功能,先在守护进程中添加通用扩展点。
  • 不要按游戏名称分支。 守护进程和公共辅助函数中没有游戏名称。使用 module.toml 的键、钩子和插槽。
  • 处处使用相同的运行环境。 不要使用 PC 上已安装的运行时。模块下载固定版本的运行时并放到服务器文件夹中(第 5 节)。
  • 每个值只放在一个地方。 设置的默认值来自一个文件:游戏生成的文件,或下载包中附带的示例文件。
  • 所有面向用户的文字都放在 locales/。 en.json 是基准文件。

2. 调研游戏

写代码之前,在 <game>/RESEARCH.md 中建立调研表。为每一项写出来源,并注明来源是文档还是实测。找不到来源的项留空,写上“未确认”。不要猜测数值。

项目去哪里找
服务器可执行文件、启动参数、默认端口官方文档、服务器帮助、下载包中的启动脚本
全部命令及其参数官方命令文档和服务器 help 命令的输出。逐行对照两者
全部设置(键、格式、范围、默认值)服务器生成的默认设置文件。服务器不生成时,用下载包中的示例文件
设置文件的语法和编码该文件的原始字节
世界存档和游戏生成的备份启动服务器并保存世界后的文件列表
就绪、停止、加入、离开消息控制台的原始输出。还要确认服务器的语言设置是否会翻译这些消息
安装方式和文件校验官方下载地址和官方校验和。没有校验和时,写“无”和来源
运行前提(运行时)服务器可执行文件的引用列表和官方文档。找出下载包中没有的东西
实例文件夹以外的文件运行服务器后主文件夹和文档文件夹的变化

Wiki 可能描述的是旧版本。Terraria Wiki 列出了 death 命令,但 Terraria 1.4.5.8 服务器对它的回答是“Invalid command.”。


3. 检查真实文件

如果能下载服务器,就亲自检查文件。

  1. 列出压缩包的全部条目。确认是否每个操作系统各有一个文件夹,以及同一个可执行文件名是否出现在多个文件夹中。Terraria 的压缩包在 Linux/ 和 Windows/ 文件夹中都有 TerrariaServer.exe。
  2. 按字节读取默认文件。确认编码(UTF-8、BOM、cp1252)、换行符(LF、CRLF)、注释掉的示例键,以及不是注释的行。
  3. 把注释掉的示例键也加入设置列表。不是注释的行给出默认值。

4. 运行真实服务器

用与守护进程相同的方式启动服务器:通过管道连接 stdin 和 stdout,并记录原始输出。即使构建环境只能运行其他操作系统版本的服务器,也要运行它。游戏代码相同时,命令、消息和保存行为都相同。

记录以下内容:

  • 就绪行、停止命令之后的行,以及保存所需时间。
  • help 的输出。逐个发送只有文档提到的命令,并记录回答。
  • 控制台提示符。有些服务器输出提示符时不换行,下一行就以提示符开头。Terraria 输出 : Server started。
  • 通过管道发送命令后的回答。服务器不回答时,用伪控制台再试(第 7 节)。
  • 服务器每种语言下的就绪和停止消息。
  • 服务器启动和保存时生成的文件。Terraria 会生成 world.wld.bak 和 world.wld.bak2。

加入消息、踢出对象等需要游戏客户端才能测的项留空,写上“未实测”。


5. 运行前提:固定版本、可移植

有些服务器需要下载包中没有的运行时,例如 Java、XNA Framework 或 Visual C++ 运行时。不要使用 PC 上已安装的运行时,因为每台 PC 上的版本可能不同。

按以下步骤操作:

  1. 在调研表中写下官方运行时文件的地址、大小、签名和 SHA-256。
  2. 找出服务器所需的最小文件集合。只放这些文件启动服务器来确认。Terraria 需要 4 个 XNA 程序集(Microsoft.Xna.Framework、.Game、.Graphics、.Xact)、XnaNative.dll、msvcr100.dll 和 msvcp100.dll。
  3. 在 install_server 中下载固定版本,并与官方校验和比较。没有官方校验和时,与从发布者签名有效的文件记录下来的 SHA-256 比较。
  4. 只把需要的文件放到服务器文件夹或实例文件夹,并用该路径启动服务器。
  5. 在 validate 中查找这些文件。缺少任何一个时,返回带有 severity: "critical" 和专用 code 的问题,并提示用户重新安装服务器。

不要使用管理员权限、全系统安装或 Windows 服务。

限制: 当全局程序集缓存(GAC)中有同名同版本的程序集时,.NET Framework 会先从 GAC 加载。原生 DLL 会先从服务器文件夹加载。


6. 隔离运行

在 Windows 上,不是来自 Saba-chan 签名目录的模块会在 Windows AppContainer 中运行。新制作的模块都在这种隔离中运行。打开 pull request 之前,先在隔离运行中测试模块。

隔离运行中不能使用以下内容:

不能使用改用
回环连接(守护进程 API、游戏服务器 REST API)daemon_stdin_command、daemon_rest、loopback_http、loopback_exchange。由守护进程转发请求
Windows Installer(msiexec 以错误 1601 失败)和其他服务用 Python 直接读取安装文件(MSI、CAB)
tempfile.mkdtemp 在实例文件夹中创建的文件夹tempfile.mkstemp,或用 os.mkdir 创建的文件夹。从 Python 3.13 起,mkdtemp 只给当前用户权限,隔离账户无法写入该文件夹
在允许的文件夹之外写入实例文件夹、工作文件夹、安装文件夹,以及 data_roots 中声明的文件夹

如果公共辅助函数在隔离运行中失败,不要在模块里绕过,把它作为守护进程的问题报告。


7. 控制台模式

守护进程默认通过管道连接服务器的 stdin 和 stdout([launch] console = "pipe")。有些服务器在 stdin 是管道时行为不同:

  • Palworld 会把输出攒到停止时才输出。
  • Terraria 的 Windows 服务器不读取管道输入。它对命令和 exit 都没有回答,守护进程在 60 秒后未保存就强制结束了它。

对这类服务器,设置 [launch] console = "pty"。守护进程会在伪控制台(Windows ConPTY、Unix pty)中启动服务器。

伪控制台会回显发送的每条命令,换行位置也可能改变。在伪控制台中,Terraria 把提示符 : 和 Server started 输出在不同的行。编写模式时要兼顾两种情况。


8. 控制台模式匹配

就绪、加入、离开、停止的模式只根据实测的原始输出编写。

  • 就绪、加入、离开的模式放在 [extensions.saba-core](ready_patterns、player_join_patterns、player_leave_patterns),停止的模式放在 [detection] graceful_exit_patterns。
  • 把每个模式锚定在行首和行尾。包含相同文字的聊天行(例如 <Server> Server started)不能匹配。
  • 如果消息前可能有提示符,用 ^(?:<提示符>)? 接受它。
  • 如果服务器的语言设置会翻译消息,就加入每种语言实测到的消息。只加英文的话,守护进程无法识别设置为其他语言的服务器的就绪状态。
  • 加入测试。实测行无论有没有提示符都应匹配,聊天行不应匹配。

9. 安装与设置文件

安装:

  • 压缩包中每个操作系统各有一个文件夹时,按操作系统名称选择文件夹。不要按可执行文件名、路径长度或第一个条目来选。找不到文件夹或找到多个时,返回失败。
  • 不要覆盖已有的设置和世界。只有在还没有设置文件时,才解压示例设置文件。
  • 校验每个下载的文件。每个二进制文件都使用官方校验和。没有官方校验和时,用指向固定官方主机的 HTTPS、压缩包 CRC 和预期可执行文件是否存在来确认,并在调研表中写上“无官方校验和”和来源。不要编造校验和,也不要使用社区来源的校验和。

设置文件:

  • 用该格式的官方语法读写文件。例如 Java .properties 文件有 \: 和 \= 转义,行尾的 \ 表示续行。
  • 不要假定编码。用文件的真实编码读取,并用相同的编码和换行符写回。Terraria 的 Windows 版 serverconfig.txt 使用 cp1252,注释中有字节 0x92。只按 UTF-8 读取的模块既无法启动该服务器,也无法保存或导入其设置。
  • 只修改变化了的键,保留其他键、注释和顺序。
  • 读不了文件就不要写。文件不存在、无法读取、无法解析是三种不同的情况。

10. 测试

单元测试和一致性套件在没有隔离的情况下用示例文件运行,因此找不到只在真实下载、隔离运行、控制台模式或 Windows 上出现的问题。三个层次的测试都要做。

10.1 单元测试

  1. 在写函数之前,先在 test_lifecycle.py 中为它写测试。
  2. 运行测试,确认它失败。
  3. 编写函数。
  4. 运行以下检查:
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules

10.2 真实服务器测试(pull request 之前)

完成第 4 节后,在真实的服务器文件夹上调用模块函数。

  1. 用真实下载运行 install_server。确认文件夹中只有本操作系统的文件。
  2. 用 get_launch_command 给出的命令启动服务器。确认就绪模式能匹配。
  3. 逐个发送命令模板。确认服务器接受。
  4. 发送停止命令。确认服务器保存后退出。
  5. 把 backup_paths 和 reset_server 的路径与服务器生成的文件进行比较。

10.3 真实 PC 测试

使用 Windows PC 上常规安装的 Saba-chan。新模块在隔离中运行,所以这项测试也能发现隔离运行的问题。

  1. 把模块文件夹复制到 Saba-chan 数据文件夹的 modules\<名称>\。
  2. 运行 saba-chan-cli module refresh。
  3. 运行 saba-chan-cli server add <服务器> -m <模块>。
  4. 启动服务器。确认 Saba-chan 显示就绪状态。
  5. 用 saba-chan-cli run <服务器> <命令> 发送命令,用 saba-chan-cli server console <服务器> --print 查看回答。
  6. 修改一项设置并重启服务器。确认服务器使用了新值。
  7. 用 saba-chan-cli backup create <服务器> 创建备份,检查备份中的文件。
  8. 停止服务器。确认 Saba-chan 记录为正常停止,世界存档仍在。
  9. 重置世界。检查删除了哪些文件、保留了哪些文件。

如果 [module.dependencies] saba-core 要求尚未发布的版本,常规安装不会加载该模块。等该版本发布后再做 PC 测试。不要降低依赖版本。


11. pull request 前的检查清单

  • RESEARCH.md 的每一项都有来源,并且每个来源都标明“文档”或“实测”。
  • 检查过压缩包条目和默认文件的原始字节。
  • 运行过真实服务器,并记录了原始输出、help 输出和保存后的文件。
  • 声明的每条命令都在 help 输出中。
  • 服务器会回答命令。如果不回答,已设置 [launch] console = "pty"。
  • 每个控制台模式都来自实测输出,并接受提示符和各语言的翻译。
  • 每个运行时都是固定版本的可移植文件,模块会校验下载的文件。
  • 安装只解压本操作系统的文件夹。
  • 设置文件保持原有编码和换行符。
  • 重置世界只删除服务器生成的文件(包括游戏生成的备份)。
  • 模块不使用 msiexec、Windows 服务、mkdtemp 文件夹或直接的回环连接。
  • 做过真实服务器测试和真实 PC 测试,或记录了没能做的测试。