CS2DemoKit.Analysis 0.11.0

CS2DemoKit.Analysis

A rule-driven analysis engine for parsed CS2 demos: a state-graph evaluator that walks a ParsedDemo's frames once, four baseline rulesets embedded in the assembly, rich highlights with frame-clock timestamps, per-player stats, and a 3D line-of-sight engine for visibility-gated stats. Builds on CS2DemoKit.Parser — parse first, then hand the result here.

Quickstart

using CS2DemoKit.Analysis;
using CS2DemoKit.Analysis.Abstractions;
using CS2DemoKit.Analysis.Yaml;
using CS2DemoKit.Parser;

ParsedDemo demo = MemoryMappedDemoSource.ParseFile(path);

// The four baseline rulesets — KAST, per-player stats, weapon stats, post-plant multi-kills —
// embedded in this assembly, so there are no files to ship or locate alongside your app.
RuleConfigLoadResult loaded = YamlConfigLoader.LoadShippedEmbedded();
if (!loaded.Success)
{
    throw new RuleConfigException(loaded.Errors);
}

AnalysisRun run = DemoAnalysis.Run(demo, loaded.Rulesets);

foreach (HighlightFired hl in run.Highlights)
{
    // hl.Tick is frame clock — the same clock as GameEvent.GameTick and DemoFrame.ServerTick.
    // Never subtract ParsedDemo.ServerStartTick from it.
    PlayerInfo? player = demo.Players.GetValueOrDefault(hl.PlayerSlot);
    Console.WriteLine($"[{hl.RulesetId}.{hl.HighlightId}] tick {hl.Tick} {player?.SteamId64}: {hl.RenderedTitle}");
}

DemoAnalysis.Run builds the graph and evaluates it in one call; DemoAnalysis.Build + DemoAnalysis.Evaluate split the two steps for callers that need the compiled graph before the (multi-second) evaluation runs, e.g. to render a skeleton UI. AnalysisRun.Highlights is populated in both capture modes — including the cheaper bare scan (new AnalysisOptions { CaptureSnapshots = false }), which is the mode to reach for if you only need highlights, not per-frame snapshots.

To customize or fork the shipped rules, extract them to disk with YamlConfigLoader.ExtractShippedTo(dir), edit the copies, and load your directory back with YamlConfigLoader.TryLoadDirectory(dir) or layer it over the shipped tier with YamlConfigLoader.LoadWithOverlay(shippedDir, userDir).

Rules from a database or an upload

YamlConfigLoader.LoadDocuments(...) gives in-memory (label, yaml) documents identical semantics to a rules/ directory; LoadShippedWithOverlay(userDocs) layers them over the embedded shipped tier (same-id replaces wholesale, enabled: false drops after overlay). Validate uploads with no demo via DemoAnalysis.ValidateRulesets(...) — pass every document sharing the id namespace (shipped + user), or cross-ruleset use: references report false unknown-ruleset errors; the upload path is ValidateRulesets(LoadShippedWithOverlay(userDocs).Rulesets). At analysis time, BuildResult.RulesetDiagnostics and .ExcludedRulesets surface what composition dropped — check them, or a ruleset that stopped compiling is indistinguishable from feats that never fired.

Clip planning

CS2DemoKit.Analysis.Clips turns highlights into clip windows entirely in frame clock: ClipRounds.Derive(demo) (the frame-clock round authority), HighlightSurfacing.Surface (drops hidden firings, collapses group families to their top tier), ClipWindows (per-round window computation with reach-back + coalescing), and ClipPlanner.Plan(demo, ...) → a renderer-neutral ClipPlan. Any tick-space offset for a downstream renderer applies once, at emission — never inside the plan.

Version discipline

This family (CS2DemoKit.Parser, CS2DemoKit.Analysis, CS2DemoKit.Analysis.Rules) is lockstep exact-pinned pre-1.0: CS2DemoKit.Analysis depends on exact versions of the other two. Installing CS2DemoKit.Analysis alone is the known-good set — there is no metapackage.

Bump all CS2DemoKit.* package references together, in one commit. A direct reference to one family member at a version that conflicts with another member's transitive exact pin doesn't fail the build — NuGet's nearest-wins rule lets it through with only NU1608, a warning. Restore succeeds and the skew surfaces later as a runtime MissingMethodException, not a build error. Add this to your project so that class of skew fails the build instead:

<PropertyGroup>
  <WarningsAsErrors>$(WarningsAsErrors);NU1608;NU1605</WarningsAsErrors>
</PropertyGroup>

Parallelism

Set AnalysisOptions.MaxDegreeOfParallelism when evaluating several demos in one process — otherwise each demo's entity-decode precompute fans out to every core, and each worker holds a full EntityTracker. null/≤0 means unbounded (the default). Still gate the number of concurrent demos with your own SemaphoreSlim, sized with the parse-side memory multiplier in mind.

Pawn position

Rules read a pawn's world position as player.pos_x, player.pos_y, player.pos_z (floats). There is no m_vecOrigin leaf on a pawn: position is a cell index plus an in-cell offset on CBodyComponent, reconstructed as (cell - 32) * 512 + offset.

These three cost more than every other provider combined, and only when you read them. Providers are gated in by name, so a ruleset that reads no axis pays nothing. A ruleset that does read one defeats the digest's delta encoding for that column, because a moving player changes it every frame. Measured on a 123,283-frame demo, counting per-pawn cells the digest actually emits:

One axis is 26x, three are 100x. Read only the axes you need: that is where the split into three providers pays, since a height check gates in one column rather than three.

Three providers rather than one vector-valued provider is forced, not preferred. The rules type vocabulary is bool/int/float/string/duration/instant plus list and map of a scalar element, so there is no type a Vector3 could be declared as and no member access to read .z off one. Where that costs: a single vector column would emit 548,787 cells against the split's 1,442,280 on the same demo, because it boxes once per pawn-frame instead of about 2.7 times. A ruleset that genuinely reads all three axes is paying 2.6x for the language's scalar type system. Worth revisiting only if positional rules become common enough to justify a new type kind, which would reach the checker, the normalizer and canonical ruleset hashing.

Zones and bombsites

The library does not resolve map zones. Bombsite membership needs trigger volumes or baked zone geometry, neither of which is in a demo file. Register your own provider instead, and rules address it by name like any built-in:

public sealed class SiteProvider : IPerPlayerEntityValueProvider, IPawnStateReader
{
    public string Name => "entity.pawn.site";
    public Type ValueType => typeof(string);
    public string EntityClass => "CCSPlayerPawn";

    // The scanner validates this leaf against the demo's schema and THROWS if its wire type is
    // not compatible with ValueType, so it cannot be an arbitrary field: a string provider needs
    // a string-ish leaf. A computed provider declares whichever of its inputs matches.
    public string FieldName => SchemaNames.CCSPlayerPawn.LastPlaceName;

    public object? ReadForPawnState(EntityTracker tracker, EntityState pawn) =>
        PositionUtil.CellToWorld(pawn) is { } p ? MyZones.Resolve(p) : null;
    // ... CaptureAllSlots / Read / ReadForPawn as in PawnPositionProvider
}

var providers = PerPlayerEntityValueProviderRegistry.CreateDefault();
providers.Register(new SiteProvider());
var run = DemoAnalysis.Run(demo, rulesets, new AnalysisOptions { PerPlayerEntityProviders = providers });

A zone name is coarse and changes rarely, so it stays cheap in the digest in a way raw coordinates cannot. Prefer it over three axis reads plus arithmetic in the rule.

Implement IPawnStateReader when your provider needs the raw EntityState. The SDK wrapper's typed accessors resolve through the Lens lane only, and the CBodyComponent pair is not on it, so CSPlayerPawn.Origin returns null on the decode path this engine uses.

Line-of-sight / visibility

The LOS engine ships in this package under CS2DemoKit.Analysis.Visibility (VisibilityEngine, VisibilityAnalyzer, TriangleBvh) — VisibilityEngine.Load(trisPath) loads a per-map baked triangle mesh and answers ray/occlusion queries against it.

The baked collision geometry itself (collision.tris per map) does not ship in this package — it's Valve-derived geometry distributed out-of-band as its own asset bundle. The resolution convention now ships in the package: CollisionAssetLocator finds the blob via the CS2DEMOKIT_COLLISION_DIR environment variable (<map>.tris / <map>/collision.tris) with an assets/<map>/collision.tris walk-up fallback, null-on-miss; MapAssetBundleReader reads the bundle.json manifest beside it. Thread the manifest's identity into VisibilityAnalyzer.Options.Bundle and persist Report.Bundle with any stored result — bundles are selected by map name only, so bake identity is the only way to tell a stale bake from a current one after a CS2 map update. Analyze accepts a CancellationToken. For the analyzer's position resolver, pass CS2DemoKit.Parser.EntityTracking.PositionUtil.CellToWorld. Without a bundle for a given map, LOS-dependent stats are simply unavailable; the rest of analysis is unaffected.

On-disk rule locations

RuleSetLocator (used internally by the shipped-tier resolution helpers) resolves two directories for applications that deploy rules as files: a per-user overlay under the platform config root (~/Library/Application Support/<app> on macOS, %APPDATA%\<app> on Windows, $XDG_CONFIG_HOME/<app> on Linux), and AppContext.BaseDirectory/rules — with a directory walk-up fallback — for the shipped tier. Set RuleSetLocator.AppConfigDirName once at startup to your application's name so user rules land beside its other settings; it defaults to CS2DemoKit. Both locations are overridable with CS2DEMOKIT_RULES_DIR and CS2DEMOKIT_USER_RULES_DIR.

Server-side consumers that just want the embedded defaults should prefer YamlConfigLoader.LoadShippedEmbedded() over these directory probes — they exist for on-disk deployment models, not as the primary API.

Dependencies

CS2DemoKit.Parser and CS2DemoKit.Analysis.Rules (exact-pinned, see above), CS2OpenDev.Sdk (schema field-name constants), and YamlDotNet (the primary rule format — shipped and user rulesets are both YAML).

License

MIT. See THIRD-PARTY-NOTICES.md in the repo for third-party attributions carried by the family.