Paketformat und Manifest

Ein natives sOU-HUD-Paket ist ein ZIP-Archiv mit der Endung .souhud. Es enthält ein Manifest und statische Browserdateien. Mit dem Paketwerkzeug kannst du dein HUD vor der Installation prüfen. Dieses Kapitel beschreibt die unterstützten Felder, Versionsregeln und Dateigrenzen.

Verzeichnisstruktur

mein-hud/
  hud.json
  wwwroot/
    index.html
    hud.js
    hud.css
    panel.json
    logo.png
    fonts/
    images/
    licenses/

hud.json liegt direkt an der Archivwurzel. Der Einstieg ist immer wwwroot/index.html. panel.json, Logo, eigene Skripte und weitere Verzeichnisse sind optional. Bei Blazor gehört die vollständige veröffentlichte wwwroot-Ausgabe einschließlich _framework ins Paket. Die übergeordnete Projektmappe, bin, obj, Entwicklungszugänge und private Konfigurationen gehören nicht hinein.

Das Paketwerkzeug nimmt die Dateien des angegebenen Ordners auf; es ist kein Filter für versehentlich beigelegte Quell- oder Geheimdateien. Halte deshalb einen eigenen sauberen Paketordner bereit. Das Manifest darf nicht in einem zusätzlichen ZIP-Unterordner versteckt sein.

Manifest vollständig erklärt

{
  "id": "mein-cast-hud",
  "version": "1.2.0",
  "name": "Mein Cast HUD",
  "apiVersion": 2,
  "runtime": "web",
  "entryPoint": "index.html",
  "logo": "logo.png",
  "outlineColors": {
    "ct": "#6FA8DC",
    "t": "#E8B44C"
  },
  "subviews": [
    { "name": "Vor dem Match", "route": "views/prematch" },
    { "name": "Vollbild", "route": "views/fullscreen" }
  ]
}

Native JSON-Eigenschaftsnamen werden ohne Unterscheidung der Groß-/Kleinschreibung gelesen. Verwende trotzdem die gezeigte camelCase-Schreibweise. Die Werte für Runtime und Einstieg müssen genau passen. Zusätzliche eigene Manifestfelder erweitern den Funktionsumfang von sOU nicht; verwende für die Integration die hier beschriebenen Felder.

Archiv- und Pfadgrenzen

Innere Leerzeichen in Assetnamen sind zulässig, etwa fonts/Meine Schrift.ttf. Der Import benennt Dateien nicht um. Browseradressen müssen Leerzeichen korrekt URL-kodieren; relative CSS- und HTML-Verweise sollten exakt zur Datei passen. Nicht zulässig sind absolute Pfade, Rückstriche, Doppelpunkte, alternative Datenströme und Ausbrüche aus dem Paketordner.

Versionen, Identität und Aktualisierung

Die Kombination aus id und version identifiziert einen unveränderlichen Paketstand. Der Desktop lehnt eine bereits installierte Version ab. Ersetze daher weder Dateiinhalte in einer vorhandenen Installation noch ein bereits verteiltes Archiv unter derselben Versionsnummer. Erhöhe für Änderungen die Version und importiere das neue Paket.

Die drei Zahlen werden numerisch verglichen. Eine Version ohne Suffix steht über derselben Version mit Suffix. Rein numerische Suffixe werden numerisch verglichen, andere Suffixe ordinal; ein numerisches Suffix steht vor einem nichtnumerischen. Dies ist kein vollständiger SemVer-Vertrag: Buildmetadaten mit +, Punkte innerhalb des Suffixes und vierteilige Versionsnummern sind im HUD-Manifest nicht erlaubt.

Eine Workspace-Vorgabe kann eine bestimmte installierte Version auswählen. Ohne solche Vorgabe verwendet der Host die höchste installierte Version. Fehlt die angeforderte Version, soll keine andere Version als scheinbar identischer Ersatz ausgegeben werden. Die Verwaltungsansicht kann weiterhin vorhandene Installationen anzeigen.

Ausgabeadressen und Subviews

Die stabile Adresse lädt die konkrete Version in einem transparenten Rahmen. Ein bereits geöffnetes Dokument bleibt damit bei seinem Stand; ein Import tauscht nicht mitten im Cast seine Dateien oder Panelversion aus. Für einen Versionswechsel die Quelle bewusst neu laden.

Subviews sind Ansichten derselben Anwendung. Der Host liefert auch dort die Paket-index.html aus und setzt die Basisadresse auf die gemeinsame Paketwurzel. Dein HUD wertet die Route selbst aus. Eine zusätzliche Unterordner-index.html ist dafür nicht der Vertrag. Nicht deklarierte Routen werden abgewiesen. Hauptansicht und Subviews teilen dieselbe Paketidentität, Medienbasis und Panelkonfiguration.

Bauen und prüfen

Richte zunächst das Werkzeug über NuGet oder aus dem portablen SDK ein, wie unter Vorlagen und Werkzeug einrichten beschrieben. Die folgenden Befehle verwenden dieses Arbeitsverzeichnis mit werkzeuge und ausgabe. Lege deinen Paketordner mein-hud beziehungsweise das zu normalisierende Originalarchiv daneben ab.

./werkzeuge/sou-hud pack ./mein-hud ./ausgabe/mein-hud-1.2.0.souhud
./werkzeuge/sou-hud validate ./ausgabe/mein-hud-1.2.0.souhud
./werkzeuge/sou-hud normalize ./original-lhm.zip ./ausgabe/mein-lhm.souhud

Die Ausgabedatei muss außerhalb des Eingabeordners liegen und darf noch nicht existieren. pack prüft das erzeugte Archiv vor der Ausgabe. normalize übernimmt ein kompatibles Originalarchiv in das native sOU-Format und ist insbesondere vor einem Cloud-Upload relevant. Lokal kann ein LHM-/JT-ZIP direkt importiert werden. Weitere Regeln unter LHM-/JT-Import.

Installation und typische Ablehnungen

Eine neue Version erscheint erst nach erfolgreicher Prüfung von Manifest, Einstieg, Logo und Panel in den installierten HUDs. Bei einer Ablehnung korrigierst du das Paket und importierst es erneut. Prüfe nach der Installation auch die Darstellung im Browser und in OBS: Eine gültige Paketstruktur allein bestätigt noch nicht, dass dein HUD alle Spielzustände korrekt darstellt.

• „hud.json fehlt“: Manifest an die Archivwurzel legen, nicht den übergeordneten Ordner mitzippen.
• „HUD-Einstiegsdatei fehlt“: wwwroot/index.html mitliefern; bei WebAssembly die Publish-Ausgabe verwenden.
• „Diese HUD-Version ist bereits installiert“: Neue Version vergeben. Gleiche IDs nicht für fachlich verschiedene HUDs verwenden.
• „Ungültiger oder doppelter Paketpfad“: Kollidierende Dateinamen, unerlaubte Zeichen und Links entfernen; Groß-/Kleinschreibung allein erzeugt keine zweite Datei.
• Abgewiesenes Panel: Kennungen, Feldtypen, Auswahlwerte und Grenzen gegen die Panelreferenz prüfen.
• Leere Ausgabe bei gültigem Paket: Browserkonsole, relative Assets, SDK-Reihenfolge und Wartedarstellung ohne GSI prüfen.

Dateizugriff und Ressourcen

Native Pakete werden mit einer auf lokale Ressourcen begrenzten Content-Security-Policy ausgeliefert. Lokale Skripte und WASM sind möglich; Schriftdateien gehören ins Paket. Bilder können lokale Dateien oder erlaubte Daten-URLs sein. Das LHM-Kompatibilitätsprofil hat eigene Regeln für HTTPS-Präsentationsressourcen, beschrieben unter externe Legacy-Ressourcen.

Paketdateien sind nicht der Speicherort für Laufzeiteinstellungen. Panelwerte und importierte Medien verwaltet sOU außerhalb der unveränderlichen Installation. Bearbeite diese Daten über den Manager und empfange sie über das SDK. Wenn eine Cloud-Berechtigung entzogen wird, können neue Ausgaben gesperrt sein; eine laufende Ausgabe wird dadurch nicht automatisch ausgetauscht.