Datenbedeutung und Randfälle

Dieser Leitfaden erklärt die Bedeutung und Grenzen der Daten im SDK 0.3.0-preview.2 mit HUD-API 3. Er ergänzt die HUD-API-Anleitung, die SDK-Laufzeitreferenz und die vollständigen Typdefinitionen. Die Beispiele zeigen unveränderte öffentliche Feldnamen; sie sind keine zusätzlichen Nachrichtenarten.

Unbekannt, leer und null sind verschiedene Zustände

Die Regeln gelten auf unterschiedlichen Ebenen: Eine ausgelassene Objektersetzung in objects lässt das bisherige Objekt unverändert. Eine vorhandene Ersetzung enthält ein vollständiges typisiertes Objekt; seine Nullable-Felder werden übernommen und nicht mit alten Feldwerten aufgefüllt. removed: true entfernt ein Objekt und enthält keinen Nutzdatenblock. Ein snapshot ersetzt die gesamte Objektbasis.

Welche Quelle liefert welchen Bereich?

availableSections nennt vorhandene GSI-Bereiche. Die Liste ist weder eine Berechtigungsübersicht noch ein Versprechen, dass darin jedes Feld oder jeder Spieler geliefert wurde. Ein fehlender Bereich bleibt unbekannt. Details: GSI-Bereiche.

Identitäten, Quellrollen und Reihenfolge

Spielerschlüssel sind opak und sitzungsgebunden. Verwende Roster.Players / roster.players in der gelieferten Reihenfolge und löse jeden Schlüssel mit Player(key) / player(key) auf. Die Dictionary- oder Map-Reihenfolge ist keine Kaderreihenfolge. Konstruiere Schlüssel weder aus Steam-IDs noch aus Namen oder Listenpositionen. Dieselbe Steam-ID darf in mehreren Quellrollen vorkommen.

Namen sind Anzeigetext, keine Identität und kein HTML. Blazor-Textbindung oder textContent verwenden; keine zusätzliche HTML-Dekodierung und kein innerHTML. Steam-IDs bleiben Strings, damit JavaScript sie nicht rundet. Kaderreferenz und Identität beschreiben die vollständige Form.

Die sechs Spielerteile lesen

Beispiel: 0 HP erhalten, unbekannte HP offen lassen

Dieses vollständige HudPlayerVitalsV3-Objekt beschreibt bekannte 0 HP, eine bekannte fehlende Helmausrüstung und einen unbekannten Smokewert. Es erzeugt selbst kein Killereignis.

{
  "activity": "playing",
  "health": 0,
  "armor": 0,
  "helmet": false,
  "flashed": 0,
  "smoked": null,
  "burning": 0
}

Die folgenden reinen Formatierfunktionen nehmen einen bereits übernommenen SDK-Sitzungszustand entgegen. Sie zeigen bei bekanntem 0 den Wert und bei fehlendem Zustand einen Platzhalter. C# verwendet den generischen Optionstyp der eigenen Sitzung; JavaScript erhält dasselbe HudSessionSnapshot-Konzept.

using SOU.Hud.Sdk;

static string HealthLabel<TOptions>(HudSessionSnapshot<TOptions> state)
{
    if (!state.Ready) return "—";
    var health = state.Game?.ObservedPlayer?.Vitals.Health;
    return health?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "—";
}

function healthLabel(state) {
  if (!state.ready) return '—';
  const game = state.game;
  const key = game?.roster?.observed;
  const player = key == null ? null : game.player(key);
  const health = player?.vitals.health;
  return health == null ? '—' : String(health);
}

Inventardefinition und Waffenlaufzeit verbinden

Die Definition sagt, welche Waffe ein Slot enthält; die Laufzeit sagt, was sie gerade tut. HudWeaponDefinitionV3 und HudWeaponRuntimeV3 verwenden denselben slot. Beide Listen sind gemeinsam verfügbar oder beide null; der Reducer prüft gleiche Länge und passende Slotfolge. Für den fachlichen Join trotzdem den Slot verwenden und keine festen Indizes für Primärwaffe, Pistole oder Messer annehmen.

Diese zwei zusammengehörigen JSON-Objekte sind vollständige HudPlayerEquipmentV3- und HudPlayerWeaponsV3-Nutzdaten. Ein Munitionswechsel kann nur das zweite Objekt ersetzen.

{
  "defuseKit": false,
  "money": 0,
  "equipmentValue": 2700,
  "weapons": [
    { "slot": "weapon_0", "name": "weapon_ak47", "type": "rifle", "paintKit": null, "kind": "ak47" }
  ]
}

{
  "weapons": [
    { "slot": "weapon_0", "state": "reloading", "ammoClip": 0, "ammoClipMax": 30, "ammoReserve": 90 }
  ]
}

Für eine aktive Waffenanzeige einen gelieferten Status active oder reloading wählen. holstered ist keine aktive Waffe. Bei sicherem Tod alte Ausrüstung nicht als aktuellen Besitz ausgeben. Eine bekannte leere Liste leert die Anzeige; ein unbekannter Waffenname erhält einen begrenzten Text oder ein neutrales Symbol. kind ist die bekannte Typisierung, name die offene Quellkennung; ein Namenspräfix ist kein Beweis für eine bestimmte Waffe.

Map, Runde, Seiten und verwaltetes Match

Weitere Felder: Spielinformationen, verwaltetes Match und Seitenauflösung.

Statistik und Abdeckung richtig beschriften

Vollständige Formen: MatchStats und RecordedPlayerStats. Die Erfassung zählt beobachtete Rundenergebnisse einmal; ein erneuter Render darf keine Statistik hochzählen.

Geometrie, HLAE-Radar, Granaten und Kills

CS2-Weltkoordinaten benötigen die Kalibrierung der konkreten Karte; sie sind keine Pixel. forward ist ein Richtungsvektor. Fehlende Positionen bleiben fehlend, auch wenn die Anzeige einen Marker erwartet. Das Radar benutzt HLAE-Verbindung, Epoche, Sequenz und receivedAt als eigenen Quellkontext. Der vorübergehende pawnHandle ersetzt keine Steam-ID und ist keine dauerhafte Identität über Respawns.

Verwende einen frischen HLAE-Stand als gemeinsame Markerquelle. Ein dort fehlender Spieler wird nicht mit seiner älteren GSI-Pose ergänzt. Erst wenn der HLAE-Stand insgesamt nicht verwendbar ist, kann das HUD auf vorhandene GSI-Posen zurückfallen. Der aktuelle Desktop entfernt einen mindestens 750 ms alten Radarstand; das ist keine allgemeine Aktualitätsgarantie des WebSockets. Bei Verbindungs-, Epochen-, Map- oder Spielsitzungswechsel eigene Interpolationen zurücksetzen.

Granaten liefern optionale Position, Geschwindigkeit, lifetimeSeconds, effectTimeSeconds und Flammenpunkte. Die beiden benannten Zeitwerte sind Sekunden; aus ihnen keine unbelegte absolute Endzeit oder Wiedergabegeschwindigkeit konstruieren. Vektoren bleiben Quellgeometrie; ohne dokumentierte Kalibrierung keine SI-Einheiten oder Etage behaupten. Granatenart und Waffenart sind verschiedene Enums.

Ein Kill wird durch connectionId, epoch und id zusammen identifiziert. Seine gameTimeSeconds gehören zur HLAE-Spielzeit. Der gelieferte Bestand ist begrenzt und wird bei Kontextwechseln erneuert; nach Reconnect ist er kein Archiv fehlender Ereignisse. Wiederholtes Lesen oder Rendern desselben Eintrags erzeugt keine neue Animation. Aus health: 0, einem unbekannten Angreifer oder einer unbekannten Waffenkennung keine zusätzlichen Kills oder einen Suizid ableiten.

Radarreferenzen, Radarmarker, Granaten und Killfeed führen die einzelnen Felder auf.

Zeitstempel und Einheiten nicht vermischen

Uhrbereitschaft, Ablauf und Countdown

HudClockSample enthält nur die Serverzeitprobe. Der Host misst die Laufzeit; der C#-Uhrkern und die Browserintegration akzeptieren keine Probe mit einer Laufzeit über zwei Sekunden. Ein angenommener Anker wird monoton fortgeschrieben und läuft nach mehr als 90 Sekunden ohne gültige Erneuerung ab. Sichtbarkeitswechsel, suspendierte Browserdokumente und Verbindungswechsel können die Bereitschaft zusätzlich aufheben. Das sind Uhrgrenzen, keine Frischegrenzen der Spieldaten.

{
  "serverTime": "2026-10-28T12:00:00+00:00"
}

Ein fehlgeschlagener Erneuerungsversuch ersetzt keinen noch gültigen Anker. Ein alter oder nach Invalidierung eintreffender Versuch darf eine neue Generation nicht bereit machen. Nutze hudClock.isReady() vor hudClock.now(); C# kann HudClock.TryGetUtcNow prüfen. Eine noch nicht bereite strikte Uhr wirft beim direkten Lesen. Der Blazor-Host bindet seine Inhalte an die Uhrbereitschaft. Die ready-Eigenschaft der Datensitzung ist davon unabhängig.

Die Countdownhelfer erhalten den ursprünglichen Quellanker. Ohne gültigen Sekundenwert bleibt das Ergebnis unbekannt. Ohne Empfangszeit bleibt ein laufender Countdown unbekannt; eine ausdrücklich pausierte Berechnung hält dagegen den gelieferten Sekundenwert fest. Negative Ergebnisse werden auf null begrenzt, ein in der Zukunft liegender Empfang darf den Quellwert nicht erhöhen. Eine Pause nicht allein aus einem alten oder fehlenden Paket ableiten.

Dieses JavaScript-Beispiel läuft in einem bereits aufgebauten SDK-HUD. Es zeigt bei unbereiter Sitzung, nicht frischen GSI-Daten oder unbereiter Uhr einen Platzhalter. countdownRemaining erwartet Sekunden und liefert Sekunden, während hudClock.now() Millisekunden liefert. subscribe der Uhr meldet Bereitschaftsänderungen und ist kein Animationstakt.

import { hudClock, countdownRemaining } from './sdk/sou-hud.js';

function countdownLabel(state) {
  const graph = state.game;
  if (!state.ready || graph?.freshness !== 'live' || !hudClock.isReady()) return '—';
  const countdown = graph.clock?.countdown;
  const paused = countdown?.phase === 'paused';
  const seconds = countdownRemaining(
    countdown?.secondsRemaining, graph.receivedAt, hudClock.now(), paused);
  return seconds == null ? '—' : String(Math.ceil(seconds));
}

Sitzungsrevision und Spielrevision auseinanderhalten

Die äußere Sitzungs-ID und die innere Spielsitzungs-ID sind getrennte Identitäten. Ein Reconnect erhält eine neue äußere Basis; die innere Spielsitzung kann dieselbe bleiben. Eine neue Map oder ein anderer Spielkontext kann die Spielsitzung wechseln. Revisionswerte bleiben im gemeinsamen exakt vergleichbaren Ganzzahlbereich bis 9007199254740991.

Das folgende vollständige innere Update setzt eine bereits angenommene Spielbasis mit Revision 7 und einem vollständigen Spieler unter player-7 voraus. Der Sprung auf Revision 10 ist mit passender Basis zulässig. Es ist keine äußere HudSessionMessageV3-Nachricht.

{
  "schemaVersion": 3,
  "kind": "update",
  "sessionId": "22222222-2222-2222-2222-222222222222",
  "baseRevision": 7,
  "revision": 10,
  "receivedAt": "2026-10-28T12:00:00+00:00",
  "freshness": "live",
  "objects": [{
    "kind": "playerVitals",
    "key": "player-7",
    "removed": false,
    "vitals": {
      "activity": "playing", "health": 37, "armor": 85,
      "helmet": true, "flashed": 0, "smoked": null, "burning": 0
    }
  }]
}

Atomare Übernahme und ungültige Bündel

Ein Bündel ersetzt oder entfernt ganze typisierte Objekte. Ein referenzierter Spieler benötigt alle sechs Teile; Kader-, Granaten-, Radar- und Killreferenzen müssen zum endgültigen Bündel passen. Neue Referenzen und ihre Objekte können in derselben Nachricht ankommen. Ihre Reihenfolge innerhalb von objects ist keine schrittweise sichtbare Animation: Der Reducer prüft den Gesamtzustand vor der Veröffentlichung.

Doppelte Objektschlüssel, falsche Nutzdatenarten, fehlende Referenzziele, verwaiste Objekte, widersprüchliche Waffenlisten, nicht endliche Zahlen und eine falsche Revisionsbasis können das Bündel ungültig machen. Es wird kein gültiger Teil davon veröffentlicht. Die hohe SDK-Laufzeit setzt beim daraus folgenden Neuverbinden alle vier Sitzungsdomänen zurück und wartet auf eine vollständige Basis. Ein eigener Adapter darf nach einer Lücke keine beliebigen Deltas überspringen und weiterrechnen.

Übernommene Graphen und JavaScript-Daten sind unveränderlich; alte Zustände beobachten keine künftigen Reduceränderungen. Unveränderte Teile können dieselbe Referenz behalten. C#-Optionstypen als eigene unveränderliche Records behandeln. UI-Zustand, Animationen und Auswahlcaches getrennt halten und bei Quell- oder Sitzungswechsel zurücksetzen.

Bereitschaft, Verbindung und Frische getrennt prüfen

Die üblichen konfigurierbaren GSI-Hostschwellen sind 15 Sekunden bis stale und 45 Sekunden bis disconnected. Maßgeblich ist die gelieferte Frische; keine pauschale Zusage über jeden Host ableiten. HLAE-, Panel-, Ansichts- und Optionsnachrichten machen GSI nicht frisch. Ein gültiger Uhranker macht einen alten Rundentimer ebenfalls nicht frisch.

Panelwerte, Referenzen und einmalige Aktionen

Der Panelzustand enthält values und references, jeweils nach Abschnitt und Feldname indiziert. Text / text erhält einen ausdrücklich leeren String; Flag / flag unterscheidet echte boolesche Werte von anderen JSON-Typen. Ein Fallback ist eine lokale Präsentationsentscheidung, keine Änderung des empfangenen Werts. Eine Referenz mit missing: true bedeutet, dass das ausgewählte Ziel nicht mehr verfügbar ist; keine Daten des vorherigen Ziels anzeigen.

Eine HudPanelAction ist ein einzelner Befehl mit ID, Abschnitt, Name und optionalem Wert, kein dauerhaftes Checkboxfeld. Der Handler läuft nach der Zustandsübernahme. Aktionen gehören nicht zur Erstbasis und werden beim Reconnect nicht wiederholt. Eine Unterbrechung kann vergangene Aktionen auslassen; die Sitzung verspricht keine nachträgliche Zustellung oder dauerhafte Ereignishistorie. Eigenes Wiederabspielen beim Rendern vermeiden.

Panelzustand, Panelreferenz und Panelaktion beschreiben die Daten; die SDK-Laufzeitreferenz erklärt Abonnements und Fehlerereignisse.

Fehler, Reset, Wiederverbinden und Dispose

StartAsync / start startet eine Instanz einmal und wartet nicht auf einen erreichbaren Server. Completion / completion verfolgt die Lebensdauer. Transport- und Protokollfehler warten vor weiteren Versuchen 1, 2, 5 und danach höchstens 10 Sekunden; eine angenommene Basis setzt den Retryfortschritt zurück. Der SDK-Kanal bleibt v3 und fällt nicht still auf v2 oder regelmäßige Spielzustandsabfragen zurück.

Ein Neustart der Verbindung ist kein Beweis für eine neue Map; ein neuer Spielkontext ist kein Ersatz für den Reset eigener Caches. Ein hoher Render- oder Abotakt erzeugt keine zusätzlichen Quellmessungen. Wähle für Datenanzeigen kleine Selektoren, für Timer einen separaten Uhrtakt und für animierte Übergänge explizite Regeln zu Map, Sitzung, Epoche und Frische.