HUD-API und Datenverträge

Die lokale HUD-API liefert deinem HUD den aufbereiteten Zustand des aktuellen CS2-Casts. Die Verbindung erfolgt direkt zur laufenden sOU-App auf demselben Rechner. Der SDK-Client empfängt vollständige Spielzustände über SignalR und verwendet die Datenverträge aus SOU.Live.Contracts. Für neue Browser-HUDs ist der SDK-Client der direkte Einstieg. Ergänzend stehen die vollständige durchsuchbare Typreferenz und die SDK-Vertragsdatei als Download bereit.

Welche Daten brauche ich für meine Anzeige?

Für ein neues HUD beginne mit der installierbaren SDK-Vorlage. Ihr Client stellt die Verbindung her; du ergänzt im Empfangscode die gewünschte Anzeige. Die Endpunktbeschreibung in diesem Kapitel brauchst du vor allem, wenn du den Transport selbst implementieren oder einen Verbindungsfehler untersuchen möchtest.

Die Codebeispiele verwenden JavaScript-Eigenschaften in camelCase. In C# heißen dieselben Eigenschaften beispielsweise Game, ObservedPlayer und ManagedMatch. Die Typreferenz führt jedes Feld auf; dieses Kapitel erklärt, wie du die gelieferten Werte fachlich verwendest.

Version und allgemeine Konventionen

• Die aktuelle Schema-Hauptversion ist 2. schemaVersion im Snapshot und apiVersion im Paketmanifest müssen zu diesem Vertrag passen.
• JSON-Eigenschaften und Enumwerte sind camelCase: roundNumber, counterTerrorists, freezeTime. Numerische Enum-Ordnungswerte gehören nicht zum Protokoll.
• Ein fehlender optionaler Wert ist null. Ein vorhandener unbekannter Enumname wird zu unknown. Ein falscher Datentyp ist kein gültiger Ersatz für einen fehlenden Wert.
• Steam-IDs und fachliche Kennungen bleiben Strings. Steam-IDs nicht in JavaScript-Zahlen umwandeln; dabei kann Genauigkeit verloren gehen.
• UUIDs werden als Strings, DateTimeOffset-Werte als ISO-8601-Zeitpunkte mit Offset übertragen. receivedAt ist Empfangszeit, keine Spielzeit.
• Rundennummern, Mapnummern und Vetoschrittnummern beginnen bei 1. Observer-Ziffern folgen dagegen 1…9,0.
• Zeitdauern sind numerische Sekunden, erkennbar an Namen wie secondsRemaining. Vektoren verwenden unveränderte CS2-Welteinheiten.
• null bei einer optionalen Liste bedeutet nicht verfügbar; [] bedeutet explizit leer. Bei der immer vorhandenen Spielerliste hilft zusätzlich availableSections.

Additive Felder können innerhalb von v2 hinzukommen. Ein Consumer muss unbekannte JSON-Eigenschaften tolerieren und für neue Enumwerte einen passenden unbekannten Zustand darstellen. Die SDK-Version und deine Paketversion werden unabhängig davon versioniert. Alte v1-Adressen werden nicht als Alias auf v2 umgeleitet.

Endpunkte und Zugriff

Der lokale Host lauscht standardmäßig auf http://127.0.0.1:5085. Der Port ist konfigurierbar; verwende im HUD die Origin der geladenen Paketadresse. Fest eingetragene Cloud- oder Standardportadressen verhindern den korrekten Betrieb bei anderer lokaler Konfiguration.

Der Host akzeptiert nur Loopback-Verbindungen und die Hostnamen 127.0.0.1 beziehungsweise localhost. Falls eine Origin mitgesendet wird, muss sie genau zur lokalen HTTP-Origin einschließlich Host und Port passen. Ein fehlender oder falscher Browsercookie ergibt bei den HUD-Streams HTTP 401; unerlaubter Ursprung oder ein fehlender Sitzungsheader ergibt HTTP 403. Das ist keine LAN-API.

Der Browsercookie ist HttpOnly und SameSite=Strict; sein Name enthält den lokalen Port. Er wird vom Host erzeugt und nach Host-Neustart erneuert. Das SDK führt die Sitzungserstellung vor jedem Verbindungsversuch aus. Für diese Verbindung sind keine Zugangsdaten im Paket erforderlich. Kontopasswörter oder Zugriffstokens gehören weder in Paketdateien noch in Browseradressen oder JavaScript.

Die HUD-Verbindung dient zum Lesen von Spielzuständen, Medien und Panelnachrichten. Sie bietet weder Schreibzugriff auf Live-Daten noch Kamerasteuerung oder Kontoverwaltung. Vollständige GSI-Rohpakete und darin enthaltene Authentifizierungsdaten werden nicht an das HUD weitergegeben. Mehr zur Einrichtung der Datenquellen unter CS2 und HLAE.

Stream, Wiederverbindung und Datenfrische

Watch liefert unmittelbar den aktuellen vollständigen Snapshot und anschließend vollständige neue Zustände. Es handelt sich nicht um JSON-Patches. Bei langsamem Lesen können Zwischenrevisionen entfallen; verarbeite deshalb jeden empfangenen Snapshot als vollständigen Zustand und verlasse dich nicht auf eine lückenlose Folge einzelner Änderungen.

Die SDK-Clients melden connecting, connected, reconnecting und stopped getrennt je Kanal. Bei Transportabbruch erstellen sie die Browsersitzung erneut und abonnieren wieder; zwischen Versuchen liegt ungefähr eine Sekunde. Das setzt keinen erneuten Seitenaufbau voraus. Die Behandlung einer unterbrochenen oder veralteten Darstellung bleibt Aufgabe deines HUDs.

freshness bezieht sich auf den Empfang von GSI. Standardmäßig wird der Zustand ab 15 Sekunden ohne neues GSI stale und ab 45 Sekunden disconnected. Die Schwellen sind lokale Hostkonfiguration. Ein funktionierender SignalR-Stream kann gleichzeitig einen veralteten GSI-Zustand liefern. Bibliotheks- und HLAE-Änderungen machen GSI nicht künstlich frisch.

LiveSnapshot

{
  "schemaVersion": 2,
  "sessionId": "00000000-0000-4000-8000-000000000001",
  "revision": 0,
  "receivedAt": null,
  "freshness": "waiting",
  "game": null,
  "managedMatch": null
}

Das Beispiel beschreibt einen leeren Ausgangszustand. Die tatsächliche sessionId wird zur Laufzeit vergeben. Sie kann sich unter anderem bei der ersten GSI-Nachricht, einem Mapwechsel, einer rückläufigen Rundennummer oder beim Übergang aus gameOver ändern. Setze dann sitzungsgebundene Animationen und Zwischenspeicher zurück. Die ID beschreibt keine vollständige Demo-Timeline.

GameState: Match und Spielbereiche

SideState enthält name: string?, score: int?, flag: string?, consecutiveRoundLosses: int?, timeoutsRemaining: int? und matchesWon: int?. Die an CT/T gemeldeten Namen sind kein Ersatz für die zentrale Auflösung in managedMatch.

Spieler, Ausrüstung und Statistik

Als Coach markierte Profile erscheinen nicht in den Spieler-, Radar- und Killfeed-Daten des HUDs. Verwende die gelieferten Observer-Ziffern unverändert. Leite Teamidentitäten aus den zugeordneten Teams ab, nicht aus der Position eines Spielers in der Liste.

WeaponState

Eine Waffe enthält slot: string, name: string?, kind: WeaponKind?, type: WeaponCategory?, state: WeaponStatus?, paintKit: string?, ammoClip: int?, ammoClipMax: int? und ammoReserve: int?. name erhält die offene Quellkennung, kind bezeichnet eine bekannte konkrete Waffe, type deren Kategorie. Eine unbekannte Waffenkennung nicht anhand eines Namenspräfixes einer bekannten Waffe gleichsetzen.

RecordedPlayerStats

Die Felder sind rounds: int, damage: long, kills: long, headshotKills: long und coversWholeMatch: bool. averageDamagePerRound: double? ist Schaden geteilt durch erfasste abgeschlossene Runden; ohne solche Runden null. headshotPercentage: double? ist der Headshot-Anteil an den erfassten Kills; ohne Runden oder Kills null.

coversWholeMatch entscheidet, ob du den Wert als vollständige Matchstatistik bezeichnen darfst. Später Einstieg oder Datenlücken erlauben keine vollständige rückwirkende Statistik. Teilstatistik sichtbar als solche behandeln.

Bomben, Granaten, Timer und Quellmetadaten

Ein Countdown kann zwischen zwei Meldungen grafisch fortgeschrieben werden, ist aber keine Zusage eines gemeinsamen Demo-Ticks, einer Wiedergabegeschwindigkeit oder zuverlässiger Pausensynchronisation. Für einen solchen Verlauf liefert der Vertrag noch kein vollständiges Zeitmodell. Nach Sitzungswechsel und veralteten Daten eigene Timer korrigieren oder anhalten.

ManagedMatch: dauerhafte Identität und Serienkontext

managedMatch beschreibt das aktiv ausgewählte Match aus der Bibliothek. Es ist unabhängig davon, ob GSI bereits ein Spiel liefert. Änderungen an Teams, Maps oder Wettbewerb erzeugen neue Snapshotrevisionen, ohne den GSI-Empfangszeitpunkt zu verändern.

Teams und Seitenauflösung

ManagedTeam enthält id, name, shortName als Strings, logo: string? und seriesWins: int. TeamSideResolution enthält side: TeamSide, status: TeamRecognitionStatus, teamId: string? sowie teamAScore und teamBScore als Integer.

Die letzten beiden Zahlen sind Trefferzahlen eindeutiger Steam-IDs bei der Teamzuordnung, keine Rundenpunkte. Rundenpunkte stehen in game.ct.score und game.t.score. Der Host unterscheidet recognized, inferred, manual, noMatch, tied, conflicting und unknown. Verwende die gelieferte teamId; eine fehlende Zuordnung bleibt offen.

Spielmaps, Veto und Ergebnisse

ManagedMatchMap enthält id, name, gameName, number sowie optional kind, status, scoreA, scoreB und winnerTeamId. number ist die Spielposition ab 1. Punkte beziehen sich immer auf die verwalteten Gegner A/B, nicht auf aktuelle CT/T. status ist pending, live, completed oder unknown; ältere Daten können null enthalten.

ManagedVeto enthält mapId, name, gameName, type, teamId: string?, number und playNumber: int?. number ordnet den Vetoablauf; playNumber ordnet eine gespielte Map. Ein Ban ist keine gespielte Map. Aus bloßer Listenreihenfolge keinen Picker, Sieger oder Ban ableiten.

Wettbewerbsdaten

ManagedCompetition enthält id, name, seasonId, seasonName, sections, round, logo, sponsors, sectionId und structure. Optionale Texte, Logo, Sponsorbestand und Struktur können fehlen. sections ist der geordnete Vorfahrenpfad des zugeordneten Bereichs; sectionId bezeichnet die genaue Zuordnung.

• Ein Pfadeintrag enthält id, name und kind.
• Ein Sponsor enthält id, name und image als lokale Medienreferenz.
• structure.seasons enthält alle konfigurierten Seasons mit id, competitionId und name.
• structure.sections enthält alle Bereiche mit id, competitionId, seasonId?, parentId?, name und kind.

Ein HUD kann den zugeordneten Bereich und dessen Eltern anzeigen, ohne selbst die Matchzuordnung zu erraten. Eine komplette Turnierbaum-Auswertung oder Siegerlogik entsteht daraus nicht automatisch.

HLAE-Radar und Killfeed

RadarState enthält connectionId: UUID, epoch: long, sequence: long, gameTimeSeconds: double, receivedAt: Zeitpunkt und players: RadarPlayer[]. Jeder RadarPlayer enthält steamId: string, pawnHandle: uint, position, forward und health: int.

Radar ergänzt GSI und verändert dessen PlayerState.position nicht. Der Host ordnet HLAE-Spieler vorhandenen GSI-Identitäten zu. Radar mit falscher Map, überholter Sequenz oder nicht passender Verbindung wird nicht als neuer Zustand übernommen. Ein veralteter Radarbestand wird nach ungefähr 750 Millisekunden ohne passende Aktualisierung entfernt; game.radar kann daher wieder null werden.

Ein KillFeedEntry enthält id: long, connectionId: UUID, epoch: long, gameTimeSeconds: double, killer: KillParticipant?, victim: KillParticipant, assister: KillParticipant?, weapon: string, weaponKind: WeaponKind sowie die booleschen Modifikatoren flashAssist, headshot, wallbang, attackerBlind, throughSmoke und noScope.

KillParticipant besitzt entityIndex: int, steamId: string?, name: string? und side: TeamSide?. Verwende zur Ereignisidentität die Kombination aus Verbindung, Epoche und ID; ein alleiniger numerischer Zähler ist über Neustarts nicht eindeutig. Der Bestand ist auf höchstens 32 Einträge begrenzt und wird an relevanten Sitzungs-/Rundenübergängen zurückgesetzt.

Ein wiederholter Snapshot mit denselben Einträgen ist kein neuer Kill. Der Bestand ist weder eine vollständige Matchhistorie noch eine allgemeine Ereignisschnittstelle für Schaden, Schüsse oder Bombenaktionen. Aus einem Wechsel der HP auf null keinen zusätzlichen Kill erzeugen.

Wichtige Enumwerte im JSON

WeaponKind und MapKind enthalten den konkreten bekannten Inhaltskatalog, beispielsweise ak47, awp, m4A1S sowie mirage, nuke und ancient. Die vollständigen Listen stehen in der Typreferenz für WeaponKind und MapKind sowie in der mitgelieferten contracts.d.ts. Verwende die mit deinem SDK gelieferten Werte und behalte den Fallback unknown; eine neue CS2-Kennung darf die Darstellung nicht zum Absturz bringen.

Grenzen, die ein Consumer berücksichtigen muss

• Snapshots können Zwischenzustände überspringen; sie sind keine garantiert lückenlose Ereignisaufzeichnung.
• Es gibt keinen vollständigen gemeinsamen Demo-Zeitvertrag und keinen typisierten Kameravertrag mit FOV und Observer-Modus.
• Spielerkameras und Live-Videobilder sind keine GSI-Felder und werden nicht durch diese API geliefert.
• Aufgezeichnete Statistiken können nur die beobachteten Zeiträume abdecken; coversWholeMatch beachten.
• Unbekannte Teams, fehlende Medien und nicht verfügbare Geometrie bleiben fehlend. Datenverfügbarkeit nicht mit einem geschlossenen Null- oder Standardwert verwechseln.
• HUD-Browsersitzung und gemeinsame Origin sind ein Vertrauensmodell für lokale Pakete, keine Isolation zwischen beliebigem fremdem Code.

Die ergänzende Panelreferenz beschreibt den getrennten Bedienkanal. Für bestehende Fremd-HUDs gilt zusätzlich das LHM-/JT-Kompatibilitätsprofil.