Ein eigenes HUD entwickeln

Mit dem sOU-HUD-SDK entwickelst du ein eigenes HUD als HTML-/JavaScript-Anwendung oder mit C# und Blazor WebAssembly. Beide Varianten erhalten dieselben aufbereiteten Spieldaten und dieselben Panelnachrichten. sOU übernimmt GSI, HLAE, Teamzuordnung und die lokale Ausgabe. Dein HUD entscheidet, wie es diese Daten darstellt.

Diese Anleitung verwendet den SDK-Stand 0.2.0-preview.4. Du kannst die Vorlagen und das Werkzeug von nuget.org installieren oder das vollständige HUD-SDK als ZIP herunterladen (0.2.0-preview.4). Das ZIP enthält alle vier sOU-Pakete, beide Vorlagen, die Verbindungsclients und zwei fertig installierbare Beispiele. Die älteren SDK-Downloads 0.2.0-preview.3 und 0.1.0-preview bleiben unverändert erhalten.

Zuerst ein Beispiel öffnen

Du kannst die Verbindung ausprobieren, bevor du eine Entwicklungsumgebung einrichtest. Dafür brauchst du eine installierte sOU-App, ein freigeschaltetes Konto und das entpackte SDK. Ein laufendes CS2-Spiel ist für diesen ersten Schritt nicht erforderlich.

1. Das ZIP herunterladen und vollständig entpacken.
2. sOU starten, anmelden und den gewünschten Workspace auswählen.
3. In der Navigation HUDs öffnen und über Paket importieren die Datei sdk-web-example.souhud aus dem entpackten SDK wählen. Für C# kannst du stattdessen sdk-blazor-example.souhud verwenden.
4. Das installierte Beispiel auswählen und seine Browserausgabe öffnen. Ohne Spiel siehst du „Warte auf Spieldaten“. Das ist der erwartete Startzustand.
5. Das HUD-Panel öffnen, die Überschrift ändern und speichern. Die Überschrift im geöffneten HUD muss sich aktualisieren. Die Panelaktion zeigt zusätzlich eine Aktionsmeldung im HUD.
6. Für den Spielstand CS2 über die eingerichtete GSI-Verbindung starten und ein Spiel beobachten. Das Beispiel zeigt dann Spielstand und Map. Eine fehlende Spielverbindung verhindert den Paneltest nicht.

Damit hast du Installation, Browserausgabe und Panelverbindung geprüft. Für eine eigene Gestaltung wählst du jetzt einen der beiden Wege. Bestehende LHM-/JT-HUDs kannst du dagegen nach der Importanleitung direkt verwenden.

Welcher Entwicklungsweg passt zu dir?

Beide Wege verwenden hud.json für Name, Kennung und Version sowie wwwroot/panel.json für die Bedienfelder in sOU. Beginne mit der vorhandenen Vorlage und ändere zuerst nur Überschrift, Farben und Abstände. So bleibt die bereits funktionierende Datenverbindung erhalten.

Voraussetzungen und SDK-Inhalt

Für eigene Pakete benötigst du einen Texteditor, PowerShell und das .NET-10-SDK für Vorlageninstallation und Paketwerkzeug. Für Blazor wird .NET zusätzlich zum Bauen benötigt. Beim ersten Einrichten ist eine Internetverbindung für weitere .NET-Abhängigkeiten erforderlich; das portable ZIP liefert die sOU-Pakete bereits mit. Zum bloßen Importieren der fertigen Beispiele brauchst du keine Entwicklungswerkzeuge. Die Vertragsdatei als Typdownload ist eine zusätzliche Datenreferenz; sie enthält keine Vorlagen oder Clients.

Die vier Pakete haben unterschiedliche Aufgaben: SOU.Hud.Templates liefert die Projektvorlagen, SOU.Hud.Tool das Paketwerkzeug, SOU.Hud.Sdk den C#-Client und SOU.Live.Contracts dessen Datenmodelle. Die Paketlinks zeigen den jeweiligen Veröffentlichungsstand. Verwende Vorlagen, Werkzeug und C#-Abhängigkeiten aus demselben SDK-Stand.

Für die Webvorlage sind weder npm noch React, Vue oder TypeScript vorgeschrieben. Der Browser führt dein JavaScript aus; der vorhandene Microsoft-SignalR-Client wird lokal mitgeliefert. Blazor-HUDs werden als WebAssembly veröffentlicht und im Browser ausgeführt. Sie sind keine Erweiterungen, die eigene Assemblies im sOU-Host ausführen.

Vorlagen und Werkzeug einrichten

Wähle einen der folgenden Installationswege. Beide führen zu denselben Vorlagen und zum Werkzeug unter ./werkzeuge/sou-hud. Bereits installierte HUDs in sOU werden durch die Einrichtung der Entwicklungswerkzeuge nicht geändert. Lege ein neues Arbeitsverzeichnis an und öffne dort PowerShell; die folgenden Beispiele erzeugen eigene Projekte und Ausgaben darin.

Aus einer NuGet-Paketquelle installieren

Die passenden Paketseiten auf nuget.org: Vorlagen, Paketwerkzeug, C#-Client und Datenverträge.

New-Item -ItemType Directory -Path ./ausgabe
dotnet new install SOU.Hud.Templates@0.2.0-preview.4
dotnet tool install SOU.Hud.Tool --version 0.2.0-preview.4 --tool-path ./werkzeuge

Die Befehle verwenden deine eingerichteten NuGet-Paketquellen, normalerweise nuget.org. Falls dein Rechner die Quelle nicht erreicht oder du die sOU-Pakete lokal installieren möchtest, verwende die mitgelieferten Pakete aus dem ZIP wie im nächsten Abschnitt. Ein Quellenwechsel erfordert keine Änderung deiner HUD-Kennung oder deines Quellcodes.

Die mitgelieferten Pakete aus dem ZIP verwenden

1. Ein neues Arbeitsverzeichnis für deine HUD-Entwicklung anlegen.
2. Das SDK-Bundle darin in den Unterordner sou-hud-sdk entpacken. Direkt in diesem Unterordner müssen NuGet.Config, packages, javascript und templates liegen.
3. PowerShell im Arbeitsverzeichnis öffnen und die folgenden Befehle ausführen. Die Ordner werkzeuge und ausgabe werden hier neu angelegt; nach einem teilweise abgeschlossenen NuGet-Versuch einen neuen Werkzeugordner verwenden, statt eine bestehende Installation zu überschreiben.

$sdkRoot = (Resolve-Path ./sou-hud-sdk).Path
New-Item -ItemType Directory -Path ./ausgabe
dotnet new install "$sdkRoot/packages/SOU.Hud.Templates.0.2.0-preview.4.nupkg"
dotnet tool install SOU.Hud.Tool --version 0.2.0-preview.4 --add-source "$sdkRoot/packages" --tool-path ./werkzeuge

Das Paketwerkzeug steht anschließend unter ./werkzeuge/sou-hud bereit. Führe auch die weiteren Befehle aus diesem Arbeitsverzeichnis aus. In einer neuen PowerShell-Sitzung setzt du $sdkRoot mit dem ersten Befehl erneut. Eigene Projekte liegen neben dem SDK; fertige HUD-Pakete landen im Ordner ausgabe.

Die Version 0.2.0-preview.4 bezeichnet die SDK-Pakete. Sie ist unabhängig von der Protokoll-Hauptversion 2 und von der Version deines eigenen HUDs. Das ZIP macht die sOU-Pakete unabhängig vom NuGet-Abruf verfügbar; für weitere .NET-Abhängigkeiten benötigt der erste Blazor-Restore weiterhin eine Internetverbindung.

Ein Web-HUD erstellen

Vorlage und Paketidentität

dotnet new sou-hud-web -n MeinWebHud --hud-id mein-web-hud -o ./mein-web-hud

Der Zielordner mein-web-hud darf noch nicht existieren. -n bestimmt den Anzeigenamen. --hud-id ist erforderlich und bestimmt die eigene dauerhafte Paketkennung: mit einem Kleinbuchstaben beginnen, danach nur Kleinbuchstaben, Ziffern oder Bindestriche, höchstens 64 Zeichen. Unterschiedliche HUDs brauchen unterschiedliche Kennungen; eine neue Version desselben HUDs behält ihre Kennung.

Prüfe danach mein-web-hud/hud.json und ändere die version für das folgende Paketbeispiel auf 1.0.0. Behalte runtime: "web", apiVersion: 2 und entryPoint: "index.html". Der JavaScript-Client liegt bereits unter wwwroot/sdk. Den Paketbefehl findest du unter Prüfen, importieren und aktualisieren.

Daten abonnieren

Die Vorlage enthält bereits eine vollständige HTML-Seite und die folgende Verbindung. Für deinen ersten Versuch musst du sie nicht neu schreiben: Ändere in wwwroot/hud.css eine Farbe oder die Schriftgröße, erstelle das Paket wie unter Prüfen und importieren und öffne deine Ausgabe. Die folgenden Beispiele erklären anschließend, wie du eigene Datenanzeigen ergänzt.

Lade den mitgelieferten SignalR-Client vor deinem Modul. Die Dateien müssen im Paket liegen; absolute Dateipfade oder CDN-Adressen sind dafür nicht geeignet.

<script src="sdk/vendor/signalr.min.js"></script>
<script type="module" src="hud.js"></script>

Eine kleine wwwroot/hud.js kann so beginnen. Die Elemente score, caption und connection müssen in deiner HTML-Datei existieren.

import { HudClient } from './sdk/sou-hud.js';

const hud = new HudClient();
const lifetime = new AbortController();
const text = (id, value) => {
  document.getElementById(id).textContent = value;
};

hud.watch(snapshot => {
  const game = snapshot.game;
  text('score', game
    ? `${game.ct?.score ?? '–'} : ${game.t?.score ?? '–'}`
    : 'Warte auf Spieldaten');
}, {
  signal: lifetime.signal,
  status: (channel, status) => {
    if (channel === 'live') text('connection', status);
  },
  error: error => console.error('HUD-Verbindung:', error)
});

hud.watchPanel(message => {
  if (message.state) {
    text('caption', message.state.values.display?.caption || 'Mein HUD');
  }
  if (message.action?.name === 'cue') {
    // Nur auf diese neue Aktion reagieren; nicht als Einstellung speichern.
  }
}, { signal: lifetime.signal });

window.addEventListener('pagehide', () => lifetime.abort(), { once: true });

textContent setzt empfangene Texte als Text. Verwende für Teamnamen, Spielernamen und Paneltexte keine ungeprüfte HTML-Einfügung. Externe Inhalte sind Daten, kein vertrauenswürdiges Markup.

JavaScript-Clientvertrag

contracts.d.ts beschreibt die Daten für Editoren. Du kannst die vollständige Typreferenz durchsuchen oder die Vertragsdatei herunterladen; diese Datei ist kein vollständiges SDK-Paket. sou-hud.d.ts ergänzt die Clientmethoden. Der JavaScript-Client normalisiert neue Enum-Namen auf unknown, sofern der betreffende Vertrag einen solchen Wert besitzt. Du musst dafür kein TypeScript-Projekt einführen.

Ein Blazor-HUD erstellen

Nach der Vorlageninstallation erzeugst du das C#-Projekt mit eigener Kennung. Wie bei der Webvorlage ist --hud-id erforderlich:

dotnet new sou-hud-blazor -n MeinBlazorHud --hud-id mein-blazor-hud -o ./mein-blazor-hud

Passe mein-blazor-hud/hud.json mit eigener ID, Name und Version an. Das folgende Beispiel verwendet die Version 1.0.0. Behalte runtime: "blazor-wasm", apiVersion: 2 und entryPoint: "index.html". Nach deinen Änderungen veröffentlichst und paketierst du das HUD mit den folgenden Befehlen. Die Zielordner und die Ausgabedatei dürfen beim ersten Durchlauf noch nicht existieren.

dotnet publish ./mein-blazor-hud/MeinBlazorHud.csproj -c Release -o ./ausgabe/mein-blazor-paket
./werkzeuge/sou-hud pack ./ausgabe/mein-blazor-paket ./ausgabe/mein-blazor-hud-1.0.0.souhud
./werkzeuge/sou-hud validate ./ausgabe/mein-blazor-hud-1.0.0.souhud

Der Publishordner enthält bereits hud.json, LICENSE und den veröffentlichten wwwroot-Ordner. Das Manifest muss nicht mehr von Hand kopiert werden. Prüfe insbesondere, ob panel.json, Schriftdateien und Bilder mitveröffentlicht wurden. Liefere benötigte Lizenzdateien mit. Verwende bei einem weiteren Stand einen neuen beziehungsweise leeren Publishordner und eine neue Paketdatei.

Mit dem portablen SDK stellst du vor dem Publish sicher, dass die sOU-Abhängigkeiten aus dem ZIP gelesen werden. Führe dafür anstelle des ersten Publishbefehls diese beiden Befehle aus und paketiere anschließend denselben Ausgabeordner:

dotnet restore ./mein-blazor-hud/MeinBlazorHud.csproj --configfile "$sdkRoot/NuGet.Config"
dotnet publish ./mein-blazor-hud/MeinBlazorHud.csproj -c Release --no-restore -o ./ausgabe/mein-blazor-paket

Falls du die portable Vorlage direkt aus templates/blazor kopierst, heißt ihre Projektdatei zunächst Hud.csproj. Passe die Befehle dann an diesen Dateinamen an und vergib ID, Name und Version selbst in hud.json. Die installierbare Vorlage übernimmt Anzeigename und Kennung dagegen aus deinen Argumenten.

C#-Client und Lebensdauer

Die Vorlage enthält bereits die vollständige Komponente mit Live- und Panelverbindung. Ändere zuerst das Markup in App.razor oder die CSS-Datei und führe die obigen Buildbefehle aus. Der folgende Ausschnitt erläutert den Client; er ersetzt nicht die vollständige Komponente aus der Vorlage.

var hud = new HudClient(httpClient, new Uri(packageAddress));
hud.ConnectionChanged += (channel, status) => {
    // In Blazor Änderungen über InvokeAsync in die Oberfläche übernehmen.
};

await foreach (var snapshot in hud.WatchAsync(cancellationToken))
{
    if (snapshot.Game is { } game)
    {
        int? health = game.ObservedPlayer?.Health;
        string? teamId = snapshot.ManagedMatch?.Ct.TeamId;
    }
}

Benötigte Namespaces sind SOU.Hud.Sdk und SOU.Live.Contracts. WatchAsync und WatchPanelAsync sind getrennte asynchrone Streams: Starte beide parallel, wenn dein HUD beide benötigt. Ein endloser Live-Stream, den du zuerst vollständig abwartest, lässt keinen anschließenden Panel-Stream starten. Die Vorlage zeigt die parallele Ausführung mit Task.WhenAll.

Halte den übergebenen HttpClient für die Lebensdauer des HUDs bereit. Die Clientklasse verwendet die lokale Browsersitzung; eigene Zugangsdaten sind dafür nicht nötig. Bei DisposeAsync der Komponente den gemeinsamen Abbruchtoken auslösen, beide Aufgaben asynchron abwarten und die Tokenquelle freigeben. Ereignisbehandlung darf keine unbehandelten Fehler werfen. HudSdkJson.Default stellt die generierten JSON-Typinformationen für WASM und Trimming bereit.

Zustände korrekt darstellen

Ein Snapshot ist ein vollständiger aktueller Datenstand. Für eine erste Anzeige genügt game; dort findest du etwa Map und Spielstand. Für Namen und Logos deiner vorbereiteten Teams verwendest du zusätzlich managedMatch. Suche ein konkretes Feld in der Typreferenz; die API-Anleitung erklärt seine Herkunft und Bedeutung.

• Vor dem ersten GSI-Paket: game ist null. Ein ausgewähltes managedMatch kann trotzdem bereits Teams, Serie und Startzeit liefern.
• Verbindung und Frische: connected bedeutet erreichbarer Transport. Ob neue CS2-Daten vorliegen, steht in snapshot.freshness.
• Fehlende Daten: null, leere Listen und unknown unterscheiden. Aus fehlenden HP keinen Tod, aus fehlendem Spielstand kein 0:0 und aus einer leeren Mapliste kein Veto erfinden.
• Seiten: Die fertige Team-ID aus managedMatch.ct beziehungsweise managedMatch.t verwenden. Bildschirmseite, Spielerreihenfolge und CT/T allein ergeben keine dauerhafte Teamidentität.
• Sitzungswechsel: Ändert sich sessionId, eigene sitzungsgebundene Animationen und Zwischenspeicher zurücksetzen. Ein einzelner Stream enthält vollständige Zustände, keine garantiert lückenlose Ereignisfolge.
• Panel: Zustand erneut anwenden können. Einmalige Aktionen nur beim Eintreffen behandeln; nach Reconnect kommen vergangene Aktionen nicht erneut.
• Medien: Fehlende Bilder mit einer passenden leeren Darstellung behandeln. Namen, Logos oder Fotos unbekannter Teams und Spieler nicht ersetzen, als wären sie echte Profildaten.

Prüfen, importieren und aktualisieren

Für das Webprojekt aus dieser Anleitung erzeugst du nach deinen Änderungen ein Paket mit den folgenden Befehlen. Die Ausgabedatei darf noch nicht existieren; verwende bei weiteren Paketständen eine neue Version in Manifest und Dateiname.

./werkzeuge/sou-hud pack ./mein-web-hud ./ausgabe/mein-web-hud-1.0.0.souhud
./werkzeuge/sou-hud validate ./ausgabe/mein-web-hud-1.0.0.souhud

pack erstellt und prüft das Archiv. validate prüft ein vorhandenes Archiv auf die Installationsanforderungen von sOU. Ohne Argumente oder mit falscher Syntax liefert das Werkzeug Exitcode 2, bei abgewiesenen Paketen Exitcode 1, bei erfolgreicher Prüfung Exitcode 0. Die Blazor-Paketierung ist im Blazor-Abschnitt beschrieben.

Importiere ein gültiges Paket unter HUDs → Paket importieren. Öffne seine angebotene Adresse oder seine OBS-/Overlay-Ausgabe. Ein direkter Start von index.html per file:// besitzt weder die Paketidentität noch den lokalen Transport. Details zum Benutzerablauf stehen unter HUDs installieren und HUDs ausgeben.

Prüfe vor einer Weitergabe mindestens den Start ohne Spiel, ein vorbereitetes Match vor GSI, fehlende Teamzuordnung, veraltete Daten, Seitenwechsel, Host-Neustart, Paneländerungen und Reconnect. Prüfe außerdem die tatsächliche Zielauflösung in OBS, Transparenz, lange Namen und fehlende Medien. Synthetische Daten gehören ausschließlich in einen getrennten Entwicklungsbetrieb, niemals in einen laufenden echten Cast.

Für jedes geänderte Paket eine neue Version erzeugen. Eine bereits installierte Kombination aus ID und Version ist unveränderlich. Laufende Ausgaben bleiben an ihrer geladenen Version; die stabile Adresse wählt beim nächsten Laden die vom Host angebotene Version. Die Versionsregeln und die Übernahme von Panelwerten erklären die Folgen für Updates.

Dein HUD Schritt für Schritt erweitern

1. Eigene Gestaltung: HTML beziehungsweise Razor und CSS ändern. Die vorhandenen IDs der Webvorlage erhalten, solange hud.js sie verwendet. Paketkennung und erste Version in hud.json festlegen.
2. Erste eigene Datenanzeige: Im vorhandenen Empfangscode ein Feld aus dem Snapshot lesen. Beispielsweise liefert snapshot.game?.map in JavaScript beziehungsweise snapshot?.Game?.Map in Razor den Mapnamen. Ohne Map einen leeren Text oder einen Wartezustand anzeigen.
3. Bedienfelder: wwwroot/panel.json anpassen und die empfangenen Werte im HUD anwenden. Ein Feld im Panel erzeugt noch keine Darstellung im HUD. Das vollständige Panelbeispiel erklärt Schema, Werte und Aktionen.
4. Bilder und weitere Ansichten: Eigene Assets im Paket ablegen; Medien aus sOU über media beziehungsweise Media auflösen. Zusätzliche Ausgaben als Subviews im Manifest anmelden.
5. Änderung ausprobieren: Version in hud.json erhöhen, etwa von 1.0.0 auf 1.0.1. Web erneut paketieren; Blazor erneut veröffentlichen und dessen neue Dateien in einen neuen Paketordner kopieren. Neue Namen für Publishordner, Paketordner und Ausgabedatei verwenden, damit keine alten Dateien in den nächsten Stand geraten. Danach importieren und die Ausgabe neu laden.

Die laufende Ausgabe wechselt nicht automatisch zur neuen Version. Kontrolliere bei einer scheinbar unveränderten Darstellung zuerst die installierte Version und lade die Ausgabe neu. Bewahre deinen Quellprojektordner auf: Die fertige .souhud-Datei ist für Installation und Weitergabe gedacht.

Wenn der erste Versuch nicht funktioniert

Ressourcen, Rechte und Vertrauensmodell

Die eigenen Bestandteile des sOU-SDK und die eigenen Vorlagen stehen unter der MIT-Lizenz. Du darfst sie auch für kostenpflichtige und geschlossene HUDs verwenden. Bei Weitergabe von SDK-Code müssen dessen Lizenz- und Urheberrechtshinweise erhalten bleiben; dein eigener HUD-Quellcode muss durch diese Lizenz nicht veröffentlicht werden. Mitgelieferte Fremdsoftware behält ihre jeweiligen Lizenzbedingungen.

Native HUDs beziehen Skripte, Schriften und Bilder aus ihrem Paket oder über die vorgesehenen lokalen Medienpfade. Die Hostrichtlinie erlaubt keine beliebigen externen Skripte oder Netzverbindungen. Beachte die Lizenzen deiner eigenen Abhängigkeiten und Grafiken; die SDK-Vorlagen enthalten keine fremden Echo-, DCM- oder JT-Grafiken als frei übernehmbare Gestaltung. Lizenzhinweise des mitgelieferten SignalR-Clients müssen erhalten bleiben.

Importierte Pakete teilen eine lokale Origin. Paketprüfung und getrennte Paneladressierung sind keine Sandbox zwischen fremden Skripten. Verwende nur Pakete, deren Herkunft du vertraust. Das SDK stellt die lokale HUD-Verbindung ohne Zugangsdaten im Paket her. Kontopasswörter, Zugriffstokens und andere private Zugangsdaten gehören weder in Paketdateien noch in Browseradressen oder HUD-Logs. Das vollständige Datenmodell steht in der HUD-API-Referenz, Bedienfelder in der Panelreferenz.