deadem is the original Deadlock (Source 2) demo parser and replay player for Node.js, Deno, Bun, and browsers, built on top of @deademx/engine.

For the shared parser model, player lifecycle, interceptors, configuration, and the full API surface, see the engine documentation. This document covers Deadlock-specific usage only.

Other game implementations: @deademx/cs2 (Counter-Strike 2) and @deademx/dota2 (Dota 2).

Contents

• Installation Install from npm or use the browser bundle.
• Quick start Minimal example to parse a Deadlock demo file.
• Examples Runnable example scripts covering parsing, player, and broadcast.
• Usage Deadlock-specific usage patterns.
  • Replay file Parse a Deadlock replay from a .dem file.
  • HTTP broadcast Parse a live Deadlock HTTP broadcast stream.
  • Data extraction Extract chat messages and query Deadlock entities.
  • Playback and seeking Inspect Deadlock state at a specific tick.
• Compatibility Supported game builds and runtimes.
• Performance Measured throughput and memory usage.
• License Project licensing information.

Installation

Node.js / Deno / Bun

npm install deadem --save

import { Parser, Player } from 'deadem';

Browser

<script src="//cdn.jsdelivr.net/npm/[email protected]/dist/deadem.min.js"></script>

const { Parser, Player } = window.deadem;

Quick start

import { createReadStream } from 'node:fs';

import { Parser, Printer } from 'deadem';

const parser = new Parser();
const printer = new Printer(parser);

await parser.parse(createReadStream(PATH_TO_DEM_FILE));
await parser.dispose();

printer.printStats();

Parser and Player in deadem are drop-in subclasses of the engine classes — the schema registry is built automatically, so no extra wiring is required.

Examples

All example scripts live in the examples-node-deadem package. They look for demo files in /demos; missing files are downloaded automatically from deadem.com.

Parsing

| # | Description | Source | Command | | --- | --- | --- | --- | | 100 | Parse a single replay file | 100_parse.js | node ./packages/examples-node-deadem/scripts/100_parse.js | | 101 | Parse multiple replay files | 101_parse_multiple.js | node ./packages/examples-node-deadem/scripts/101_parse_multiple.js --matches="36126255,36127043" | | 102 | Parse with selective packet filtering | 102_parse_selective.js | node ./packages/examples-node-deadem/scripts/102_parse_selective.js | | 103 | Extract chat messages and chat wheel events | 103_parse_chat.js | node ./packages/examples-node-deadem/scripts/103_parse_chat.js | | 104 | Extract kill feed events | 104_parse_kill_feed.js | node ./packages/examples-node-deadem/scripts/104_parse_kill_feed.js | | 105 | Extract ability usage events | 105_parse_ability_feed.js | node ./packages/examples-node-deadem/scripts/105_parse_ability_feed.js | | 106 | Parse mid boss spawn and kill events | 106_parse_mid_boss_deaths.js | node ./packages/examples-node-deadem/scripts/106_parse_mid_boss_deaths.js | | 107 | Parse tower destruction events | 107_parse_tower_deaths.js | node ./packages/examples-node-deadem/scripts/107_parse_tower_deaths.js | | 108 | Rank high-churn entity classes and fields from ENTITY_PACKET deltas | 108_parse_entity_field_stats.js | node ./packages/examples-node-deadem/scripts/108_parse_entity_field_stats.js |

Player

| # | Description | Source | Command | | --- | --- | --- | --- | | 200 | Load and play back a replay file | 200_play.js | node ./packages/examples-node-deadem/scripts/200_play.js | | 201 | Get game duration from replay | 201_play_game_time.js | node ./packages/examples-node-deadem/scripts/201_play_game_time.js | | 202 | Identify the top damage dealer | 202_play_top_damage_dealer.js | node ./packages/examples-node-deadem/scripts/202_play_top_damage_dealer.js | | 203 | Print the final scoreboard | 203_play_scoreboard.js | node ./packages/examples-node-deadem/scripts/203_play_scoreboard.js |

Broadcast

| # | Description | Source | Command | | --- | --- | --- | --- | | 300 | Save HTTP Broadcast data to a file | 300_broadcast_save.js | node ./packages/examples-node-deadem/scripts/300_broadcast_save.js | | 301 | Parse HTTP Broadcast live | 301_broadcast_parse.js | node ./packages/examples-node-deadem/scripts/301_broadcast_parse.js | | 302 | Parse HTTP Broadcast data from a saved file | 302_broadcast_parse_file.js | node ./packages/examples-node-deadem/scripts/302_broadcast_parse_file.js |

Browser

| # | Description | Command | | --- | --- | --- | | 01 | Deadem Explorer | npm start |

Usage

Replay file

import { createReadStream } from 'node:fs';

import { Parser, Printer } from 'deadem';

const parser = new Parser();
const printer = new Printer(parser);

await parser.parse(createReadStream(PATH_TO_DEM_FILE));
await parser.dispose();

printer.printStats();

HTTP broadcast

import { BroadcastAgent, BroadcastGateway, DemoSource, Parser } from 'deadem';

const FROM_BEGINNING = false;
const MATCH_ID = '75637129_201673668';

const gateway = new BroadcastGateway('dist1-ord1.steamcontent.com/tv');
const agent = new BroadcastAgent(gateway, MATCH_ID);

const parser = new Parser();

await parser.parse(agent.stream(FROM_BEGINNING), DemoSource.HTTP_BROADCAST);
await parser.dispose();

Data extraction

Deadlock-specific message types are exposed via the extended MessagePacketType — for example, CITADEL_USER_MESSAGE_CHAT_MESSAGE, CITADEL_USER_MESSAGE_HERO_KILLED, CITADEL_USER_MESSAGE_BOSS_KILLED, CITADEL_USER_MESSAGE_MID_BOSS_SPAWNED, and more.

Extract chat messages paired with player names from the USER_INFO string table:

import { InterceptorStage, MessagePacketType, Parser, StringTableType } from 'deadem';

const parser = new Parser();
const players = new Map();

parser.registerPostInterceptor(InterceptorStage.DEMO_PACKET, (demoPacket) => {
    if (players.size === 0 && !demoPacket.getIsInitial()) {
        const userInfo = parser.getDemo().stringTableContainer.getByName(StringTableType.USER_INFO.name);

        for (const entry of userInfo.getEntries()) {
            if (Number.isInteger(entry.value.userid)) {
                players.set(entry.value.userid, entry.value.name);
            }
        }
    }
});

parser.registerPostInterceptor(InterceptorStage.MESSAGE_PACKET, (demoPacket, messagePacket) => {
    if (messagePacket.type === MessagePacketType.CITADEL_USER_MESSAGE_CHAT_MESSAGE) {
        console.log(`${players.get(messagePacket.data.playerSlot)}: ${messagePacket.data.text}`);
    }
});

await parser.parse(readable);

Query entities after the parse completes:

await parser.parse(readable);

const demo = parser.getDemo();
const controllers = demo.getEntitiesByClassName('CCitadelPlayerController');

const topDamageDealer = controllers.reduce((top, entity) => {
    const data = entity.unpackFlattened();

    return data.m_iHeroDamage > top.damage
        ? { player: data.m_iszPlayerName, damage: data.m_iHeroDamage }
        : top;
}, { player: null, damage: 0 });

console.log(`Top damage dealer: ${topDamageDealer.player} (${topDamageDealer.damage})`);

Playback and seeking

import { createReadStream } from 'node:fs';

import { Player } from 'deadem';

const player = new Player();

await player.load(createReadStream(PATH_TO_DEM_FILE));
await player.seekToTick(player.getLastTick());

const demo = player.getDemo();

demo.getEntitiesByClassName('CCitadelPlayerController').forEach((entity) => {
    const name = entity.getField('m_iszPlayerName');
    const damage = entity.getField('m_iHeroDamage');

    console.log(`${name}: ${damage} hero damage`);
});

await player.dispose();

Compatibility

• Game builds: tested with Deadlock demos from build 6448 and below.
• Runtimes: Node.js v18+, Deno, and Bun.
• Browsers: Chrome, Firefox, Safari, Edge.

Performance

For configuration trade-offs see the engine performance notes.

| # | Configuration | Ticks/sec | 30-min replay, sec | Max Heap, MB | Max ArrayBuffers, MB | Max RSS, MB | | - | --- | --- | --- | --- | --- | --- | | 1 | No filters (ParserConfiguration.DEFAULT) | 12 115 +- 2.80% | ~9.51 | 43 +- 3.65% | 17 +- 9.48% | 187 +- 2.74% | | 2 | messagePacketTypes allowlist excluding SVC_PACKET_ENTITIES | 73 277 +- 3.41% | ~1.57 | 32 +- 6.58% | 30 +- 7.74% | 241 +- 3.38% | | 3 | entityClasses allowlist | 55 834 +- 2.08% | ~2.06 | 45 +- 15.71% | 23 +- 5.53% | 239 +- 5.09% |

Runtime: Node.js v22.14.0.

License

This project is licensed under the MIT License.