Building a Module: Research to Release

The full procedure to build a reliable game module: research, tests on the real server, portable runtimes, the sandbox, console modes, and tests on a real PC.

Building a Module: Research to Release

The Module Development Guide tells you what a module contains. This page tells you how to build a module that works on a real PC.

A module that passes all unit tests can still fail on a real server. The Terraria module is an example. It passed every unit test and every conformance check. On a real server, it had nine defects. This page shows the procedure that finds those defects before a release.


1. Design Rules

These rules apply to every module.

  • The daemon does the work. A module only describes a game. Do not go around the daemon contract. If the contract does not have a feature that you need, add a general extension point to the daemon first.
  • Do not branch on a game name. The daemon and the shared helpers do not contain game names. Use module.toml keys, hooks, and slots.
  • Keep one execution environment everywhere. Do not use a runtime that is installed on the PC. The module downloads a fixed version of the runtime and puts it in the server folder (section 5).
  • Keep each value in one location. The default value of a setting comes from one file: the file that the game makes, or the example file in the download.
  • Put all user text in locales/. en.json is the reference file.

2. Research the Game

Make a research table in <game>/RESEARCH.md before you write code. For each item, write the source. Also write if the source is a document or a measurement. If you cannot find a source, leave the item empty and write "not verified". Do not guess a value.

ItemWhere to find it
Server executable, launch arguments, default portsOfficial documents, the server help text, the start scripts in the download
All commands and their argumentsOfficial command documents and the output of the server help command. Compare the two line by line
All settings (key, format, range, default)The default settings file that the server makes. If the server does not make one, use the example file in the download
Syntax and encoding of the settings fileThe raw bytes of that file
World saves and the backups that the game makesThe file list after you start the server and save the world
Ready, stop, join, and leave messagesThe raw console output. Also find out if the server language setting translates these messages
Install method and file verificationThe official download address and the official checksum. If there is no checksum, write "none" and the source
Runtime requirementsThe references of the server executable and the official documents. Find what the download does not include
Files outside the instance folderChanges in the home folder and the documents folder after a server run

A wiki can describe an old version. The Terraria wiki lists a death command. The Terraria 1.4.5.8 server replies "Invalid command." to it.


3. Examine the Real Files

If you can download the server, examine the files yourself.

  1. Show all entries of the archive. Find out if the archive has a folder for each operating system. Find out if the same executable name is in more than one folder. The Terraria archive has TerrariaServer.exe in the Linux/ folder and in the Windows/ folder.
  2. Read the default files byte by byte. Find the encoding (UTF-8, BOM, cp1252), the line endings (LF, CRLF), the example keys in comments, and the lines that are not comments.
  3. Add the example keys in comments to the settings list. A line that is not a comment gives the default value.

4. Run the Real Server

Start the server in the same way as the daemon: connect stdin and stdout through pipes. Record the raw output. If your build environment can only run a server build for a different operating system, run that build. The commands, the messages, and the save behavior are the same when the game code is the same.

Record these items:

  • The ready line, the line after the stop command, and the time that a save takes.
  • The output of help. Send each command that only a document mentions, and record the reply.
  • The console prompt. Some servers write the prompt without a line break. The next line then starts with the prompt. Terraria writes : Server started.
  • The reply to a command that you send through the pipe. If the server does not reply, test it again with a pseudo console (section 7).
  • The ready and stop messages for each server language.
  • The files that the server makes when it starts and saves. Terraria makes world.wld.bak and world.wld.bak2.

Some items need a game client, for example join messages and a kick target. Leave these items empty and write "not measured".


5. Runtime Requirements: Portable and Fixed

Some servers need a runtime that the download does not include, for example Java, XNA Framework, or the Visual C++ runtime. Do not use a runtime that is installed on the PC. A runtime on the PC can have a different version on each PC.

Use this procedure:

  1. Write the address, size, signature, and SHA-256 of the official runtime file in the research table.
  2. Find the smallest set of files that the server needs. Start the server with only those files to confirm the set. For Terraria, the set is the four XNA assemblies (Microsoft.Xna.Framework, .Game, .Graphics, .Xact), XnaNative.dll, msvcr100.dll, and msvcp100.dll.
  3. In install_server, download the fixed version. Compare the file with the official checksum. If there is no official checksum, compare it with a SHA-256 that you recorded from a file with a valid publisher signature.
  4. Put only the necessary files in the server folder or the instance folder. Start the server with that path.
  5. In validate, look for these files. If a file is missing, return an issue with severity: "critical" and a dedicated code. Tell the user to install the server again.

Do not use administrator rights, a system-wide install, or a Windows service.

Limit: .NET Framework loads an assembly from the global assembly cache (GAC) first when the GAC has the same name and version. Native DLLs load from the server folder first.


6. The Sandbox

On Windows, a module that is not in the signed Saba-chan catalog runs in a Windows AppContainer. Every new module runs in this sandbox. Test your module in the sandbox before you open a pull request.

The sandbox blocks these items:

BlockedUse this
Loopback connections (the daemon API, the game server REST API)daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. The daemon relays the request
Windows Installer (msiexec fails with error 1601) and other servicesRead the installer file (MSI, CAB) with Python
A folder that tempfile.mkdtemp makes in the instance foldertempfile.mkstemp, or a folder that you make with os.mkdir. In Python 3.13 and later, mkdtemp gives access only to the current user. The sandbox account cannot write in that folder
Writes outside the allowed foldersThe instance folder, the working folder, the install folder, and the folders in data_roots

If a shared helper fails in the sandbox, do not go around the failure in the module. Report the failure as a daemon problem.


7. Console Modes

By default, the daemon connects the server stdin and stdout through pipes ([launch] console = "pipe"). Some servers operate differently when stdin is a pipe:

  • Palworld keeps its output until it stops.
  • The Terraria Windows server does not read input from a pipe. It did not reply to commands or to exit. The daemon stopped it with a forced kill after 60 seconds, without a save.

For these servers, set [launch] console = "pty". The daemon then starts the server in a pseudo console (Windows ConPTY, Unix pty).

A pseudo console shows each command that you send. The line breaks can also change. In a pseudo console, Terraria writes the prompt : and Server started on different lines. Write your patterns for both cases.


8. Console Patterns

Write the ready, join, leave, and stop patterns only from measured output.

  • Put the ready, join, and leave patterns in [extensions.saba-core] (ready_patterns, player_join_patterns, player_leave_patterns). Put the stop pattern in [detection] graceful_exit_patterns.
  • Anchor each pattern to the start and the end of the line. A chat line that contains the same words must not match, for example <Server> Server started.
  • If a prompt can come before the message, accept it with ^(?:<prompt>)?.
  • If the server language setting translates a message, add the measured message for each language. If you add only English, the daemon cannot see the ready state of a server that uses a different language.
  • Add a test. The measured lines must match, with and without the prompt. A chat line must not match.

9. Install and Settings Files

Install:

  • If the archive has a folder for each operating system, select the folder by the name of the operating system. Do not select it by the executable name, by the path length, or by the first entry. If you find no folder or more than one folder, return a failure.
  • Do not replace existing settings or worlds. Extract the example settings file only when no settings file exists.
  • Verify each downloaded file. Use the official checksum for each binary file. If there is no official checksum, use HTTPS to a fixed official host, the archive CRC, and the presence of the expected executable. Write "no official checksum" and the source in the research table. Do not make up a checksum, and do not use a checksum from a community source.

Settings files:

  • Read and write the file with the official syntax of its format. For example, Java .properties files have the escapes \: and \=, and a \ at the end of a line continues the line.
  • Do not assume an encoding. Read the file with its real encoding. Write it again with the same encoding and the same line endings. The Terraria Windows serverconfig.txt file uses cp1252, and it has the byte 0x92 in a comment. A module that reads only UTF-8 cannot start this server, save its settings, or import them.
  • Change only the keys that changed. Keep the other keys, the comments, and the order.
  • If you cannot read the file, do not write it. A file that is missing, a file that you cannot read, and a file that you cannot parse are three different cases.

10. Tests

Unit tests and the conformance kit run without the sandbox and with sample files. They cannot find problems that occur only with the real download, in the sandbox, in a console mode, or on Windows. Do all three levels of tests.

10.1 Unit Tests

  1. Write a test for each function in test_lifecycle.py before you write the function.
  2. Run the test and make sure that it fails.
  3. Write the function.
  4. Run these checks:
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 Tests on the Real Server (Before a Pull Request)

After you complete section 4, call the module functions on a real server folder.

  1. Run install_server with the real download. Make sure that only the files for this operating system are in the folder.
  2. Start the server with the command from get_launch_command. Make sure that the ready pattern matches.
  3. Send each command template. Make sure that the server accepts it.
  4. Send the stop command. Make sure that the server saves and stops.
  5. Compare the paths from backup_paths and reset_server with the files that the server made.

10.3 Tests on a Real PC

Use the regular Saba-chan installation on a Windows PC. A new module runs in the sandbox, so this test also finds sandbox problems.

  1. Copy the module folder to modules\<name>\ in the Saba-chan data folder.
  2. Run saba-chan-cli module refresh.
  3. Run saba-chan-cli server add <server> -m <module>.
  4. Start the server. Make sure that Saba-chan shows the ready state.
  5. Send commands with saba-chan-cli run <server> <command>. Read the replies with saba-chan-cli server console <server> --print.
  6. Change a setting and restart the server. Make sure that the server uses the new value.
  7. Make a backup with saba-chan-cli backup create <server>. Examine the files in the backup.
  8. Stop the server. Make sure that Saba-chan records a normal stop and that the world save is there.
  9. Reset the world. Examine which files the reset deleted and which files it kept.

If [module.dependencies] saba-core asks for a version that is not released, the regular installation does not load the module. Do the PC test after that version is released. Do not decrease the version in the dependency.


11. Checklist Before a Pull Request

  • RESEARCH.md has a source for each item, and each source shows "document" or "measurement".
  • You examined the archive entries and the raw bytes of the default files.
  • You ran the real server and recorded the raw output, the help output, and the files after a save.
  • Each declared command is in the help output.
  • The server replies to commands. If it does not, [launch] console = "pty" is set.
  • Each console pattern comes from measured output and accepts the prompt and each translation.
  • Each runtime is a fixed portable version, and the module verifies the downloaded files.
  • The install extracts only the folder for this operating system.
  • The settings file keeps its encoding and line endings.
  • The world reset deletes only files that the server made, including its backups.
  • The module does not use msiexec, a Windows service, a mkdtemp folder, or a direct loopback connection.
  • You did the tests on the real server and on a real PC, or you wrote down each test that you could not do.