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.tomlkeys, 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.jsonis 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.
| Item | Where to find it |
|---|---|
| Server executable, launch arguments, default ports | Official documents, the server help text, the start scripts in the download |
| All commands and their arguments | Official 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 file | The raw bytes of that file |
| World saves and the backups that the game makes | The file list after you start the server and save the world |
| Ready, stop, join, and leave messages | The raw console output. Also find out if the server language setting translates these messages |
| Install method and file verification | The official download address and the official checksum. If there is no checksum, write "none" and the source |
| Runtime requirements | The references of the server executable and the official documents. Find what the download does not include |
| Files outside the instance folder | Changes 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.
- 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.exein theLinux/folder and in theWindows/folder. - 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.
- 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.bakandworld.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:
- Write the address, size, signature, and SHA-256 of the official runtime file in the research table.
- 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, andmsvcp100.dll. - 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. - Put only the necessary files in the server folder or the instance folder. Start the server with that path.
- In
validate, look for these files. If a file is missing, return an issue withseverity: "critical"and a dedicatedcode. 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:
| Blocked | Use 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 services | Read the installer file (MSI, CAB) with Python |
A folder that tempfile.mkdtemp makes in the instance folder | tempfile.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 folders | The 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
.propertiesfiles 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.txtfile 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
- Write a test for each function in
test_lifecycle.pybefore you write the function. - Run the test and make sure that it fails.
- Write the function.
- 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.
- Run
install_serverwith the real download. Make sure that only the files for this operating system are in the folder. - Start the server with the command from
get_launch_command. Make sure that the ready pattern matches. - Send each command template. Make sure that the server accepts it.
- Send the stop command. Make sure that the server saves and stops.
- Compare the paths from
backup_pathsandreset_serverwith 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.
- Copy the module folder to
modules\<name>\in the Saba-chan data folder. - Run
saba-chan-cli module refresh. - Run
saba-chan-cli server add <server> -m <module>. - Start the server. Make sure that Saba-chan shows the ready state.
- Send commands with
saba-chan-cli run <server> <command>. Read the replies withsaba-chan-cli server console <server> --print. - Change a setting and restart the server. Make sure that the server uses the new value.
- Make a backup with
saba-chan-cli backup create <server>. Examine the files in the backup. - Stop the server. Make sure that Saba-chan records a normal stop and that the world save is there.
- 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.mdhas 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
helpoutput, and the files after a save. - Each declared command is in the
helpoutput. - 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, amkdtempfolder, 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.