Data semantics and edge cases

This guide explains the meaning and limits of data in SDK 0.3.0-preview.2 with HUD API 3. It complements the HUD API guide, the SDK runtime reference and the complete type definitions. Examples use the actual public field names; they do not introduce additional message kinds.

Unknown, empty and null are different states

These rules apply at different levels: an omitted object replacement in objects leaves the existing object unchanged. A present replacement contains a complete typed object; its nullable fields are accepted rather than filled from previous field values. removed: true removes an object and carries no payload. A snapshot replaces the entire object baseline.

Which source supplies each domain?

availableSections lists present GSI sections. It is neither a permission list nor a promise that every field or player within those sections was supplied. Missing sections remain unknown. Details: GSI sections.

Identities, source roles and ordering

Player keys are opaque and scoped to a game session. Use Roster.Players / roster.players in the supplied order and resolve each key with Player(key) / player(key). Dictionary or Map iteration order is not roster order. Do not construct keys from Steam IDs, names or list positions. The same Steam ID may occur in several source roles.

Names are display text, not identity or HTML. Use Blazor text binding or textContent; do not decode HTML again or use innerHTML. Keep Steam IDs as strings so JavaScript cannot round them. The Roster reference and Identity describe the complete shape.

Reading the six player parts

Example: preserve 0 HP and leave unknown HP unavailable

This complete HudPlayerVitalsV3 object describes known 0 HP, a known absent helmet and an unknown smoke value. It does not itself create a kill event.

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

The following pure formatting functions take an already committed SDK session state. They display a known 0 and use a placeholder for missing state. C# uses the session's generic options type; JavaScript receives the same HudSessionSnapshot concept.

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);
}

Joining inventory definitions and weapon runtime

The definition tells you which weapon a slot contains; runtime tells you what it is doing. HudWeaponDefinitionV3 and HudWeaponRuntimeV3 share the same slot. Both lists are available together or both are null; the reducer checks equal length and matching slot order. Still join them by slot and do not assume fixed indices for primary weapon, pistol or knife.

These two matching JSON objects are complete HudPlayerEquipmentV3 and HudPlayerWeaponsV3 payloads. An ammunition change can replace only the second object.

{
  "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 }
  ]
}

For an active-weapon display, select a supplied active or reloading state. holstered is not an active weapon. When death is known, do not present old equipment as current possession. A known empty list clears the display; use bounded text or a neutral symbol for an unknown weapon name. kind is the known classification and name is the open source identifier; a name prefix is not proof of a particular weapon.

Map, round, sides and managed match

Additional fields: Game information, managed match and side resolution.

Labelling statistics and coverage correctly

Complete shapes: MatchStats and RecordedPlayerStats. Recording counts observed round results once; a rerender must not increment statistics.

Geometry, HLAE radar, grenades and kills

CS2 world coordinates require calibration for the particular map; they are not pixels. forward is a direction vector. Missing positions remain missing even when the display expects a marker. Radar uses the HLAE connection, epoch, sequence and receivedAt as its own source context. The temporary pawnHandle is neither a replacement for a Steam ID nor a persistent identity across respawns.

Use a fresh HLAE frame as the common marker source. Do not fill in a missing player with their older GSI pose. Only when the HLAE frame as a whole is unusable may the HUD fall back to available GSI poses. The current desktop removes radar frames aged at least 750 ms; this is not a general freshness guarantee of the WebSocket. Reset interpolation when the connection, epoch, map or game session changes.

Grenades supply optional position, velocity, lifetimeSeconds, effectTimeSeconds and flame points. The two named time values are seconds; do not construct an unsupported absolute deadline or playback speed from them. Vectors remain source geometry; do not claim SI units or a floor without documented calibration. Grenade kind and weapon kind are different enums.

A kill is identified by connectionId, epoch and id together. Its gameTimeSeconds belongs to the HLAE game timeline. The supplied set is bounded and refreshed on context changes; after reconnect it is not an archive of missed events. Rereading or rerendering the same entry does not create a new animation. Do not infer additional kills or suicide from health: 0, an unknown attacker or an unknown weapon identifier.

Radar references, Radar markers, Grenades and Kill feed list their individual fields.

Do not mix timestamps and units

Clock readiness, expiry and countdown

HudClockSample contains only the server-time sample. The host measures round-trip time; the C# clock core and browser integration reject samples with a round trip above two seconds. An accepted anchor advances monotonically and expires after more than 90 seconds without a valid renewal. Visibility changes, suspended browser documents and connection changes can also invalidate readiness. These are clock limits, not game-data freshness limits.

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

A failed renewal attempt does not replace an unexpired anchor. An old request or one completing after invalidation must not make a new generation ready. Use hudClock.isReady() before hudClock.now(); C# can check HudClock.TryGetUtcNow. Directly reading an unready strict clock throws. The Blazor host gates its content on clock readiness. The data session's ready property is independent.

Countdown helpers take the original source anchor. Without a valid seconds value the result remains unknown. Without receive time a running countdown remains unknown; an explicitly paused calculation instead holds the supplied seconds value. Negative results are clamped to zero, and a receive time in the future must not increase the source value. Do not infer a pause merely from an old or missing packet.

This JavaScript example runs inside an already initialized SDK HUD. It displays a placeholder when the session is unready, GSI data is not live or the clock is unready. countdownRemaining takes seconds and returns seconds, while hudClock.now() returns milliseconds. The clock's subscribe reports readiness changes and is not an animation cadence.

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));
}

Distinguishing session and game revisions

The outer session ID and inner game session ID are separate identities. A reconnect receives a new outer baseline; the inner game session may remain the same. A new map or another game context may change the game session. Revision values remain within the shared exactly comparable integer range up to 9007199254740991.

The following complete inner update requires an already accepted game baseline at revision 7 with a complete player under player-7. Jumping to revision 10 is valid with the matching base. It is not an outer HudSessionMessageV3 message.

{
  "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
    }
  }]
}

Atomic commits and invalid batches

A batch replaces or removes whole typed objects. A referenced player requires all six parts; roster, grenade, radar and kill references must match the final batch. New references and their objects may arrive in the same message. Their order within objects is not a sequence of visible intermediate states: the reducer validates the complete candidate before publication.

Duplicate object keys, mismatched payload kinds, missing reference targets, orphaned objects, inconsistent weapon lists, nonfinite numbers and a mismatched revision base can invalidate a batch. No valid subset is published. When the high-level SDK runtime reconnects after such a failure, it resets all four session domains and waits for a complete baseline. A custom adapter must not skip arbitrary deltas after a gap and continue calculating.

Committed graphs and JavaScript data are immutable; old states do not observe future reducer changes. Unchanged parts may retain the same reference. Treat C# options as your own immutable records. Keep UI state, animations and selection caches separate and reset them when the source or session changes.

Check readiness, connection and freshness separately

Typical configurable GSI host thresholds are 15 seconds to stale and 45 seconds to disconnected. Use the supplied freshness status; do not assume every host has the same configuration. HLAE, panel, view and options messages do not refresh GSI. A valid clock anchor likewise does not make an old round timer fresh.

Panel values, references and one-time actions

Panel state contains values and references, each keyed by section and field name. Text / text preserves an explicitly empty string; Flag / flag distinguishes actual booleans from other JSON types. A fallback is a local presentation decision, not a change to the received value. A reference with missing: true means the selected target is no longer available; do not show data from the previous target.

A HudPanelAction is an individual command with an ID, section, name and optional value, not a persistent checkbox field. Its handler runs after state commit. Actions are not part of the baseline and are not replayed on reconnect. An interruption can miss past actions; the session does not promise later delivery or a durable event history. Avoid replaying commands during rendering.

Panel state, Panel reference and Panel action describe the data; the SDK runtime reference explains subscriptions and error events.

Errors, reset, reconnect and disposal

StartAsync / start launches an instance once without waiting for an online server. Completion / completion tracks its lifetime. Transport and protocol errors wait 1, 2, 5 and then at most 10 seconds between attempts; an accepted baseline resets the retry progression. The SDK channel stays on v3 and does not silently fall back to v2 or periodic game-state requests.

A connection restart does not prove a new map, and a new game context does not replace resetting your own caches. A high render or subscription rate does not create additional source measurements. Use small selectors for data displays, a separate clock cadence for timers and explicit rules for map, session, epoch and freshness in animated transitions.