cs2parser

A fast, typed CS2 demo parser for Node.js and Bun.

Parses .dem files and live HTTP GOTV broadcasts from Counter-Strike 2, providing typed access to entities, players, game events, and more.

Install

npm install cs2parser

Quick Start

import { createReadStream } from 'fs';
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}`);
  }
});

parser.on('end', () => {
  for (const player of parser.playerControllers) {
    console.log(player.name, player.kills, player.deaths, player.position);
  }
});

await parser.parseDemo(createReadStream('path/to/demo.dem'), { entities: EntityMode.ALL });

parseHeader

Static method that reads only the demo file header without parsing the full file. Fast and low-memory.

const header = DemoReader.parseHeader('path/to/demo.dem');
if (header) {
  console.log(header.map_name);       // e.g. "de_dust2"
  console.log(header.server_name);    // server name
  console.log(header.build_num);      // CS2 build number
  console.log(header.patch_version);  // patch version
  console.log(header.game);           // undefined on premier
}

Returns null if the file header cannot be read. Only reads the first 4 KB of the file.

parseServerInfo

Static method that reads server info from the first few packets without parsing the full demo. Fast and low-memory.

const info = DemoReader.parseServerInfo('path/to/demo.dem');
if (info) {
  console.log(info.map_name);      // e.g. "de_dust2"
  console.log(info.server_name);   // server name
  console.log(info.max_clients);   // max player slots
  console.log(info.game_dir);      // e.g. "csgo"
}

Returns null if server info cannot be found. Only reads the first 16 KB of the file.

parseDemo

A single method with overloads for all input types. File paths stream by default.

// File path (streams by default )
await parser.parseDemo('demo.dem', { entities: EntityMode.ALL });

// File path sync (loads chunks consecutively into memory)
await parser.parseDemo('demo.dem', { entities: EntityMode.ALL, stream: false });

// Readable stream
await parser.parseDemo(createReadStream('demo.dem'), { entities: EntityMode.ALL });

// Pre-loaded buffer (big memory usage)
await parser.parseDemo(buffer, { entities: EntityMode.ALL });

Entity Modes

Mode	Entities	Round events	Speed
`EntityMode.NONE`	none	no	fastest
`EntityMode.ONLY_GAME_RULES`	game rules only	yes	~20% faster than ALL
`EntityMode.ALL`	all	yes	full parsing

ONLY_GAME_RULES parses the entity bitstream but only stores CCSGameRulesProxy properties. This enables synthetic round_start/round_end events without populating the full entities array.

Input	Returns	Memory
`string` path	`Promise<void>`	low
`string` path + `stream: false`	`Promise<void>`	low
`Readable` stream	`Promise<void>`	low
`Buffer`	`Promise<void>`	high

Parse Settings

Additional options can be passed to parseDemo to enable extra data:

Option	Type	Default	Description
`messages`	`boolean`	`false`	Emit `svc_UserMessage` events
`commands`	`boolean`	`false`	Emit `usercommand` events (decoded `CSGOUserCmdPB`)

await parser.parseDemo('demo.dem', { entities: EntityMode.ALL, commands: true, messages: true });

HTTP Broadcast (live GOTV)

DemoReader can parse a live CS2 GOTV broadcast over HTTP using the same event surface as .dem parsing. The broadcast feed is the protocol Valve's relays speak (/sync + /{N}/start + /{N}/full + /{N}/delta) — see Valve's reference relay and examples/relay.ts in this repo.

Quick start

import { DemoReader, EntityMode } from 'cs2parser';

const parser = new DemoReader();

parser.gameEvents.on('player_death', e => {
  console.log(`${e.attackerPlayer?.name} killed ${e.player?.name} with ${e.weapon}`);
});

await parser.parseHttpBroadcast('http://relay.example.com/match-id/', {
  entities: EntityMode.ALL
});

parseHttpBroadcast resolves when the broadcast ends ({ reason: 'stop' }), the relay stops returning new fragments ('timeout'), or the parser is cancelled. It throws if the relay returns a fatal error.

`HttpBroadcastReader` (finer control)

Use HttpBroadcastReader directly when you want to inspect sync metadata, separate the start/run phases, or stop mid-stream.

import { DemoReader, HttpBroadcastReader } from 'cs2parser';

const parser = new DemoReader();
parser.on('broadcastsync', sync => console.log('connected', sync.map, 'tick', sync.tick));

const reader = new HttpBroadcastReader(parser, 'http://relay.example.com/match-id/');
await reader.start();                    // /sync + /start + first /full
console.log('tail tick:', reader.tailTick);
const terminus = await reader.run();     // /N/delta loop
console.log(terminus.reason);            // 'stop' | 'timeout' | 'cancelled' | 'error'

Option	Type	Default	Description
`entities`	`EntityMode`	`NONE`	Same modes as `parseDemo`
`fetcher`	`BroadcastFetcher`	`globalThis.fetch`	Inject your own HTTP layer for tests, auth, or proxies
`deltaThrottle`	`number` (ms)	`1000`	Minimum gap between successful `/delta` requests
`deltaRetryInterval`	`number` (ms)	`1000`	Backoff on 404/405 (fragment not yet ready)
`maxDeltaRetries`	`number`	`10`	Consecutive 404/405s on `/delta` before terminating with `'timeout'`
`maxFullRetries`	`number`	`5`	Consecutive 404/405s on `/full` before terminating with `'error'`
`signal`	`AbortSignal`	—	External cancellation
`onFragmentError`	`(err, ctx) => 'abort' \| 'continue'`	`'abort'`	Skip a malformed fragment instead of aborting
`gameEventDescriptors`	`CMsgSource1LegacyGameEventList \| Uint8Array \| false`	bundled	Preload the game-event descriptor list (see below). Defaults to the descriptor file shipped with the package; pass `false` to skip preload

reader.stop() aborts the loop and pending fetches; reader.sync, reader.fragment, reader.tailTick expose live state.

Mid-stream joins and `gameEventDescriptors`

Broadcasts deliver CSVCMsg_GameEventList once at game start. A client connecting at fragment 700 has already missed it, so gameevent payloads would arrive without resolvable names.

The package ships a default descriptor list at dist/default-event-descriptors.bin and the reader auto-loads it when no gameEventDescriptors option is passed. For most consumers this is enough — names like player_death, weapon_fire, bomb_planted resolve out of the box.

const reader = new HttpBroadcastReader(parser, url, { entities: EntityMode.ALL });
// gameEventDescriptors omitted → bundled descriptors used automatically

To override with a fresher list (e.g. after a CS2 patch changed event IDs), generate one from any .dem of the same build:

# ~15 KB output, one-time per game build
bun scripts/dump-event-descriptors.ts path/to/demo.dem event-descriptors.bin

import fs from 'fs';
const reader = new HttpBroadcastReader(parser, url, {
  entities: EntityMode.ALL,
  gameEventDescriptors: fs.readFileSync('event-descriptors.bin')
});

Pass gameEventDescriptors: false to disable preload entirely — useful if the broadcast you're connecting to actually delivers its own descriptor list and you'd rather trust that one. You can also pass an in-memory CMsgSource1LegacyGameEventList instead of bytes.

The reader emits a synthetic gameeventlist event before processing the first fragment so the descriptor map is populated immediately.

Wire format notes

Broadcasts deliver bytes in a slightly different framing from .dem files; this is handled internally but worth knowing if you're debugging at the protocol layer:

Frame header is [uvarint cmd][LE u32 tick][1 reserved byte][LE u32 size][payload], with cmd === 0 as the end-of-stream marker. (.dem files use varints for tick and size and have no reserved byte.)
DEM_Packet / DEM_SignonPacket payloads are the raw SVC bit-stream — they are not wrapped in a CDemoPacket proto envelope as they are in .dem files.
DEM_FullPacket.string_table carries the tables that have changed since the last full packet. The reader applies these on every full fragment so instancebaseline reflects the current tick — required for entity parsing on mid-stream joins.
Compression is per-command via the DEM_IsCompressed bit (cmd | 0x40) and uses Snappy.

Events

All DemoReader events fire as usual. One additional event:

parser.on('broadcastsync', sync => {
  // BroadcastSyncDto from /sync — fragment, signup_fragment, tick, tps, map, ...
});

Terminus reasons returned by run():

Reason	Meaning
`'stop'`	Broadcast ended cleanly (`cmd === 0` end-of-stream marker received)
`'timeout'`	`maxDeltaRetries` consecutive 404/405s on `/delta` (relay stopped advancing)
`'cancelled'`	`reader.stop()`, `parser.cancel()`, or external `signal` aborted
`'error'`	Fatal error (HTTP failure, malformed fragment without `onFragmentError: 'continue'`)

Diagnostic scripts

Script	Purpose
`scripts/probe-broadcast.ts <url> [descriptors.bin]`	Connect, log `/sync` and the first 10 game events, exit
`scripts/capture-broadcast-fixture.ts <url> [outDir]`	Save `sync.json` + `/start` + `/full` + a few `/delta`s to disk for offline replay
`scripts/dump-event-descriptors.ts <demo.dem> [out.bin]`	Extract `CMsgSource1LegacyGameEventList` for `gameEventDescriptors`

A reference relay implementation is provided in examples/relay.ts for local testing.

Reader State

DemoReader exposes a handful of live properties that update during parsing. They're useful inside game-event handlers or low-level listeners.

Member	Type	Description
`header`	`CDemoFileHeader \| null`	Populated after the first `'header'` event
`entities`	`AnyEntity[]`	Sparse array indexed by entity ID. Each slot is a `TypedEntity` for known classes or `BaseEntity` otherwise; `undefined` slots mean the entity was deleted or never existed
`currentTick`	`number`	Tick currently being processed (`-1` before the first frame)
`currentTime`	`number`	`currentTick * tickInterval` — requires `'serverinfo'` to have arrived
`gameEvents`	`GameEvents`	Typed emitter for in-game events (see Game Events)
`players`	`CMsgPlayerInfo[]`	Userinfo rows from the string table, sparse-indexed by `userid & 0xff`
`playerControllers`	`Player[]`	All live `CCSPlayerController` entities wrapped as `Player` (requires `EntityMode.ALL`)
`teams`	`Team[]`	All live `CCSTeam` entities (requires `EntityMode.ALL`)
`gameRules`	`GameRules \| null`	Wrapper around the current `CCSGameRulesProxy` entity

Cancelling a parse

const parser = new DemoReader();

parser.on('tickend', () => {
  if (parser.currentTick >= 1000) parser.cancel();
});

await parser.parseDemo('demo.dem', { entities: EntityMode.ALL });

cancel() aborts an in-flight parse. It destroys the underlying stream (if any), emits a 'cancel' event, and then an 'end' event with { incomplete: true }. Calling cancel() or parseDemo() on a reader that has already ended throws.

Players

Basic player info — `parser.players`

parser.players returns CMsgPlayerInfo[] from the userinfo string table. This is the fastest way to get the roster of a demo: names and Steam IDs are available without parsing entities, so it works even with the default EntityMode.NONE.

The array is sparse — each entry lives at index player.userid & 0xff, so empty slots read as undefined. That's the same slot index used by game events, which makes it the natural way to look up the attacker or victim of a kill by raw userid.

await parser.parseDemo('demo.dem'); // EntityMode.NONE — no entity parsing

// Iterate — guard against sparse holes, or call .filter(Boolean) first.
for (const player of parser.players) {
  if (!player) continue;
  console.log(player.name, player.steamid);
}

Each CMsgPlayerInfo is a plain object decoded from the demo's userinfo string table:

Field	Type	Description
`name`	`string \| undefined`	Display name
`steamid`	`string \| undefined`	SteamID64 as a decimal string. Bots share `"0"`
`xuid`	`string \| undefined`	Xbox user id (usually equal to `steamid`)
`userid`	`number \| undefined`	In-game user id (the slot index is `userid & 0xff`)
`fakeplayer`	`boolean \| undefined`	`true` for bots
`ishltv`	`boolean \| undefined`	`true` for the HLTV/GOTV observer slot

parser.players is populated from createstringtable / updatestringtable events as soon as the userinfo table arrives, so it's usable inside 'end' and also during parsing (e.g. once the first round_start fires).

Looking up players during a game event

Game events like player_death expose userid / attacker / assister fields which are slot indices into parser.players. You can index the array directly to pull out the corresponding CMsgPlayerInfo — no entity parsing required.

const parser = new DemoReader();

parser.gameEvents.on('player_death', event => {
  const attacker = parser.players[event.attacker];
  const victim   = parser.players[event.userid];
  const assister = parser.players[event.assister];

  if (!attacker || !victim) return;

  console.log(
    `${attacker.name} (${attacker.steamid}) killed ${victim.name} with ${event.weapon}` +
    (event.headshot ? ' (HS)' : '') +
    (assister ? `, assisted by ${assister.name}` : '')
  );
});

// Runs with EntityMode.NONE — no entity parsing needed for names + steamids.
await parser.parseDemo('demo.dem');

This pattern is the fast path when you only need to log kills, build a scoreboard, or group events by player identity — anything that doesn't require live entity state like position, health, or money. For those, use event.attackerPlayer / event.player (the auto-resolved Player helpers), which require EntityMode.ALL.

Entity-backed helpers — `parser.playerControllers`

parser.playerControllers returns Player[] helper objects backed by live entity data. This requires EntityMode.ALL because it reads CCSPlayerController and CCSPlayerPawn properties.

await parser.parseDemo(createReadStream('demo.dem'), { entities: EntityMode.ALL });

for (const player of parser.playerControllers) {
  console.log(player.name, player.steamId, player.teamNumber);
  console.log('  k/d/a:', player.kills, player.deaths, player.assists);
  console.log('  money:', player.money, 'mvps:', player.mvps);
  console.log('  alive:', player.isAlive, 'health:', player.health, 'armor:', player.armor);
  console.log('  position:', player.position);
}

Player lookups

Several DemoReader methods resolve a Player helper from different identifiers. All require EntityMode.ALL.

// By controller entity ID (e.g. from event.userid_pawn lookups or parser.entities)
const p1 = parser.getPlayer(88);

// From a CMsgPlayerInfo (e.g. an element of parser.players)
const p2 = parser.getPlayerByInfo(parser.players[0]);

// By Steam account ID — the lower 32 bits of SteamID64,
// i.e. the trailing number in SteamID3 form: [U:1:918429678] -> 918429678
const p3 = parser.getByAccountId(918429678);

getPlayerByInfo returns null for bots (they share steamid === '0' so cannot be uniquely matched), for disconnected players, and before a controller has been assigned. getByAccountId is O(1) on cached entries, with a linear-scan fallback.

Player Helper

The Player class wraps a CCSPlayerController entity. It links to the player's pawn entity for position, health, and combat state. Pawn-backed getters return 0/false/null defaults while the player has no pawn (e.g. dead, spectating, or disconnected).

Identity

Property	Type	Source
`entityId`	`number` (readonly)	Controller entity index
`entity`	`TypedEntity<'CCSPlayerController'> \| undefined`	Raw controller entity
`name`	`string`	Controller
`steamId`	`string`	Controller (empty if not yet set)
`isConnected`	`boolean`	Controller (`m_iConnected === 0`)
`clanTag`	`string`	Controller
`color`	`number`	Comp teammate color (`-1` if unset)
`userInfo`	`CMsgPlayerInfo \| null`	Matching entry from `parser.players`

Team

Property	Type	Source
`teamNumber`	`number`	Controller
`team`	`Team \| null`	Linked team entity

Pawn link

Property	Type	Source
`pawnEntityId`	`number \| null`	Decoded from `m_hPlayerPawn` handle
`pawn`	`PlayerPawn \| null`	Linked pawn entity
`isAlive`	`boolean`	Controller (`m_bPawnIsAlive`)

Pawn shortcuts (delegate to pawn, return a safe default if there's no pawn)

Property	Type
`health` / `armor`	`number`
`position`	`Vector \| null`
`eyeAngles`	`{ pitch: number; yaw: number }`
`hasDefuser` / `hasHelmet`	`boolean`
`isScoped` / `isDefusing`	`boolean`

Economy

Property	Type
`money`	`number`
`totalCashSpent`	`number`
`cashSpentThisRound`	`number`

Match totals (from CCSPlayerController_ActionTrackingServices)

Property	Type
`kills` / `deaths` / `assists`	`number`
`damage`	`number`
`headshotKills`	`number`
`utilityDamage`	`number`
`enemiesFlashed`	`number`
`enemy3Ks` / `enemy4Ks` / `enemy5Ks`	`number`
`objective`	`number`

Per-round stats (from CSPerRoundStats_t, reset between rounds)

Property	Type
`round_kills` / `round_deaths` / `round_assists`	`number`
`round_damage`	`number`
`round_headshotKills`	`number`
`round_equipmentValue`	`number`
`round_cashEarned`	`number`
`round_utilityDamage`	`number`
`round_enemiesFlashed`	`number`
`round_liveTime`	`number`

General

Property	Type
`mvps` / `score` / `ping`	`number`

PlayerPawn Helper

parser.getPawn(entityId) returns a PlayerPawn helper for a CCSPlayerPawn entity. The controller property navigates back to the owning Player.

Property	Type	Description
`entityId`	`number`	Pawn entity index
`entity`	`TypedEntity<'CCSPlayerPawn'> \| undefined`	Raw pawn entity
`health` / `maxHealth`	`number`	`maxHealth` defaults to `100`
`armor`	`number`
`lifeState`	`number`	Raw life state flags
`isAlive`	`boolean`	`lifeState === 0`
`position`	`Vector`	Computed from cell + vec coords
`eyeAngles`	`{ pitch: number; yaw: number }`
`hasDefuser` / `hasHelmet`	`boolean`	From `CCSPlayer_ItemServices`
`isScoped` / `isWalking` / `isDefusing`	`boolean`
`flags`	`number`	Raw `m_fFlags` bitmask
`ownerEntityHandle`	`number`	Raw `m_hOwnerEntity` handle
`controller`	`Player \| undefined`	Owning controller, linked by `pawnEntityId`

Vector is re-exported from the package root: import type { Vector } from 'cs2parser'.

Teams

import { TeamNumber } from 'cs2parser';

for (const team of parser.teams) {
  if (team.teamNumber < TeamNumber.Terrorist) continue; // skip Unassigned/Spectator
  console.log(team.teamName, team.clanName, team.score);
  console.log('  members:', team.members.map(p => p.name));
}

TeamNumber is a const object you can import from the package root:

TeamNumber.Unassigned        // 0
TeamNumber.Spectators         // 1
TeamNumber.Terrorists         // 2
TeamNumber.CounterTerrorists  // 3

Property	Type
`entityId`	`number`
`entity`	`TypedEntity<'CCSTeam'> \| undefined`
`teamNumber`	`TeamNumber`
`teamName`	`string`
`clanName`	`string`
`score` / `scoreFirstHalf` / `scoreSecondHalf`	`number`
`members`	`Player[]`

Game Rules

const rules = parser.gameRules;
if (rules) {
  console.log(rules.roundsPlayed, rules.phase, rules.isWarmup);
}

parser.gameRules is null until the first CCSGameRulesProxy entity appears. Available with EntityMode.ALL or EntityMode.ONLY_GAME_RULES.

Property	Type	Description
`entityId`	`number`	Proxy entity index
`entity`	`TypedEntity<'CCSGameRulesProxy'> \| undefined`	Raw proxy entity
`isWarmup`	`boolean`
`isFreezePeriod`	`boolean`
`isGamePaused`	`boolean`
`isTerroristTimeOutActive`	`boolean`
`isCTTimeOutActive`	`boolean`
`roundsPlayed`	`number`
`gamePhase`	`number`	Raw phase number from the game rules proxy
`phase`	`"first" \| "second" \| "halftime" \| "postgame" \| "unknown"`	Human-readable mapping of `gamePhase`
`roundTime`	`number`	Current round length in seconds
`roundStartTime`	`number`	Server time at which the current round started
`terroristTimeOutRemaining`	`number`	Seconds remaining in the T timeout
`ctTimeOutRemaining`	`number`	Seconds remaining in the CT timeout

WinRoundReason

WinRoundReason is a const object with the round-end reason codes emitted on synthetic round_end events. Import from the package root:

import { WinRoundReason } from 'cs2parser';

parser.gameEvents.on('round_end', event => {
  if (event.reason === WinRoundReason.BOMB_DEFUSED) console.log('CTs defused the bomb');
});

Name	Value
`INVALID`	`-1`
`STILL_IN_PROGRESS`	`0`
`TARGET_BOMBED`	`1`
`VIP_ESCAPED`	`2`
`VIP_ASSASSINATED`	`3`
`T_ESCAPED`	`4`
`CT_PREVENT_ESCAPE`	`5`
`ESCAPING_T_NEUTRALIZED`	`6`
`BOMB_DEFUSED`	`7`
`T_ELIMINATED`	`8`
`CT_ELIMINATED`	`9`
`ROUND_DRAW`	`10`
`ALL_HOSTAGES_RESCUED`	`11`
`TARGET_SAVED`	`12`
`HOSTAGES_NOT_SAVED`	`13`
`T_NOT_ESCAPED`	`14`
`VIP_NOT_ESCAPED`	`15`
`GAME_COMMENCING`	`16`
`T_SURRENDER`	`17`
`CT_SURRENDER`	`18`
`T_PLANTED`	`19`
`CT_REACHED_HOSTAGE`	`20`

Game Events

Events are emitted at the end of each tick. Player references are auto-resolved — any userid / attacker / assister field is matched to a Player helper and exposed as player, attackerPlayer, assisterPlayer.

parser.gameEvents.on('player_death', event => {
  event.player;          // Player | null (victim)
  event.attackerPlayer;  // Player | null
  event.assisterPlayer;  // Player | null
  event.weapon;          // string
  event.headshot;        // boolean
});

parser.gameEvents.on('round_end', event => {
  event.winner; // team number
  event.reason; // WinRoundReason
});

parser.gameEvents.on('bomb_planted', event => { ... });
parser.gameEvents.on('bomb_defused', event => { ... });

// Catch-all listener — fires once per emitted event with the event name
parser.gameEvents.on('gameEvent', (name, event) => {
  console.log(name, event);
});

round_start and round_end are emitted as synthetic events derived from CCSGameRules.m_nRoundStartCount / m_nRoundEndCount whenever EntityMode.ALL or EntityMode.ONLY_GAME_RULES is active — the raw network versions are suppressed in those modes to avoid duplicates. With EntityMode.NONE, only the raw events fire.

Typed Entity Access

All entity classes have generated TypeScript interfaces. Use getEntity or findEntities for type-safe property access:

import { isEntityClass } from 'cs2parser';
import type { TypedEntity, AnyEntity, EntityProperties } from 'cs2parser';

// Get typed properties for a specific entity
const props = parser.getEntity(88, 'CCSPlayerPawn');
props?.['CCSPlayerPawn.m_iHealth'];    // number | undefined
props?.['CCSPlayerPawn.m_ArmorValue']; // number | undefined

// Find all entities of a class
const weapons = parser.findEntities('CAK47');
for (const { entityId, properties } of weapons) {
  console.log(entityId, properties['CAK47.m_iClip1']);
}

// Type guard for narrowing
const entity = parser.entities[306];
if (isEntityClass(entity, 'CCSGameRulesProxy')) {
  entity.properties['CCSGameRulesProxy.CCSGameRules.m_bWarmupPeriod']; // typed
}

// Parametric `TypedEntity<K>` — useful for function signatures and helpers
function controllerName(e: TypedEntity<'CCSPlayerController'>): string {
  return e.properties['CCSPlayerController.m_iszPlayerName'] ?? '';
}

// `EntityProperties<K>` — just the property map (Partial)
function pawnHp(props: EntityProperties<'CCSPlayerPawn'>) {
  return props['CCSPlayerPawn.m_iHealth'] ?? 0;
}

// `AnyEntity` is the slot type in `parser.entities[]` — known typed entities plus
// `BaseEntity` for any class outside `EntityTypeMap`.
const slot: AnyEntity | undefined = parser.entities[0];

Custom helper classes

If you need a helper for an entity class that isn't already wrapped (e.g. a weapon or grenade), extend the EntityHelper<C> base — you get a typed entity getter and a prop accessor for free:

import { DemoReader, EntityHelper } from 'cs2parser';

class C4 extends EntityHelper<'CC4'> {
  get clipAmmo(): number {
    return this.prop('CC4.m_iClip1') ?? 0;
  }
}

const parser = new DemoReader();
// ... after parsing
const c4Entities = parser.findEntities('CC4');
for (const { entityId } of c4Entities) {
  const c4 = new C4(parser, entityId);
  console.log(c4.clipAmmo);
}

Low-level Events

DemoReader is an EventEmitter. These events let you hook into the parse pipeline itself — tick boundaries, header/server info, entity lifecycle, and raw network messages.

// Parse lifecycle
parser.on('header', header => { });          // CDemoFileHeader — fires once
parser.on('serverinfo', info => { });        // CSVCMsg_ServerInfo — fires once
parser.on('tickstart', tick => { });         // number
parser.on('tickend', tick => { });           // number
parser.on('progress', fraction => { });      // 0..1, ~every 5000 frames
parser.on('end', ({ incomplete, error }) => { });
parser.on('cancel', () => { });              // fires on parser.cancel()
parser.on('error', ({ error }) => { });      // fatal parse error
parser.on('debug', msg => { });              // diagnostic strings

// String tables — populate parser.players
parser.on('createstringtable', table => { });
parser.on('updatestringtable', update => { });
parser.on('clearallstringtables', () => { });

// Entity lifecycle (requires EntityMode.ALL / ONLY_GAME_RULES)
parser.on('entitycreated', ([entityId, classId, entityType, className]) => { });
parser.on('entityupdated', ({ entityId, propId, value }) => { });
parser.on('entitydeleted', entityId => { });

// Raw game events (prefer parser.gameEvents for typed access)
parser.on('gameeventlist', list => { });
parser.on('gameevent', event => { });

// Opt-in network messages
parser.on('svc_UserMessage', msg => { });    // requires { messages: true }
parser.on('usercommand', cmd => { });        // requires { commands: true }

Any message key from SVC_Messages / ECstrike15UserMessages can be opted-in through parseDemo settings and listened to by name — messages: true and commands: true shown above are the most common.

Type Generation

Generate entity type interfaces from a demo file:

bun scripts/generate-entity-types.ts --demo path/to/demo.dem
bun scripts/generate-entity-types.ts --snapshot  # reuse saved snapshot

Proto Generation

Fetch proto definitions from SteamTracking/GameTracking-CS2 and generate TypeScript bindings:

bun scripts/generate-protos.ts

Performance

CPU: Apple M1

Demo: demo.dem (318 MB, 136,812 ticks)

Entity Mode Comparison

Mode	Throughput	Time	RSS	Heap	Entities
`EntityMode.NONE`	527.8 MB/s	0.6s	133MB	30MB	0
`EntityMode.ONLY_GAME_RULES`	138.9 MB/s	2.3s	175MB	32MB	1
`EntityMode.ALL`	120.8 MB/s	2.6s	177MB	32MB	248

ONLY_GAME_RULES parses entities but only stores game rules — enables synthetic round_start/round_end events without full entity tracking overhead.

Parse Method Comparison (EntityMode.ALL)

Method	Throughput	Time	RSS	Heap
`parseDemo(path)`	119.2 MB/s	2.7s	144MB	37MB
`parseDemo(path, {stream: false})`	122.1 MB/s	2.6s	150MB	38MB
`parseDemo(buffer)`	119.2 MB/s	2.7s	488MB	702MB
`parseDemo(stream)`	122.8 MB/s	2.6s	137MB	15MB

Examples

The examples/ directory contains runnable scripts:

File	Description
`header.ts`	`DemoReader.parseHeader` — fast metadata read
`serverinfo.ts`	`DemoReader.parseServerInfo` — tick interval / map / max clients
`stream.ts`	Streaming a `.dem` file via `Readable`
`voicedata.ts`	Opt-in `svc_VoiceData` parsing
`broadcast.ts`	Live HTTP broadcast with preloaded `gameEventDescriptors`
`relay.ts`	Reference HTTP relay (Valve protocol) for local testing

Acknowledgements

Creating this library wouldn't be possible without awesome work of:

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

Huge thanks to all of them, as they all have helped me in some way or the other during the past few years.

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
.github/workflows		.github/workflows
.husky		.husky
examples		examples
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.release-please-manifest.json		.release-please-manifest.json
ACKNOWLEDGEMENTS		ACKNOWLEDGEMENTS
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
benchmark.md		benchmark.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
commitlint.config.js		commitlint.config.js
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts

Folders and files

Latest commit

History

Repository files navigation

cs2parser

Install

Quick Start

parseHeader

parseServerInfo

parseDemo

Entity Modes

Parse Settings

HTTP Broadcast (live GOTV)

Quick start

HttpBroadcastReader (finer control)

Mid-stream joins and gameEventDescriptors

Wire format notes

Events

Diagnostic scripts

Reader State

Cancelling a parse

Players

Basic player info — parser.players

Looking up players during a game event

Entity-backed helpers — parser.playerControllers

Player lookups

Player Helper

PlayerPawn Helper

Teams

Game Rules

WinRoundReason

Game Events

Typed Entity Access

Custom helper classes

Low-level Events

Type Generation

Proto Generation

Performance

Entity Mode Comparison

Parse Method Comparison (EntityMode.ALL)

Examples

Acknowledgements

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`HttpBroadcastReader` (finer control)

Mid-stream joins and `gameEventDescriptors`

Basic player info — `parser.players`

Entity-backed helpers — `parser.playerControllers`

Packages