DSA 4.1 Heldendokument: Installation & Bedienung

Der Generator des Heldendokuments unterstützt macOS und Linux. Das Webinterface lässt sich in einem Docker-Container auch unter Windows betreiben. Um den Generator auf der Kommandozeile zu benutzen, müssen Windows-Nutzer auf WSL zurückgreifen, was hier nicht erläutert wird.

Der Generator benutzt verschiedene Werke, die zwar kostenlos aus dem Internet geladen werden können, deren Lizenz aber keine Weiterverbreitung erlaubt. Aus diesem Grund kann der fertige Generator nicht zum Download angeboten werden. Statt dessen wird ein Script zur Verfügung gestellt, mit dem du den Generator vollautomatisch auf deinem PC bauen kannst. Das Script lädt alle relevanten Dateien aus dem Internet und erstellt dir daraus den Generator.

Installation

Generator auf der Kommandozeile

Der Generator selbst ist ein Script, das sich von der Kommandozeile aus ausführen lässt. Wenn du die Kommandozeile nicht gewohnt bist oder generell lieber ein Webinterface haben willst, installiere statt dessen das Webinterface.

Du benötigst Nix auf deinem System; dies ist ein Paketmanager, der die Abhängigkeiten des Generators verwaltet und den Generator erstellt. Benutzt du NixOS, hast du Nix bereits zur Verfügung. Der Paketmanager lässt sich aber auch auf anderen Linux-System und macOS installieren. Es sei auf die offizielle Installationsanleitung verwiesen.

Der Generator benutzt die experimentellen Nix Flakes. Auf der verlinkten Seite ist beschrieben, was zu tun ist, um dieses Feature in einer Nix-Installation zu aktivieren.

Hast du Nix Flakes aktiviert, führe folgenden Befehl aus:

nix build github:flyx/DSA-4.1-Heldendokument#dsa41held

Dies erzeugt einen Ordner result (der tatsächlich ein symlink ist), in dem sich der Generator unter bin/dsa41held befindet. Damit ist das Script nicht in deinem System installiert (sodass du es nur mit dsa41held ohne kompletten Pfad ausführen könntest). Wie alle Nix-Pakete lebt das Script im Verzeichnis /nix/store, zusammen mit allen Abhängigkeiten. Du kannst es mit nix-collect-garbage von deinem System entfernen.

Für regelmäßige Nutzung empfiehlt es sich, das Paket mit nix profile, Home Manager, oder auf NixOS über environment.systemPackages zu installieren. Mir ist klar, dass das für Nutzer, die sonst kein Nix benutzen, nicht ideal ist, aber die Zielgruppe für den Kommandozeilenclient scheint mir zu klein, um Zeit und Energie in andere Optionen zu investieren, wenn Nix fast überall funktioniert.

Web-Interface

Das Webinterface ist eine Go-Anwendung, die über HTTP erreichbar ist. Es stellt dieselben Funktionen zur Verfügung wie das Kommandozeileninterface. Es kann entweder direkt mit Nix gebaut werden oder als OCI (vulgo Docker) Image.

Das Nix-Paket ist wie üblich über die Flake verfügbar:

# baut die Applikation direkt:
nix build github:flyx/DSA-4.1-Heldendokument#dsa41held_webui
# baut das Docker-Image:
nix build github:flyx/DSA-4.1-Heldendokument#dsa41held_webui-docker

Alternativ lässt sich das Docker-Image auch ohne Nix bauen. Dafür musst du Docker Desktop installieren (sofern du es nicht ohnehin auf deinem System hast). Starte Docker nach der Installation. (Linux-Nutzer können statt dessen auch podman benutzen; dies wird hier nicht erläutert, funktioniert aber ähnlich.)

Lade das aktuelle zip-Archiv des Projekts herunter, entpacke es, öffne eine Kommandozeile und wechsle in den entpackten Ordner. Führe dort folgende Befehle aus:

docker build -f build.dockerfile -t dsa41held-build .
docker run --rm dsa41held-build:latest > dsa41held_webui.tar
docker load -i dsa41held_webui.tar

Der erste Befehl baut ein Docker-Image, in dem Nix verfügbar ist und der dazu dient, das Ziel-Image zu bauen. Der zweite Befehl baut den Generator und braucht dafür mehrere Minuten – es mag so aussehen als ob er hängen bleibt, aber das ist nicht der Fall! Warte einfach, bis der Befehl fertig ist. Mit dem dritten Befehl installierst du das image, in dem der Generator installiert ist, in Docker und kannst es damit zukünftig ausführen.

Das generierte Docker-Image kann folgendermaßen von der Kommandozeile aus gestartet werden, wenn Docker läuft (man muss in der Kommandozeile nicht zu einem Ordner navigieren):

docker run -p 80:80 --rm dsa41held-webui:latest

Solange dieser Befehl läuft, kann das Webinterface im Browser über die URL http://localhost/ aufgerufen werden. Um das Webinterface zu beenden, drücke in der Konsole Ctrl+C.

Installation auf NixOS

NixOS-Nutzer, die das Webinterface als Service laufen lassen wollen, können einfach aus der Flake dieses Repositories das Modul nixosModules.webui importieren und dann in ihrer Konfiguration folgendes angeben:

services.dsa41generator = {
  enable = true;
  address = "127.0.0.1:8080";
};

Für Remote-Erreichbarkeit muss die public IP angegeben und der Port in der Firewall freigeschaltet werden!

Benutzung

Die Funktionen sind für beide Interfaces (Kommandozeile und Web) identisch. Bei jeder Funktion wird der Kommandozeilenaufruf angegeben. Auf der Weboberfläche werden Aktionen gestartet, indem die Quelldatei im entsprechenden Steuerelement ausgewählt wird.

Heldensoftware-Import

Du musst den Helden aus der Heldensoftware einzeln als XML-Datei exportieren. Danach kannst du ihn folgendermaßen importieren:

dsa41held import held.xml > held.lua

Dies erzeugt eine Datei held.lua, welche der Formatspezifikation genügt und die Werte aus dem Eingabeheld enthält. Du kannst sie manuell editieren, bevor du daraus ein PDF erzeugst. Der Import importiert den aktuellen Stand des Helden als „Basisdaten“, hast du den Held in der Software gesteigert, sind diese Steigerungen fest eingerechnet und nicht als Steigerungsereignisse verfügbar (das ist für das Resultat egal).

PDF-Generierung

dsa41held pdf [-w] <heldendatei>

Gib -w an, um weißen Hintergrund (statt der Karte) zu bekommen. Die Heldendatei muss eine Lua-Datei sein, die der Formatspezifikation genügt. Die Formatspezifikation ist relativ komplex und dem durchschnittlichen Nutzer wird empfohlen, einfach den Import aus der Heldensoftware zu benutzen, um die Lua-Datei zu erzeugen. Die Modifikation des Layouts (z.B. andere Reihenfolge der Talentgruppen, andere Zeilenanzahl in verschiedenen Tabellen usw.) ist allerdings nur direkt in der Lua-Eingabe möglich. Die Erstellung eines PDFs dauert etwas länger (auf meinem System – MBP M1 Pro 32GB – etwa 18 Sekunden). Wer statt der enormen LuaLaTeX-Ausgabe auf der Kommandozeile lieber einen Fortschrittsbalken haben möchte, sollte das Webinterface benutzen.

Steigerungsereignisse

Du kannst im Heldendokument Steigerungsereignisse angeben. Diese werden auf die angegebenen Anfangswerte appliziert bei der Erstellung des PDFs. Es ist eine Alternative zur Steigerung in der Heldensoftware. Dieses Feature habe ich eingebaut, um einen Charakter unabhängig von der Heldensoftware steigern zu können. Warum ich das will? Eine Lua-Datei lässt sich einfacher in Versionskontrolle verwalten als ein gezippter XML-Blob. Es ist angedacht, für den Generator ein Feature zu implementieren, mit dem man den Charakterbogen mit einer definierten AP-Anzahl generieren kann – also praktisch frühere Versionen des Charakters. Das ist für Conventions hilfreich, wo man oft einen Charakter in einem bestimmten AP-Bereich braucht. Dies wird dann nur funktionieren, wenn man die Steigerung in der Lua-Datei vorgenommen hat.

Der große Nachteil beim Steigern im Lua-Dokument ist, dass man die einzelnen Ereignisse eingibt, aber erst bei der Erstellung des PDFs sieht, wie viel AP man verbraucht hat (und möglicherweise mehr ausgibt als man hat). Weil die PDF-Erstellung länger braucht, gibt es ein Werkzeug, um sofort die resultierenden AP-Kosten aller Steigerungsereignisse auszugeben:

dsa41held ereignisse <heldendatei>

In der letzten Spalte stehen die übrigen AP nach jedem Ereignis.

Templates

Im Verzeichnis templates stehen Vorlagen für einen profanen, einen geweihten, und einen magischen Charakter zur Verfügung. Man kann sie auch aus dem Webinterface herunterladen.