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.json ist 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.

EintragWo Sie ihn finden
Server-Programm, Startargumente, StandardportsOffizielle Dokumente, die Hilfe des Servers, die Startskripte im Download
Alle Befehle und ihre ArgumenteOffizielle 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 EinstellungsdateiDie rohen Bytes dieser Datei
Welt-Speicherstände und die Sicherungen, die das Spiel anlegtDie Dateiliste, nachdem Sie den Server gestartet und die Welt gespeichert haben
Meldungen für Bereit, Stopp, Beitritt und VerlassenDie rohe Konsolenausgabe. Prüfen Sie auch, ob die Spracheinstellung des Servers diese Meldungen übersetzt
Installationsweg und DateiprüfungDie offizielle Download-Adresse und die offizielle Prüfsumme. Gibt es keine Prüfsumme, schreiben Sie „keine“ und die Quelle
LaufzeitvoraussetzungenDie 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.

  1. 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.exe im Ordner Linux/ und im Ordner Windows/.
  2. 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.
  3. 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.bak und world.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:

  1. Tragen Sie Adresse, Größe, Signatur und SHA-256 der offiziellen Laufzeitdatei in die Recherchetabelle ein.
  2. 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.dll und msvcp100.dll.
  3. Laden Sie in install_server die 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.
  4. Legen Sie nur die nötigen Dateien in den Server- oder Instanzordner. Starten Sie den Server mit diesem Pfad.
  5. Suchen Sie in validate nach diesen Dateien. Fehlt eine, geben Sie ein Problem mit severity: "critical" und einem eigenen code zurü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:

GesperrtStattdessen
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 DiensteLesen Sie die Installationsdatei (MSI, CAB) mit Python
Ein Ordner, den tempfile.mkdtemp im Instanzordner anlegttempfile.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 OrdnerDer 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.txt von 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

  1. Schreiben Sie in test_lifecycle.py für jede Funktion einen Test, bevor Sie die Funktion schreiben.
  2. Führen Sie den Test aus und stellen Sie sicher, dass er fehlschlägt.
  3. Schreiben Sie die Funktion.
  4. 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.

  1. Führen Sie install_server mit dem echten Download aus. Stellen Sie sicher, dass nur die Dateien für dieses Betriebssystem im Ordner liegen.
  2. Starten Sie den Server mit dem Befehl aus get_launch_command. Stellen Sie sicher, dass das Bereit-Muster passt.
  3. Senden Sie jede Befehlsvorlage. Stellen Sie sicher, dass der Server sie annimmt.
  4. Senden Sie den Stopp-Befehl. Stellen Sie sicher, dass der Server speichert und beendet wird.
  5. Vergleichen Sie die Pfade aus backup_paths und reset_server mit 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.

  1. Kopieren Sie den Modulordner nach modules\<name>\ im Saba-chan-Datenordner.
  2. Führen Sie saba-chan-cli module refresh aus.
  3. Führen Sie saba-chan-cli server add <server> -m <modul> aus.
  4. Starten Sie den Server. Stellen Sie sicher, dass Saba-chan den Bereit-Zustand anzeigt.
  5. Senden Sie Befehle mit saba-chan-cli run <server> <befehl>. Lesen Sie die Antworten mit saba-chan-cli server console <server> --print.
  6. Ändern Sie eine Einstellung und starten Sie den Server neu. Stellen Sie sicher, dass der Server den neuen Wert nutzt.
  7. Erstellen Sie eine Sicherung mit saba-chan-cli backup create <server>. Untersuchen Sie die Dateien in der Sicherung.
  8. Stoppen Sie den Server. Stellen Sie sicher, dass Saba-chan einen normalen Stopp aufzeichnet und der Welt-Speicherstand vorhanden ist.
  9. 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.md nennt 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 help und 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 msiexec noch einen Windows-Dienst, einen mkdtemp-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.