demolens

README

demolens

CS2 demo analyzer written in Go. Feed it a .dem file, get per-player and per-round stats back as JSON. Works as a CLI or as a library.

Features

• Core stats: kills, deaths, assists, K/D, ADR, KPR/DPR/APR, KAST, headshot %, accuracy, HLTV 1.0 and 2.0 ratings
• Aim stats: spotted accuracy, counter-strafe, spray accuracy, time-to-damage, crosshair placement
• Round detail: trades, opening duels, clutches, multi-kills, weapon breakdowns, duel and flash matrices
• Utility: flashes thrown and landed, blind durations, HE and molotov damage, unused utility on death
• Optional heavy output: per-frame positions, per-shot geometry, grenade trajectories

Install

go install github.com/f-gillmann/demolens/cmd/demolens@latest

Or build from a checkout:

go build -o demolens ./cmd/demolens

Usage

demolens analyze match.dem            # full stats as JSON on stdout
demolens analyze match.dem -o out/    # write out/<hash>.json instead
demolens check match.dem              # just the hash and header

A few of the aim stats need a line-of-sight test, so they only kick in when a map mesh is around. Grab the mesh for the map first, then point analyze at it:

demolens extract-map --cs2 "<CS2 install>" --map de_mirage
demolens analyze match.dem --maps-dir tris

Mesh setup lives in docs/maps.md.

Library

import "github.com/f-gillmann/demolens"

f, _ := os.Open("match.dem")
defer f.Close()

match, err := demolens.Analyze(f, demolens.Options{MapsDir: "tris"})

Options toggles the heavy output and holds the calibration knobs for the estimated stats. The zero value is fine for most use.

Stats

The deterministic stats (kills, accuracy, headshots, ratings) are exact, straight from the demo. The estimated ones (spotted accuracy, counter-strafe, spray, time-to-damage, crosshair) rebuild visibility and recoil from the demo's geometry and timing, since the game never records that.

docs/stats.md walks through how each number is computed.

Map data

No map geometry ships with demolens. CS2 maps are Valve's assets, so you pull collision meshes from your own install with extract-map. Full setup in docs/maps.md.

License

MIT. See LICENSE.

Documentation

Index

• func Analyze(r io.Reader, opts Options) (*model.Match, error)
• func Validate(r io.Reader) (demofile.Info, error)
• type Calibration
  • func DefaultCalibration() Calibration
• type Options

Functions

func Analyze

func Analyze(r io.Reader, opts Options) (*model.Match, error)

Analyze parses a CS2 demo from r and computes the full match analytics.

func Validate

func Validate(r io.Reader) (demofile.Info, error)

Validate checks the demo header and returns the format stamp plus a SHA-256 of the bytes.

Types

type Calibration

type Calibration = parser.Calibration

Calibration re-exports parser.Calibration, the tunable aim-stat thresholds.

func DefaultCalibration

func DefaultCalibration() Calibration

DefaultCalibration is the tuned defaults.

type Options

type Options = parser.Options

Options re-exports parser.Options, mostly so callers can flip on the heavy per-frame data without importing the parser package.