SDK-Laufzeitreferenz · Dokumentation

Geltungsbereich und Einstieg

Referenz zur öffentlichen Laufzeit von SDK 0.3.0-preview.2 mit HUD-API 3: SOU.Hud.Sdk, SOU.Hud.Sdk.Blazor und JavaScript sdk/sou-hud.js. C# verwendet .NET 10. Der veröffentlichte Desktop 0.3.34 enthält die passende gemeinsame v3-Sitzung. Erforderlich ist ein Host mit dieser Sitzung; das SDK vergleicht keine numerische Desktop-Mindestversion.

Der Entwicklungsleitfaden erklärt Installation, CLI, Vorlagen, Vorschau und Paketierung. Die Datenreferenz beschreibt Quellen und Bedeutung, die Typreferenz Vertragsfelder. Weitere Regeln stehen in Panelreferenz und Paketformat.

Ein neues HUD verwendet eine Sitzung je Ausgabe. Blazor verwendet SouHudHost. C#-Typen liegen, soweit nicht anders genannt, in SOU.Hud.Sdk, Graph und Serveruhr in SOU.Live.Contracts, Komponenten in SOU.Hud.Sdk.Blazor. JavaScript importiert Exporte aus sdk/sou-hud.js; vorher den mitgelieferten SignalR-Client laden. — in Tabellen bedeutet keine direkte Entsprechung.

Sitzung erzeugen, starten und beenden

C# / Blazor	JavaScript	Vertrag
`new HudSession<TOptions>(HudClient client, JsonTypeInfo<TOptions> optionsType)`	`new HudSession(client, options = {})`	Erzeugt ohne Netzwerkstart. C# benötigt Client und generierte Optionsmetadaten. JavaScript benötigt einen Client mit watchSessionGraphV3.
`—`	`createHudSession(client = new HudClient(), options = {})`	Fabrik für dieselbe Sitzung. Der Standardclient verwendet die aktuelle Paketadresse.
`Task StartAsync(CancellationToken cancellationToken = default)`	`start(): Promise<void>`	Startet einmal ohne Warten auf eine erreichbare Quelle. Wiederholungen öffnen keine weitere Verbindung. Token beziehungsweise Options-signal gilt für die ganze Lebensdauer.
`Task Completion`	`completion: Promise<void>`	Lebensdauer getrennt vom Start beobachten. C# vor Start bereits abgeschlossen; nach Start der laufende Task. JavaScript vor Start offen bis Laufende oder Abbau. Normale Abbrüche und behandelte Optionsfehler erscheinen im Zustand.
`ValueTask DisposeAsync()`	`dispose(): Promise<void>`	Bricht eigenen Stream ab, wartet auf dessen Ende und entfernt Abos. Mehrfacher Abbau zulässig. C#-Start nach Abbau wirft. JavaScript lehnt ersten Start nach vorherigem Abbau ab; nach schon erfolgtem Start gibt start() nur das bestehende Startversprechen zurück und startet nicht neu.
`HudIdentity Identity`	`HudClient.identity`	Paketkennung und Version. JavaScript liest sie am erzeugenden Client.

Die Sitzung besitzt keinen öffentlichen manuellen Reset. Bei Transport-/Protokollverlust werden erst alle Domänen ungültig, danach folgt bei Wiederverbindung eine neue vollständige Basis. Ein lokaler Optionsfehler beendet diese Instanz dauerhaft; nach Korrektur neue Instanz erzeugen oder Dokument neu laden. Starte daneben keinen Panelstream und keine Optionsabfrageschleife.

Aktuellen Zustand und Bereitschaft lesen

C# / Blazor	JavaScript	Vertrag
`HudSessionSnapshot<TOptions> Current`	`current: HudSessionSnapshot<TOptions>`	Atomar veröffentlichter Zustand. Nicht verändern; eigene C#-Optionsobjekte ebenfalls unveränderlich behandeln.
`bool Ready; HudConnectionStatus Connection`	`ready: boolean; connection: HudConnectionStatus`	Ready erst nach validierter Basis aller vier Domänen. Socketstatus Connected/connected genügt nicht. C#: Connecting, Connected, Reconnecting, Stopped; JS: connecting, connected, reconnecting, stopped.
`HudV3Graph? Game; HudPanelView? Panel; HudViewStateV3? View; TOptions? Options`	`game; panel; view; options`	Vor Basis/nach Reset nicht verfügbar. C#-Options ist default(TOptions), JS null. Referenz-/Recordtyp für Optionen verwenden und Ready prüfen. Ein bereiter Graph kann bei fehlenden Spieldaten trotzdem Info=null haben.
`HudSessionFault? Error; long Sequence`	`error: HudSessionError \| null; sequence: number`	Letzter Fehler und lokale Veröffentlichungsfolge, keine Server-/Game-Revision. Ein erfolgreich akzeptiertes Update löscht den Fehler. Statuswechsel können ihn bis dahin weitertragen.
`LiveSnapshot? Snapshot`	`snapshot: DeepReadonly<LiveSnapshot> \| null`	Lazy Gesamtprojektion in die ältere Snapshotform. Für neue Anzeigen direkt Graphteile auswählen. Gespeicherte Graphen liefern weiter ihren historischen Zustand.

Reset der Sitzung lädt das Browserdokument nicht selbst neu. Sitzungsbereitschaft, Serveruhrbereitschaft und Quellenfrische sind getrennt. 0 ist ein echter Wert, null unbekannt und eine leere Liste explizit leer.

Abonnements und Ereignisse

C# / Blazor	JavaScript	Vertrag
`IDisposable Observe<T>(Func<HudSessionSnapshot<TOptions>,T> selector, Action<T> callback, IEqualityComparer<T>? comparer = null, bool emitCurrent = true)`	`observe(selector, listener, { equals = Object.is, emitCurrent = true } = {}): Unsubscribe`	Ermittelt aktuelle Auswahl sofort, liefert sie standardmäßig sofort, danach nur bei Änderung. C# vergleicht mit EqualityComparer<T>.Default. JS-Listener erhält (value,state). Ohne Erstbenachrichtigung wird der Vergleichswert trotzdem gesetzt.
`event Action<HudSessionSnapshot<TOptions>> StateChanged`	`onState(listener, { emitCurrent = false } = {}): Unsubscribe`	Alle neuen Veröffentlichungen. C#-Event ohne initialen Replay. JS optional mit aktuellem Zustand.
`event Action<HudPanelAction> PanelAction`	`onAction(listener): Unsubscribe`	Akzeptierte Liveaktion nach Zustandscommit. Kein Replay bei Registrierung, Basis oder Wiederverbindung. Id, Section, Name, Value aus dem Vertragsobjekt verwenden.
`event Action<HudSessionFault> ErrorOccurred`	`onError(listener): Unsubscribe`	Sitzungsfehler; JavaScript meldet hier zusätzlich isolierte Abonnentenfehler. Kein initialer Replay.
`event Action<Exception> SubscriberFailed`	`onError(listener): Unsubscribe`	Selektor-/Vergleichs-/Callbackfehler beenden andere Abos und die Sitzung nicht. Fehler eines Fehlerlisteners werden isoliert. JavaScript verwendet kind=subscriber.

C#-Handles mit Dispose(), eigene Eventhandler mit -= entfernen. JavaScript gibt eine Abmeldefunktion Unsubscribe = () => void zurück. Diese entfernt nur ihr Abo. Die Sitzung beim eigenen Abbau vollständig beenden; keine neuen Abos nach Dispose registrieren. Callbacks sind synchron und sollen den Feed nicht blockieren. Eigene Blazor-Komponenten wechseln über InvokeAsync zum Renderer; SouHudRegion übernimmt dies.

Wähle Skalare, unveränderliche Records oder beibehaltene Graphteile. Ein neues JavaScript-Objekt bei jedem Selektoraufruf ist unter Object.is immer verändert. Ein eigener Vergleich muss alle dargestellten Felder berücksichtigen. Abonnements öffnen keine zusätzliche Verbindung oder Uhr.

Optionen vor dem Commit prüfen

C# / Blazor	JavaScript	Vertrag
`JsonTypeInfo<TOptions> optionsType`	`parseOptions(value) => TOptions`	C# deserialisiert über Metadaten; Options-JSON muss ein Objekt und Ergebnis nicht null sein. Gleiches rohes JSON wird innerhalb einer Verbindung nicht erneut deserialisiert. JS übernimmt ohne Parser das Objekt. Parser synchron, kein Array oder Promise.
`—`	`validateOptions(value): boolean \| void`	Optional; false oder Wurf bedeutet Fehler. Kein Promise.
`—`	`optionsEqual(previous,next): boolean`	Optional; true behält vorherige unveränderliche Referenz. Kein asynchroner Vergleich.
`StartAsync(cancellationToken)`	`options.signal?: AbortSignal`	Abbruch für die Lebensdauer. Bereits abgebrochenes Signal startet keinen laufenden Stream.
`SouHudSettings.Diagnostics: bool? = null`	`options.diagnostics?: boolean`	Explizit an/aus. Nicht gesetzt folgt ?diagnostics=1 in Dokument- beziehungsweise JS-Clientadresse.

Optionsvorbereitung läuft vor dem atomaren Commit; ein Fehler veröffentlicht keine Teilbasis. JS kopiert eigene Optionsobjekte als unveränderliches JSON: endliche Zahlen, keine Zyklen/Funktionen/undefined/beliebigen Klasseninstanzen; maximale Verschachtelung 64. C# verwendet deine Metadaten/Konverter: unveränderliche Anwendungstypen und eigene fachliche Prüfung vorsehen.

C#-Beispiel mit vollständigem Lebenszyklus

Vollständige Datei für ein .NET-10-Projekt mit SDK-Paket. Aufrufer hält HttpClient am Leben, liefert eine Host-Paketadresse und bricht über das Token ab. In Blazor stattdessen die gemeinsame DI-Sitzung verwenden.

using System.Text.Json.Serialization;
using SOU.Hud.Sdk;

public sealed record ReferenceOptions(string Caption = "My HUD");

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(ReferenceOptions))]
internal partial class ReferenceJson : JsonSerializerContext;

public static class SessionReference
{
    public static async Task RunAsync(HttpClient http, Uri packageAddress, CancellationToken stop)
    {
        await using var session = new HudSession<ReferenceOptions>(
            new HudClient(http, packageAddress), ReferenceJson.Default.ReferenceOptions);
        using var map = session.Observe(
            state => state.Game?.Info?.Map,
            value => Console.WriteLine(value ?? "Waiting for game data"));
        await session.StartAsync(stop);
        await session.Completion;
    }
}

Vollständiges JavaScript-Modul mit Abbau

Das Modul liegt neben dem aus der Vorlage erzeugten Verzeichnis sdk. Aufrufer verwendet runHud(signal) und ruft beim Abbau die zurückgegebene dispose()-Methode auf. Für sichtbare Ausgabe Konsolenausgabe durch textContent an deinem eigenen Element ersetzen.

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

export function runHud(signal) {
    const session = createHudSession(new HudClient(), {
        signal,
        parseOptions(raw) {
            const caption = raw.caption ?? 'My HUD';
            if (typeof caption !== 'string') throw new TypeError('caption must be a string');
            return { caption };
        },
        validateOptions: value => value.caption.length <= 100,
        optionsEqual: (previous, next) => previous.caption === next.caption
    });
    const unsubscribe = session.observe(
        state => state.game?.info?.map ?? 'Waiting for game data',
        value => console.log(value)
    );
    const removeError = session.onError(error => console.error(error.kind, error.message));
    void session.start();
    return {
        session,
        async dispose() {
            unsubscribe();
            removeError();
            await session.dispose();
        }
    };
}

Panelwerte sicher lesen

C# / Blazor	JavaScript	Vertrag
`HudPanelView.Revision; Values; References`	`HudPanelView.revision; values; references`	Unveränderliche gruppierte Wörterbücher. Values enthält C#-JsonElement beziehungsweise JavaScript-JSON-Werte.
`JsonElement? Get(string section, string field)`	`get(section,name): unknown`	Fehlendes Feld ergibt null. JS gibt auch gespeichertes JSON-null als null zurück.
`string? Text(string section, string field, string? fallback = null)`	`text(section,name,fallback = null): string \| null`	Nur Stringwerte. Fehlend/falscher Typ ergibt Fallback; bewusst leerer String bleibt leer.
`bool Flag(string section, string field, bool fallback = false)`	`flag(section,name,fallback = false): boolean`	Nur boolesche Werte; keine Umwandlung von Strings/Zahlen.
`HudPanelReference? Reference(string section, string field)`	`reference(section,name): HudPanelReference \| null`	Aufgelöste Referenz oder null; keine Identität aus Beschriftungen erraten.
`HudPanelState ToState()`	`toState(): HudPanelState`	Defensive Kopie in veränderliche DTO-Form; Änderungen wirken nicht auf Sitzung/Panel.
`—`	`new HudPanelView(state)`	Für eigene Adapter; kopiert und friert JSON ein. C#-Views kommen aus der Sitzung.

Unveränderlichen Spielgraph auswählen

C# / Blazor	JavaScript	Vertrag
`HudV3Graph.SessionId; SchemaVersion; Revision; ReceivedAt; Freshness`	`sessionId; revision; receivedAt; freshness`	Graphmetadaten. C# SchemaVersion ist 3. Quellenzeit erhalten und Frische nicht aus Socketstatus ableiten.
`Info; Clock; Roster; Radar; GrenadeOrder; KillOrder`	`info; clock; roster; radar; grenadeOrder; killOrder`	Typisierte Singletonobjekte oder null. Roster.Players/roster.players und Order-Keys bestimmen Reihenfolge. Die Graph-Clock ist fachlicher Zustand, keine laufende Serveruhr.
`ManagedMatch; GameMatch`	`managedMatch; gameManagedMatch`	Vorbereitetes Match auf Snapshotebene beziehungsweise Match im Spielobjekt. Quellen nicht gleichsetzen.
`ImmutableDictionary<string,HudPlayerPartsV3> Players`	`players: ReadonlyMap<string,HudPlayerPartsV3>`	Opake Schlüssel. Parts: Key, Identity, Vitals, Equipment, Weapons, Statistics, Pose; JS camelCase. Unveränderte Teile behalten Referenzen.
`HudPlayerPartsV3? Player(string key)`	`player(key): HudPlayerPartsV3 \| null`	Unbekannter Schlüssel liefert null.
`ObservedPlayer; CurrentPlayer`	`roster.observed; roster.current; player(key)`	C# löst bestätigte Rollen auf. JS löst denselben Roster-Key mit player auf. Rollen nicht allein nach Steam-ID bestimmen.
`IEnumerable<HudPlayerPartsV3> FindPlayersBySteamId(string steamId)`	`findPlayerBySteamId(steamId): HudPlayerPartsV3 \| null`	C# liefert alle Treffer: dieselbe Steam-ID kann in mehreren Quellblöcken vorkommen. JS liefert ersten Treffer/null; für mehrere players.values() selbst filtern.
`RadarPlayer? GetRadarPlayer(string key); GrenadeState? GetGrenade(string key); KillFeedEntry? GetKill(string key)`	`getRadarPlayer(key); getGrenade(key); getKill(key)`	Typisierte Lookupwerte/null; Reihenfolge aus Radar-/Orderobjekt übernehmen.
`IReadOnlyDictionary<(HudObjectKindV3 Kind,string Key),HudObjectV3> Objects; GetObject(kind,key = "main")`	`objects: ReadonlyArray<HudObjectV3>; getObject(kind,key)`	Rohobjektzugriff ohne Gesamtprojektion. Unbekannt: C# null, JS undefined. JS verlangt expliziten Key.
`IsCompatibilitySnapshotCreated; LiveSnapshot ToSnapshot()`	`snapshotMaterialized; toSnapshot()`	Erkennt/erzeugt lazy Gesamtprojektion. Gespeicherter Graph erhält seinen historischen Zustand, auch nach späteren Updates.

Blazor: Dienste, Host und Regionen

Einmal SouHudServices.AddSouHud<TOptions>(IServiceCollection services, JsonTypeInfo<TOptions> optionsType, Action<SouHudSettings>? configure = null) als Erweiterungsmethode aufrufen; Rückgabe dieselbe IServiceCollection. Beispiel: builder.Services.AddSouHud<ReferenceOptions>(ReferenceJson.Default.ReferenceOptions) mit den Typen oben. Scoped registriert: HudClient, HudSession<TOptions>, HudClock, HudRenderClock, HudPerformanceMetrics, HudBrowserRuntime<TOptions>. SouHudSettings ist singleton. Vorhandener HttpClient bleibt erhalten; sonst scoped mit Browserbasisadresse.

C# / Blazor	JavaScript	Vertrag
`SouHudSettings.Diagnostics: bool? = null`	`—`	Zum Beispiel settings => settings.Diagnostics = false. Null folgt diagnostics=1 in der Dokument-URL.
`SouHudHost<TOptions>: ChildContent; DisposeAsync()`	`—`	Ein Host an der Wurzel. Cascading Values: Session, Clock, Metrics. Start nach erstem Render. ChildContent erst bei bereiter Serveruhr; Session-Ready separat beachten. Optionsfehler als Alert. Dispose beendet eigene Sitzung/Browserlaufzeit.
`SouHudRegion<TOptions,TValue>: Select; Comparer = null; ChildContent; Session; Dispose()`	`—`	Select erforderlich; optionaler Comparer. ChildContent erhält Auswahl. Session kommt vom Host. Parameteränderung erneuert Abo, Dispose entfernt es. Nur geänderte Auswahl fordert Render.
`HudRenderBoundary: RenderKey = null; Now; ClockMilliseconds = 0; ChildContent; Clock; Metrics; Dispose()`	`—`	Unveränderlicher RenderKey bestimmt Datenrender. Now ist expliziter Anker, initial default. 0 deaktiviert Uhrabo; positives Intervall mindestens 16 ms. ChildContent erhält DateTimeOffset. Clock/Metrics sind optionale Cascading Values. Zeitänderung allein fordert ohne Uhrabo/Key keinen Render.

Vollständige Razor-Komponente mit ReferenceOptions aus dem C#-Beispiel. Die oben genannte Registrierung gehört in den WebAssembly-Start. Kein globaler Elterntimer erforderlich.

@using SOU.Hud.Sdk.Blazor

<SouHudHost TOptions="ReferenceOptions">
    <SouHudRegion TOptions="ReferenceOptions" TValue="string"
                  Select='@(state => state.Game?.Info?.Map ?? "Waiting for game data")'
                  Context="map">
        <p>@map</p>
    </SouHudRegion>
</SouHudHost>

Serveruhr und Countdown

C# / Blazor	JavaScript	Vertrag
`HudRenderClock.IsReady; DateTimeOffset Now`	`hudClock.isReady(): boolean; hudClock.now(): number`	Bereitschaft vor Zeitlesen prüfen, sonst Wurf. C# Server-UTC, JS Unix-Millisekunden.
`IDisposable HudRenderClock.Subscribe(int milliseconds, Action<DateTimeOffset> callback, DateTimeOffset? anchor = null)`	`hudClock.subscribe(listener): Unsubscribe`	C#: mindestens 16 ms, kein sofortiger Tick. Ein gemeinsamer Timer nur bei Abos; Anchor letzter Tick, sonst bereite Uhr/kein Anker. JS nur Zustandsereignisse {ready,reason}, kein periodischer Timer und kein initialer Replay.
`event Action<DateTimeOffset> HudRenderClock.Tick; event Action<Exception> SubscriberFailed`	`—`	Tick folgt beim Advance den Abonnenten; Event allein startet keinen Timer. Fehler werden je Callback isoliert.
`void HudRenderClock.Advance(DateTimeOffset now); ValueTask DisposeAsync()`	`—`	Advance nutzt übergebene Zeit für eigene deterministische Integration/Tests. Normalerweise Host versorgen lassen. Dispose entfernt Timer/Abos.
`double? HudCountdown.Remaining(double? seconds, DateTimeOffset? receivedAt, DateTimeOffset now, bool paused = false)`	`countdownRemaining(seconds,receivedAt,now,paused = false): number \| null`	Sekunden; Ergebnis mindestens 0. Ungültige/fehlende Dauer null. Pause behält Dauer auch ohne Quellenanker. Sonst Anker erforderlich; negative verstrichene Zeit auf 0 begrenzt. JS receivedAt: ISO-String, Unix-ms oder Date; now: Unix-ms oder Date.

Uhrzustandsänderung ist kein Animationsintervall. JavaScript wählt Darstellungstakt für die betroffenen Elemente und beendet den Timer beim Abbau. Weder Date ersetzen noch Quellenzeitpunkte neu stempeln. hudClock nutzt die synchronisierte Hostuhr ohne Anfrage oder eigenen Timer.

C#-Uhr für eigene Hostintegrationen

Normale Blazor-HUDs verwenden die registrierte Uhr. Die folgenden öffentlichen Methoden von SOU.Live.Contracts.HudClock unterstützen eigene Hostadapter; keine zusätzlichen Uhrabfragen neben dem Host starten.

C# / Blazor	JavaScript	Vertrag
`new HudClock(TimeProvider? timeProvider = null); IsSynchronized; UtcNow`	`—`	Standard TimeProvider.System. Serveranker wird mit monoton verstrichener Zeit fortgeschrieben; UtcNow wirft ohne gültigen Anker.
`MaximumRoundTrip = 2 seconds; MaximumSampleAge = 90 seconds; TryGetUtcNow(out DateTimeOffset now)`	`—`	Zu langsame Samples verwerfen, zu alte Anker ungültig. Try-Variante liefert false, statt Zeit zu erfinden.
`long GetTimestamp(); TimeSpan GetElapsedTime(long startingTimestamp); HudClockRequest BeginSynchronization()`	`—`	Monotone Zeitmarken und geordnete Anfrage mit Timestamp, Generation, Sequence.
`bool TrySynchronize(HudClockSample sample, long requestTimestamp, long responseTimestamp); bool TrySynchronize(HudClockSample sample, HudClockRequest request, long responseTimestamp)`	`—`	HudClockSample enthält ServerTime. Halbe Roundtripzeit schätzt Rückweg. Abgewiesene Samples ersetzen keinen gültigen Anker. Request-Variante schützt auch vor überholter Generation/Reihenfolge.
`void Invalidate(); Task<bool> HudClockSynchronizer.SynchronizeAsync(HudClock clock, HttpClient http, Uri clockAddress, CancellationToken token = default)`	`—`	Invalidate entwertet Anker. HTTP-Helfer serialisiert je Uhr, nutzt Cookiekontext/no-cache/no-store und 3s Timeout. Transportfehler werfen; abgewiesenes Sample liefert false.

Fehlerarten und Wiederverbindung

C# / Blazor	JavaScript	Vertrag
`HudSessionFault(HudSessionFaultKind Kind, Exception Exception); Message`	`HudSessionError(kind,message,cause?); kind; cause; message`	C#: Transport, Protocol, Options. JS: transport, protocol, options, subscriber. C# Message ist Exception.Message; JS erhält Ursache in cause.
`Transport / Protocol`	`transport / protocol`	Domänenreset und Wiederverbindung mit neuer Basis. Kein stiller v2-Fallback. Gemeinsame Sitzung verwendet direkt WebSockets ohne Negotiation/Pollingfallback. Wartezeiten 1, 2, 5, maximal 10 Sekunden.
`Options`	`options`	Terminaler lokaler Typ-/Parser-/Validierungsfehler. Korrigieren und neue Instanz erzeugen.
`SubscriberFailed`	`subscriber`	Selektor/Callback/optionale Diagnose fehlgeschlagen; andere Empfänger bleiben aktiv. JS-onError bedeutet nicht automatisch current.error oder gestoppte Sitzung.

Optionale lokale Diagnose

Diagnose ist standardmäßig aus. ?diagnostics=1 oder explizite Einstellungen aktivieren sie; false schaltet trotz URL ab. Keine zusätzliche Liveverbindung und keine Telemetrie. Messung nur sichtbar; versteckte Intervalle und Übergänge über Sichtbarkeitswechsel/Reset werden ausgeschlossen. rAF-Abstände sind keine GPU-Frames, DOM-Wartezeit keine isolierte CPU-Zeit. Long Tasks nur bei Browserunterstützung.

C# / Blazor	JavaScript	Vertrag
`HudClient.ProcessingMeasured; HudSession<TOptions>.ProcessingMeasured: Action<HudProcessingMeasurement>?`	`—`	Standard null. Synchrones v3-Messcallback; Fehler unterbrechen Verarbeitung nicht. HudProcessingStage: Deserialize/Reducer. Recordfelder Stage,Milliseconds,Kind,SessionId,RoundNumber,Phase. Ohne Transportwartezeit/vorangehendes SignalR-Binding/Rendering.
`HudPerformanceMetrics.Enabled`	`session.diagnostics.enabled; ready: Promise<void>`	Blazor zusätzlich WASM-/DOM-Stufen. JS-ready wartet auf optionales Modul, nicht Spielbereitschaft. Vor Start bereits erfüllt; Aktivierung erst nach session.start().
`HudPerformanceSnapshot Snapshot(); void Reset()`	`session.diagnostics.read(): HudBrowserDiagnosticReport \| null; reset(): void`	JS read liefert null, solange deaktiviert/nicht bereit. Reset leert aktuelle begrenzte Messung. Blazor-Host stellt lokale Anzeige und JSON-Export bereit.
`new HudPerformanceMetrics(bool enabled, Func<double>? elapsedMilliseconds = null)`	`—`	Eigener Aggregator in SOU.Hud.Sdk.Diagnostics; Standard Stopwatch. MaxSegments=32, MaxSeconds=120. Deaktiviert keine Messsammlung.
`long Start(); void Record(string stage,long started); void RecordElapsed(string stage,double milliseconds)`	`—`	Start=0 wenn aus/unsichtbar. Record mit Start koppeln. RecordElapsed nur endlich/nichtnegativ/bekannte Stufe. Stufen: deserialize,reducer,presentation,app-render-queue,boundary-render-queue,clock-render-queue.
`SetVisibility(bool isVisible); SetContext(Guid sessionId,int? roundNumber,string? countdownPhase); ContextSnapshot(); event Action ContextChanged`	`—`	Für eigene Adapter Sichtbarkeit und bestätigten Kontext setzen. Standardhost übernimmt dies. ContextChanged bei Kontextwechsel/Reset.
`HudPerformanceDiagnostics: Metrics; Task ResetMeasurements(); Task SetMeasurementVisibility(bool visible); ValueTask DisposeAsync()`	`—`	Metrics-Parameter erforderlich. Host fügt Anzeige nur bei Diagnose hinzu. Öffentliche Tasks sind Browsercallbacks, keine eigene Datenschnittstelle. Abbau entfernt Modul und Veröffentlichungen.

C#-Diagnosedatentypen: HudPerformanceSnapshot mit Schema,Enabled,Visible,VisibleMs,ResetOrdinal,ElapsedMs,SessionOrdinal,Segment,Round,Phase,TimingSemantics,QuantileSemantics,HistogramBoundsMs,Stages,Segments,Seconds. HudPerformanceStage: Stage,Count,MeanMs,P50Ms,P95Ms,P99Ms,MaxMs,Over33Ms,Over50Ms,Over100Ms,Buckets. HudPerformanceSegment: Segment,SessionOrdinal,Round,Phase,StartMs,Stages. HudPerformanceSecond: StartMs,SessionOrdinal,Segment,Round,Phase,Stages. HudPerformanceSecondStage: Stage,Count,TotalMs,MaxMs. HudPerformanceContext: ResetOrdinal,SessionOrdinal,Segment,Round,Phase,Visible. Quantile sind Histogramm-Obergrenzen. HudPerformanceJson liefert generierte Metadaten für Snapshot/Context.

JavaScript-HudBrowserDiagnosticReport: schema,runtime,sampledAtPerformanceMs,semantics,browser. Browserteil: elapsedMs,visibleMs,visible,visibilityChanges,rafSupported,longTaskSupported,context,frames,longTasks,histogramBoundsMs,segments,seconds. HudTimingSummary: count,meanMs,maxMs,p50Ms,p95Ms,p99Ms,over33Ms,over50Ms,over100Ms,optional buckets. HudBrowserDiagnosticContext: sessionOrdinal,segment,round,phase. JS misst weder SignalR-JSON-Parser noch WASM/DOM-Abschluss. Deaktiviert/nicht unterstützt ist kein Nachweis von null Last.

Optionale Adapter für bestehende Darstellungsmodelle

Neue Anzeigen wählen v3-Graphteile direkt. Bestehende GameState-Komponenten können die öffentlichen C#-Adapter in SOU.Hud.Sdk.Presentation beziehungsweise Blazor verwenden. Sie verändern nie den autoritativen Graphen.

C# / Blazor	JavaScript	Vertrag
`HudProjectionOptions: IncludeRadar, IncludeGrenades, IncludePlayerPose, IncludeBombPosition, IncludeProviderTimestamp, IncludeSourceBlocks`	`—`	Alle init-Optionen standardmäßig true. Default erhält alle Felder; WithoutMotion setzt alle sechs false und entfernt deren Darstellungsanteile.
`new HudGameProjection(HudProjectionOptions? options = null); GameState? ForDisplay(GameState? incoming); ManagedMatch? Match(ManagedMatch? incoming); void Reset()`	`—`	Eigene Projektion je Verbraucher mit strukturellem Cache. Null bleibt null; äquivalente Felder können frühere Referenzen behalten. Eingaben unveränderlich. Reset löscht nur Cache.
`new HudUpdateState(HudGameProjection projection); bool Accept(LiveSnapshot next); Snapshot; DisplayGame; Match`	`—`	Aktualisiert Gesamtzustand/Projektion und meldet materielle Darstellungs-/Metadatenänderung. Kein Timer oder Netz.
`SouHudSnapshotView<TOptions>: Projection = new(); CoalesceMilliseconds = 0; ChildContent; Session; Clock; Metrics; DisposeAsync()`	`—`	Unter Host. Fenster 0..100 ms; 0 ohne Verzögerung. Nur äquivalente Präsentationsanforderungen zusammenfassen; materielle Daten-/Panel-/Options-/Resetwechsel unmittelbar. Abbau entfernt Eventabo/geplanten Render.
`HudSnapshotPresentation<TOptions>(LiveSnapshot? Snapshot,GameState? DisplayGame,ManagedMatch? Match,TOptions? Options,HudPanelState? Panel,DateTimeOffset Now)`	`—`	ChildContent-Wert; Panel dort defensive HudPanelState-Kopie statt HudPanelView.

Öffentliche Browserlaufzeit für eigene Blazor-Hosts

HudBrowserRuntime<TOptions>(session, js, clock, renderClock, metrics) koordiniert Hostbrücke. bool ClockReady, string? Error, event Action? Changed melden Zustand. Task StartAsync() initialisiert idempotent; ValueTask DisposeAsync() beendet Sitzung, Renderuhr, Uhraktualisierung und Browserreferenzen. Task ClockChanged(BrowserSample sample) ist Browsercallback; BrowserSample(int Handle, bool Ready, double UnixMilliseconds) sein Datentyp. Normale HUDs rufen dies nicht zusätzlich auf: SouHudHost besitzt die Laufzeit.

Manageransicht kommt als View über dieselbe Sitzung. Blazor-Laufzeit und JS-watchSessionGraphV3 wenden sie über die Hostbrücke an. Keine zweite Verbindung. souHudManager.applyView(view) ist für eigene Adapter verfügbar. HudViewStateV3: InstanceId,Revision,Route; Revision 0 bedeutet keine ausdrückliche Auswahl. Ansichten müssen im Paket deklariert sein.

Lowlevel-Client für eigene Integrationen

Diese Methoden bleiben öffentlich, werden aber von der Highlevel-Sitzung übernommen. Nur für eigene Integrationen mit eigener Zustands-/Abbaulogik verwenden und nie parallel zur entsprechenden HudSession. Jede Enumeration/jeder Watch-Aufruf besitzt einen eigenen Stream. Paketadresse aus Host oder lokaler SDK-Vorschau verwenden.

C# / Blazor	JavaScript	Vertrag
`new HudClient(HttpClient http, Uri packageAddress); Identity`	`new HudClient(address = location.href); identity`	Adresse enthält /hud-packages/{id}/{version}/. C# HudIdentity(string Id,string Version), FromUri(Uri address) lesen Identität. JS identity eingefroren; address ist Client-URL. HttpClient am Leben halten.
`Uri Media(string relative)`	`media(path): string`	Nur lokale /cast-media/-Pfade mit einem Dateisegment. Keine .., Backslashes, Query, Fragment, Prozentkodierung. Rückgabe gleiche Herkunft wie Paket.
`IAsyncEnumerable<HudSessionUpdateV3> WatchSessionV3Async(CancellationToken token = default)`	`watchSessionV3(receive,options = {}): HudWatchCancellation`	Gemeinsamer v3-Stream für Spiel, Panel, Ansicht, Optionen. C# ohne eigenen Optionsparser in diesem Overload und mit materialisierter Gesamtprojektion. JS-Snapshot bleibt lazy.
`—`	`watchSessionGraphV3(receive,{ signal,status,error,prepareOptions } = {}): HudWatchCancellation`	Gleicher JS-Stream mit optionaler synchroner Optionsvorbereitung vor Commit. Highlevel-Sitzung verwendet dies. C#-Graphwatch nicht öffentlich.
`IAsyncEnumerable<HudV3Update> WatchV3Async(CancellationToken token = default)`	`watchV3(receive,options = {}): HudWatchCancellation`	Nur v3-Spieldaten mit eigener Basis/Deltafolge. Keine gemeinsame Panel-/Options-/Managerlaufzeit.
`event Action<string,HudConnectionStatus> ConnectionChanged; event Action<string,Exception> ConnectionFailed`	`WatchOptions.status(channel,status); WatchOptions.error(error)`	Kanäle live,panel,session. JS-Standardstatus leerer Callback; Standardfehler console.error. Eigene C#-Client-Eventhandler dürfen nicht werfen.
`CancellationToken / await foreach`	`HudWatchCancellation(): void; completion: Promise<void>`	JS liefert Abbruchfunktion mit completion. Abbrechen, danach completion abwarten. WatchOptions.signal beendet denselben Stream. C# nutzt await-foreach mit Token.
`WatchAsync(token = default); WatchPanelAsync(token = default)`	`watch(receive,options = {}); watchPanel(receive,options = {})`	Vorhandene getrennte ältere Live-/Panelmethoden bleiben kompatibel. Nicht für neue v3-HUDs oder neben der gemeinsamen Sitzung. C#-Rückgaben IAsyncEnumerable<LiveSnapshot> beziehungsweise IAsyncEnumerable<HudPanelMessage>; JS Watch-Abbruchhandle.

HudClient.stream(channel,path,args,receive,options,decode,reset,method) ist ein JavaScript-Implementierungshelfer, keine in der öffentlichen TypeScript-Deklaration angebotene Einstiegsmethode. Typisierte Watchmethoden verwenden, damit deren Protokoll-/Validierungsauswahl greift. HudSdkJson stellt generierte C#-Metadaten für LiveSnapshot, HudMessageV3, HudSessionMessageV3, JsonElement, HudPanelMessage und String bereit. Eigene Optionen benötigen weiterhin deinen generierten Kontext.

Lowlevel-Updates und Reducer

C# / Blazor	JavaScript	Vertrag
`HudV3Update(Message,Snapshot); IsSnapshot; Objects; Changed(HudObjectKindV3 kind,string? key = null)`	`HudV3Update: message; snapshot; isSnapshot; objects; changed(kind,key = null)`	Akzeptiertes Gamebatch mit Gesamtprojektion. Changed prüft Objektliste dieser Nachricht; ohne Key genügt die Art.
`HudSessionUpdateV3(Message,Snapshot,Panel,View,Options); IsSnapshot; GameUpdated; PanelUpdated; ViewUpdated; OptionsUpdated; GameUpdate; PanelMessage`	`HudSessionUpdateV3: message; game; snapshot; panel; view; options; preparedOptions; isSnapshot; gameUpdated; panelUpdated; viewUpdated; optionsUpdated; gameUpdate; panelMessage`	Basis markiert alle Domänen aktualisiert, danach nur Nachrichtendomäne. PanelUpdated kann Aktion ohne neuen Panelzustand bedeuten. GameUpdate/PanelMessage können fehlen. JS-preparedOptions ist Vorbereitungsergebnis, options rohes eingefrorenes JSON.
`new HudV3State(); Objects; Reset(); LiveSnapshot ToSnapshot(); HudV3Graph ToGraph(); LiveSnapshot Apply(HudMessageV3 message); HudV3Graph ApplyGraph(HudMessageV3 message)`	`new HudV3State(); objects; message; graph; getObject(kind,key); reset(); toSnapshot(); apply(message); applyGraph(message)`	Eigener Reducer je Stream. Vollständige Batch-/Graphprüfung vor Commit. Ohne Basis wirft Gesamtprojektion; JS graph/message vorher null. Reset verwirft Basis. C#-Lookup über Objects.
`new HudSessionStateV3(string id,string version); Message; Graph; Snapshot; Panel; View; Options; Reset(); Apply(message); Apply(message,Action<JsonElement>? prepareOptions)`	`new HudSessionStateV3(id,version); current; reset(); apply(message); applyGraph(message,prepareOptions = value => value)`	Paketgebundener atomarer Reducer. Fachliche Getter ohne Basis werfen, C# Message ist vorher null. Initial Revision 1 mit allen vier Domänen, danach exakt Basis/Revision+1 mit einer Domäne. Optionsvorbereitung vor Commit.
`HudV3SyncException(string message)`	`HudV3SyncError extends Error`	Ungültige Header, Revisionen, Ersatzobjekte/Referenzen werden abgewiesen. Nicht beliebige Deltas überspringen; neue Basis verlangen.

HudV3Protocol enthält SchemaVersion=3, HubPath=live/v3, BrowserHubPath=/hud-live/v3, SnapshotPath=state/v3, WatchMethod=Watch, SessionWatchMethod=WatchHud, MaximumSafeInteger=9007199254740991. Konstanten beschreiben den Vertrag; normale HUDs bauen keine Zusatzverbindungen daraus. HudSessionSnapshot ist Highlevel-Zustand, HudSessionUpdateV3 Lowlevel-Eintrag und HudSessionMessageV3 Drahtnachricht.

Öffentliche C#-Werkzeuge für Protokolladapter

Für eigene Adapter bietet SOU.Live.Contracts außerdem HudV3Projection.Project(LiveSnapshot snapshot) zur vollständigen Objektprojektion, HudV3Projection.KillKey(KillFeedEntry kill) zur kanonischen Killkennung, HudV3Diff.Create(LiveSnapshot? previous,LiveSnapshot next) zum Batchvergleich und HudV3Diff.Equal(HudObjectV3 a,HudObjectV3 b) zum Inhaltsvergleich. HudV3Encoder.Encode(LiveSnapshot snapshot) erzeugt auf einer seriell verwendeten Instanz je Empfänger Snapshot/Folgebatch; Reset() verwirft die Basis. Fehlgeschlagenes Encoding erhält die vorige Basis. Eine normale HUD-Anzeige benötigt diese Hilfen nicht zusätzlich.

JavaScript-Deklarationen: DeepReadonly<T> für transitive Lesbarkeit, Unsubscribe für Abmeldung, WatchOptions für signal/status/error, HudObserveOptions<T> für equals/emitCurrent, HudSessionOptions<TOptions> für Optionsvorbereitung/Abbruch/Diagnose, HudClockState für ready/reason und HudSessionDiagnostics für enabled/ready/read/reset. Drahtfelder und Enums stehen in der Typreferenz; die erste funktionierende Ausgabe erklärt der Entwicklungsleitfaden.