cs2parser

Turn Counter-Strike 2 demos and live broadcasts into typed match data.

Quick start · Browser · Documentation · Changelog

cs2parser parses CS2 .dem files and live HTTP GOTV broadcasts for match analysis, replay viewers, and broadcast tooling. Read typed game events, inspect players and entities, or subscribe to low-level network messages in Node.js, Bun, and modern browsers.

Match data	Playback and inputs	Integration
Players, teams, and game rules	Demo files, byte buffers, and streams	Typed game and parser events
Kills, rounds, and bomb events	Pause, seek, and resume on seekable inputs	Node.js, Bun, and browser exports
Entity state and smoke simulation	Live HTTP GOTV broadcasts	Embedded WASM; no production native addons

CS2 demo or GOTV relay ──► DemoReader ──► typed events + match state

Before you start: choose EntityMode.ALL for player helpers and full entity state. The default, EntityMode.NONE, skips entities. Use a new DemoReader for each demo or broadcast.

Quick start

1. Install

Requires Node.js 22 or newer, Bun, or a modern browser with WebAssembly support. The package uses ES modules and includes TypeScript declarations. Both exports embed the WASM Snappy decoder, so there are no separate WASM assets to serve.

npm install cs2parser

2. Parse a demo

Save as parse-demo.mjs:

import { DemoReader, EntityMode } from 'cs2parser';

const parser = new DemoReader();

parser.gameEvents.on('player_death', event => {
	const attacker = event.attackerPlayer;
	const victim = event.player;
	if (attacker && victim) {
		console.log(`${attacker.name} killed ${victim.name} with ${event.weapon}`);
	}
});

try {
	const outcome = await parser.parseDemo(process.argv[2] ?? 'demo.dem', {
		entities: EntityMode.ALL
	});

	console.log('Parsing finished:', outcome.status);
	for (const player of parser.playerControllers) {
		console.log(player.name, player.kills, player.deaths, player.position);
	}
} catch (error) {
	console.error('Parsing failed:', error);
	process.exitCode = 1;
}

3. Run it

Pass the path to a CS2 demo:

node parse-demo.mjs path/to/demo.dem

File paths are read on demand. You can also pass a Node stream, File / Blob, Uint8Array / Buffer, or web stream. The returned status is complete, incomplete, or cancelled; parsing failures reject the promise.

Listeners run synchronously; promises returned by async listeners are not awaited. Player helpers expose live state, so copy the values you need when recording history. See Parsing demos for input types, completion handling, and cancellation.

Choose how much to parse

Mode	Available data	Use it for
EntityMode.NONE (default)	Messages, game events, and basic player info; no entities	Event logs and rosters without full entity parsing
EntityMode.ONLY_GAME_RULES	Game rules and derived round events	Round tracking without player entity state
EntityMode.ALL	Full entity state, player helpers, teams, and smokes	Player statistics, positions, and replay analysis

event.player and event.attackerPlayer require EntityMode.ALL. With NONE, use parser.players for basic names and Steam IDs. See Players and pawns for lookups and Game and parser events for round-event behavior.

Browser

Import from cs2parser/browser in your browser application:

import { DemoReader, EntityMode } from 'cs2parser/browser';

// file is a File from an <input type="file"> or drag-and-drop.
const parser = new DemoReader();
parser.gameEvents.on('player_death', event => console.log(event.weapon));
parser.on('progress', bytesParsed => console.log(bytesParsed / file.size));

const outcome = await parser.parseDemo(file, { entities: EntityMode.ALL });
console.log(outcome.status);

Pass a File directly to enable pause, seek, and resume, or a web stream for sequential parsing. See Browser usage for fetch examples, runtime requirements, and WASM details.

Live HTTP broadcasts

Connect to a CS2 GOTV HTTP relay and use the same events as demo parsing:

import { DemoReader, EntityMode } from 'cs2parser';

const parser = new DemoReader();
parser.gameEvents.on('round_end', event => {
	console.log('Round winner:', event.winner);
});

const outcome = await parser.parseHttpBroadcast('https://relay.example.com/match-id/', {
	entities: EntityMode.ALL
});
console.log(outcome.status); // 'complete', 'timeout', or 'cancelled'

Replace the example URL with your relay address. See Live HTTP broadcasts for relay options, mid-stream joins, and cancellation.

Read metadata without a full parse

import { DemoReader } from 'cs2parser';

const header = await DemoReader.parseHeaderAsync('demo.dem');
console.log(header?.map_name, header?.server_name);

Metadata helpers read only the relevant parts of the demo. The browser export accepts bytes or a File / Blob instead of a filesystem path. See Reading metadata for server info, file info, and synchronous alternatives.

Documentation

Read	What you will find
Parsing demos	Inputs, entity modes, settings, reader state, and cancellation
Pausing and seeking	Tick-boundary playback controls, FullPackets, and seekable sources
Reading metadata	Header, server info, and file info without a full parse
Browser usage	Files, web streams, metadata, and WASM Snappy
Live HTTP broadcasts	GOTV relays, options, descriptors, and wire format
Players and pawns	Rosters, lookups, bot analysis, and helper properties
Entities and match state	Teams, game rules, and typed entity access
Smokes	Seed voxels, density simulation, and visual comparison
Game and parser events	Typed game events, equipment and grenade lifecycles, parser events
Network messages	Subscriptions, user commands, and message discovery
Encrypted demo chat	Match keys, public chat decryption, and browser support
Development	Entity types, protobuf bindings, and generated registries
Performance	Benchmark commands, methodology, and custom cases
Examples	Runnable scripts and command-line usage
Changelog	Released changes

Upgrading from 1.x? See the migration guide.

Used by

• liga.dust2.dk
• radar.dust2.org

Development

With Node.js and Bun installed:

npm ci
npm run typecheck
npm test
npm run build

See Development for code generation and Performance for benchmarks.

Acknowledgements

This library builds on the work of:

• LaihoE, creator of demoparser
• Saul, creator of demofile-net
• markus-wa, creator of demoinfocs-golang

Huge thanks to all of them for their help over the years.

License

Mozilla Public License 2.0