Ein Modul bauen: von der Recherche bis zur Veröffentlichung
Das vollständige Vorgehen für ein zuverlässiges Spielmodul: Recherche, Tests mit dem echten Server, portable Laufzeiten, die Isolation, Konsolenmodi und Tests auf einem echten PC.
Ein Modul bauen: von der Recherche bis zur Veröffentlichung
Die Modul-Entwicklungsanleitung beschreibt, was ein Modul enthält. Diese Seite beschreibt, wie Sie ein Modul bauen, das auf einem echten PC funktioniert.
Ein Modul, das alle Unit-Tests besteht, kann auf einem echten Server trotzdem fehlschlagen. Das Terraria-Modul ist ein Beispiel. Es bestand alle Unit-Tests und alle Konformitätsprüfungen. Auf einem echten Server hatte es neun Fehler. Diese Seite zeigt das Vorgehen, das solche Fehler vor einer Veröffentlichung findet.
1. Entwurfsregeln
Diese Regeln gelten für jedes Modul.
- Der Daemon erledigt die Arbeit. Ein Modul beschreibt nur ein Spiel. Umgehen Sie den Daemon-Vertrag nicht. Fehlt dem Vertrag eine Funktion, fügen Sie zuerst einen allgemeinen Erweiterungspunkt im Daemon hinzu.
- Verzweigen Sie nicht nach Spielnamen. Der Daemon und die gemeinsamen Hilfsfunktionen enthalten keine Spielnamen. Nutzen Sie Schlüssel in
module.toml, Hooks und Slots. - Überall dieselbe Ausführungsumgebung. Nutzen Sie keine Laufzeit, die auf dem PC installiert ist. Das Modul lädt eine feste Version der Laufzeit herunter und legt sie in den Serverordner (Abschnitt 5).
- Jeder Wert an genau einer Stelle. Der Standardwert einer Einstellung kommt aus einer Datei: der Datei, die das Spiel erstellt, oder der Beispieldatei im Download.
- Alle Texte für Nutzer gehören in
locales/.en.jsonist die Referenzdatei.
2. Das Spiel recherchieren
Legen Sie vor dem Programmieren eine Recherchetabelle in <game>/RESEARCH.md an. Schreiben Sie für jeden Eintrag die Quelle auf. Notieren Sie auch, ob die Quelle ein Dokument oder eine Messung ist. Wenn Sie keine Quelle finden, lassen Sie den Eintrag leer und schreiben Sie „nicht geprüft“. Raten Sie keinen Wert.
| Eintrag | Wo Sie ihn finden |
|---|---|
| Server-Programm, Startargumente, Standardports | Offizielle Dokumente, die Hilfe des Servers, die Startskripte im Download |
| Alle Befehle und ihre Argumente | Offizielle Befehlsdokumente und die Ausgabe des Server-Befehls help. Vergleichen Sie beide Zeile für Zeile |
| Alle Einstellungen (Schlüssel, Format, Bereich, Standardwert) | Die Standard-Einstellungsdatei, die der Server erstellt. Erstellt der Server keine, nutzen Sie die Beispieldatei im Download |
| Syntax und Kodierung der Einstellungsdatei | Die rohen Bytes dieser Datei |
| Welt-Speicherstände und die Sicherungen, die das Spiel anlegt | Die Dateiliste, nachdem Sie den Server gestartet und die Welt gespeichert haben |
| Meldungen für Bereit, Stopp, Beitritt und Verlassen | Die rohe Konsolenausgabe. Prüfen Sie auch, ob die Spracheinstellung des Servers diese Meldungen übersetzt |
| Installationsweg und Dateiprüfung | Die offizielle Download-Adresse und die offizielle Prüfsumme. Gibt es keine Prüfsumme, schreiben Sie „keine“ und die Quelle |
| Laufzeitvoraussetzungen | Die Verweise des Server-Programms und die offiziellen Dokumente. Suchen Sie, was der Download nicht enthält |
| Dateien außerhalb des Instanzordners | Änderungen im Benutzerordner und im Dokumente-Ordner nach einem Serverlauf |
Ein Wiki kann eine alte Version beschreiben. Das Terraria-Wiki nennt einen Befehl death. Der Server Terraria 1.4.5.8 antwortet darauf mit „Invalid command.“.
3. Die echten Dateien untersuchen
Wenn Sie den Server herunterladen können, untersuchen Sie die Dateien selbst.
- Lassen Sie alle Einträge des Archivs anzeigen. Prüfen Sie, ob das Archiv einen Ordner für jedes Betriebssystem hat und ob derselbe Programmname in mehreren Ordnern liegt. Das Terraria-Archiv hat
TerrariaServer.exeim OrdnerLinux/und im OrdnerWindows/. - Lesen Sie die Standarddateien Byte für Byte. Ermitteln Sie die Kodierung (UTF-8, BOM, cp1252), die Zeilenenden (LF, CRLF), die Beispielschlüssel in Kommentaren und die Zeilen, die keine Kommentare sind.
- Nehmen Sie die Beispielschlüssel aus Kommentaren in die Liste der Einstellungen auf. Eine Zeile, die kein Kommentar ist, liefert den Standardwert.
4. Den echten Server starten
Starten Sie den Server wie der Daemon: verbinden Sie stdin und stdout über Pipes. Zeichnen Sie die rohe Ausgabe auf. Kann Ihre Build-Umgebung nur eine Server-Version für ein anderes Betriebssystem ausführen, starten Sie diese. Befehle, Meldungen und Speicherverhalten sind gleich, wenn der Spielcode gleich ist.
Zeichnen Sie Folgendes auf:
- Die Bereit-Zeile, die Zeile nach dem Stopp-Befehl und die Dauer eines Speichervorgangs.
- Die Ausgabe von
help. Senden Sie jeden Befehl, den nur ein Dokument nennt, und notieren Sie die Antwort. - Die Konsolen-Eingabeaufforderung. Manche Server schreiben sie ohne Zeilenumbruch. Die nächste Zeile beginnt dann mit der Eingabeaufforderung. Terraria schreibt
: Server started. - Die Antwort auf einen Befehl, den Sie über die Pipe senden. Antwortet der Server nicht, testen Sie erneut mit einer Pseudokonsole (Abschnitt 7).
- Die Bereit- und Stopp-Meldungen für jede Serversprache.
- Die Dateien, die der Server beim Start und beim Speichern erstellt. Terraria erstellt
world.wld.bakundworld.wld.bak2.
Manche Einträge brauchen einen Spiel-Client, zum Beispiel Beitrittsmeldungen und ein Ziel für einen Kick. Lassen Sie diese Einträge leer und schreiben Sie „nicht gemessen“.
5. Laufzeitvoraussetzungen: portabel und fest
Manche Server brauchen eine Laufzeit, die nicht im Download enthalten ist, zum Beispiel Java, XNA Framework oder die Visual-C++-Laufzeit. Nutzen Sie keine Laufzeit, die auf dem PC installiert ist. Sie kann auf jedem PC eine andere Version haben.
Gehen Sie so vor:
- Tragen Sie Adresse, Größe, Signatur und SHA-256 der offiziellen Laufzeitdatei in die Recherchetabelle ein.
- Ermitteln Sie die kleinste Menge an Dateien, die der Server braucht. Starten Sie den Server nur mit diesen Dateien, um die Menge zu bestätigen. Für Terraria sind es die vier XNA-Assemblys (
Microsoft.Xna.Framework,.Game,.Graphics,.Xact),XnaNative.dll,msvcr100.dllundmsvcp100.dll. - Laden Sie in
install_serverdie feste Version herunter. Vergleichen Sie die Datei mit der offiziellen Prüfsumme. Gibt es keine, vergleichen Sie mit einem SHA-256, den Sie von einer Datei mit gültiger Herausgebersignatur notiert haben. - Legen Sie nur die nötigen Dateien in den Server- oder Instanzordner. Starten Sie den Server mit diesem Pfad.
- Suchen Sie in
validatenach diesen Dateien. Fehlt eine, geben Sie ein Problem mitseverity: "critical"und einem eigenencodezurück. Bitten Sie den Nutzer, den Server neu zu installieren.
Nutzen Sie keine Administratorrechte, keine systemweite Installation und keinen Windows-Dienst.
Grenze: .NET Framework lädt eine Assembly zuerst aus dem globalen Assembly-Cache (GAC), wenn dort derselbe Name und dieselbe Version liegen. Native DLLs werden zuerst aus dem Serverordner geladen.
6. Die Isolation
Unter Windows läuft ein Modul, das nicht aus dem signierten Saba-chan-Katalog stammt, in einem Windows-AppContainer. Jedes neue Modul läuft in dieser Isolation. Testen Sie Ihr Modul in der Isolation, bevor Sie einen Pull Request öffnen.
Die Isolation sperrt Folgendes:
| Gesperrt | Stattdessen |
|---|---|
| Loopback-Verbindungen (Daemon-API, REST-API des Spielservers) | daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. Der Daemon leitet die Anfrage weiter |
Windows Installer (msiexec scheitert mit Fehler 1601) und andere Dienste | Lesen Sie die Installationsdatei (MSI, CAB) mit Python |
Ein Ordner, den tempfile.mkdtemp im Instanzordner anlegt | tempfile.mkstemp oder ein Ordner, den Sie mit os.mkdir anlegen. Ab Python 3.13 gibt mkdtemp nur dem aktuellen Benutzer Zugriff. Das isolierte Konto kann in diesen Ordner nicht schreiben |
| Schreiben außerhalb der erlaubten Ordner | Der Instanz-, Arbeits- und Installationsordner sowie die Ordner in data_roots |
Scheitert eine gemeinsame Hilfsfunktion in der Isolation, umgehen Sie den Fehler nicht im Modul. Melden Sie ihn als Daemon-Problem.
7. Konsolenmodi
Standardmäßig verbindet der Daemon stdin und stdout des Servers über Pipes ([launch] console = "pipe"). Manche Server verhalten sich anders, wenn stdin eine Pipe ist:
- Palworld hält seine Ausgabe zurück, bis es beendet wird.
- Der Terraria-Server für Windows liest keine Eingabe aus einer Pipe. Er antwortete weder auf Befehle noch auf
exit. Der Daemon beendete ihn nach 60 Sekunden zwangsweise, ohne zu speichern.
Setzen Sie für solche Server [launch] console = "pty". Der Daemon startet den Server dann in einer Pseudokonsole (Windows ConPTY, Unix pty).
Eine Pseudokonsole zeigt jeden gesendeten Befehl an. Auch die Zeilenumbrüche können sich ändern. In einer Pseudokonsole schreibt Terraria die Eingabeaufforderung : und Server started in verschiedene Zeilen. Schreiben Sie Ihre Muster für beide Fälle.
8. Konsolenmuster
Schreiben Sie die Muster für Bereit, Beitritt, Verlassen und Stopp nur aus gemessener Ausgabe.
- Legen Sie die Muster für Bereit, Beitritt und Verlassen in
[extensions.saba-core]ab (ready_patterns,player_join_patterns,player_leave_patterns). Das Stopp-Muster gehört in[detection] graceful_exit_patterns. - Verankern Sie jedes Muster am Anfang und am Ende der Zeile. Eine Chatzeile mit denselben Wörtern darf nicht passen, zum Beispiel
<Server> Server started. - Kann eine Eingabeaufforderung vor der Meldung stehen, akzeptieren Sie sie mit
^(?:<Eingabeaufforderung>)?. - Übersetzt die Spracheinstellung des Servers eine Meldung, fügen Sie die gemessene Meldung für jede Sprache hinzu. Fügen Sie nur Englisch hinzu, erkennt der Daemon den Bereit-Zustand eines Servers in einer anderen Sprache nicht.
- Fügen Sie einen Test hinzu. Die gemessenen Zeilen müssen mit und ohne Eingabeaufforderung passen. Eine Chatzeile darf nicht passen.
9. Installation und Einstellungsdateien
Installation:
- Hat das Archiv einen Ordner für jedes Betriebssystem, wählen Sie den Ordner nach dem Namen des Betriebssystems. Wählen Sie ihn nicht nach dem Programmnamen, der Pfadlänge oder dem ersten Eintrag. Finden Sie keinen oder mehr als einen Ordner, geben Sie einen Fehler zurück.
- Ersetzen Sie keine vorhandenen Einstellungen oder Welten. Entpacken Sie die Beispiel-Einstellungsdatei nur, wenn noch keine Einstellungsdatei existiert.
- Prüfen Sie jede heruntergeladene Datei. Nutzen Sie für jede Binärdatei die offizielle Prüfsumme. Gibt es keine, nutzen Sie HTTPS zu einem festen offiziellen Host, die Archiv-CRC und das Vorhandensein des erwarteten Programms. Schreiben Sie „keine offizielle Prüfsumme“ und die Quelle in die Recherchetabelle. Erfinden Sie keine Prüfsumme und nutzen Sie keine Prüfsumme aus einer Community-Quelle.
Einstellungsdateien:
- Lesen und schreiben Sie die Datei mit der offiziellen Syntax ihres Formats. Java-
.properties-Dateien haben zum Beispiel die Escapes\:und\=, und ein\am Zeilenende setzt die Zeile fort. - Setzen Sie keine Kodierung voraus. Lesen Sie die Datei in ihrer echten Kodierung. Schreiben Sie sie mit derselben Kodierung und denselben Zeilenenden zurück. Die Windows-Datei
serverconfig.txtvon Terraria nutzt cp1252 und hat das Byte 0x92 in einem Kommentar. Ein Modul, das nur UTF-8 liest, kann diesen Server weder starten noch seine Einstellungen speichern oder importieren. - Ändern Sie nur die geänderten Schlüssel. Behalten Sie die anderen Schlüssel, die Kommentare und die Reihenfolge.
- Können Sie die Datei nicht lesen, schreiben Sie sie nicht. Eine fehlende Datei, eine nicht lesbare Datei und eine nicht auswertbare Datei sind drei verschiedene Fälle.
10. Tests
Unit-Tests und das Konformitätspaket laufen ohne Isolation und mit Beispieldateien. Sie finden keine Probleme, die nur mit dem echten Download, in der Isolation, in einem Konsolenmodus oder unter Windows auftreten. Führen Sie alle drei Teststufen aus.
10.1 Unit-Tests
- Schreiben Sie in
test_lifecycle.pyfür jede Funktion einen Test, bevor Sie die Funktion schreiben. - Führen Sie den Test aus und stellen Sie sicher, dass er fehlschlägt.
- Schreiben Sie die Funktion.
- Führen Sie diese Prüfungen aus:
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 mit dem echten Server (vor einem Pull Request)
Rufen Sie nach Abschnitt 4 die Modulfunktionen für einen echten Serverordner auf.
- Führen Sie
install_servermit dem echten Download aus. Stellen Sie sicher, dass nur die Dateien für dieses Betriebssystem im Ordner liegen. - Starten Sie den Server mit dem Befehl aus
get_launch_command. Stellen Sie sicher, dass das Bereit-Muster passt. - Senden Sie jede Befehlsvorlage. Stellen Sie sicher, dass der Server sie annimmt.
- Senden Sie den Stopp-Befehl. Stellen Sie sicher, dass der Server speichert und beendet wird.
- Vergleichen Sie die Pfade aus
backup_pathsundreset_servermit den Dateien, die der Server erstellt hat.
10.3 Tests auf einem echten PC
Nutzen Sie die reguläre Saba-chan-Installation auf einem Windows-PC. Ein neues Modul läuft in der Isolation, daher findet dieser Test auch Isolationsprobleme.
- Kopieren Sie den Modulordner nach
modules\<name>\im Saba-chan-Datenordner. - Führen Sie
saba-chan-cli module refreshaus. - Führen Sie
saba-chan-cli server add <server> -m <modul>aus. - Starten Sie den Server. Stellen Sie sicher, dass Saba-chan den Bereit-Zustand anzeigt.
- Senden Sie Befehle mit
saba-chan-cli run <server> <befehl>. Lesen Sie die Antworten mitsaba-chan-cli server console <server> --print. - Ändern Sie eine Einstellung und starten Sie den Server neu. Stellen Sie sicher, dass der Server den neuen Wert nutzt.
- Erstellen Sie eine Sicherung mit
saba-chan-cli backup create <server>. Untersuchen Sie die Dateien in der Sicherung. - Stoppen Sie den Server. Stellen Sie sicher, dass Saba-chan einen normalen Stopp aufzeichnet und der Welt-Speicherstand vorhanden ist.
- Setzen Sie die Welt zurück. Prüfen Sie, welche Dateien gelöscht und welche behalten wurden.
Verlangt [module.dependencies] saba-core eine noch nicht veröffentlichte Version, lädt die reguläre Installation das Modul nicht. Führen Sie den PC-Test durch, nachdem diese Version veröffentlicht ist. Senken Sie die Version in der Abhängigkeit nicht.
11. Checkliste vor einem Pull Request
-
RESEARCH.mdnennt für jeden Eintrag eine Quelle, und jede Quelle zeigt „Dokument“ oder „Messung“. - Sie haben die Archiveinträge und die rohen Bytes der Standarddateien untersucht.
- Sie haben den echten Server gestartet und die rohe Ausgabe, die Ausgabe von
helpund die Dateien nach dem Speichern aufgezeichnet. - Jeder deklarierte Befehl steht in der Ausgabe von
help. - Der Server antwortet auf Befehle. Wenn nicht, ist
[launch] console = "pty"gesetzt. - Jedes Konsolenmuster stammt aus gemessener Ausgabe und akzeptiert die Eingabeaufforderung und jede Übersetzung.
- Jede Laufzeit ist eine feste portable Version, und das Modul prüft die heruntergeladenen Dateien.
- Die Installation entpackt nur den Ordner für dieses Betriebssystem.
- Die Einstellungsdatei behält ihre Kodierung und ihre Zeilenenden.
- Das Zurücksetzen der Welt löscht nur Dateien, die der Server erstellt hat, einschließlich seiner Sicherungen.
- Das Modul nutzt weder
msiexecnoch einen Windows-Dienst, einenmkdtemp-Ordner oder eine direkte Loopback-Verbindung. - Sie haben die Tests mit dem echten Server und auf einem echten PC durchgeführt oder jeden nicht möglichen Test notiert.