demoparser2 Documentation

The DEM_Packet is the most common command type in a demo file. It is decoded by reading a bitstream where each message consists of a message type and a size.

Main message types within a DEM_Packet include:

• svc_PacketEntities: Contains the majority of entity data (coordinates, health, etc.). Note that these only send changes; if a value hasn't changed, it won't be updated in the current tick.
• GE_Source1LegacyGameEventList: Provides the decoding schema for game events. This must be processed before any game events can be decoded.
• GE_Source1LegacyGameEvent: Key-value pair events triggered by game actions (e.g., weapon fire).
• svc_CreateStringTable / svc_UpdateStringTable: Contains baseline/default values for entities (e.g., default player health).

The demoparser uses a two-pass system to process Counter-Strike 2 demo files efficiently:

1. 1st Pass (parser/src/parser.rs): A fast pass that identifies packet boundaries (start and end points) to prepare for the second pass. It also handles one-off data such as descriptors for entity data and game events.
2. 2nd Pass (parser/src/parser_thread.rs): A multi-threaded pass that performs the heavy lifting by parsing the majority of the demo data.

Understanding this separation is key to understanding how the parser achieves high performance through parallelization.

Use the @laihoe/demoparser2-darwin-x64 package if you are running on an Intel-based macOS system (x86_64-apple-darwin). This package provides the specific binary required for the @laihoe/demoparser2 library to function on this architecture.

npm install @laihoe/demoparser2-darwin-x64

If you are exploring the Rust source code to understand how data is extracted, the most critical logic resides in:

• parser/src/entities.rs: Defines entity structures.
• parser/src/collect_data.rs: Handles data collection.

Specifically, all newly decoded values are processed through the decode_entity_update function. This is the primary entry point for understanding how raw demo data is transformed into usable entity updates.

This package provides the aarch64-unknown-linux-musl binary for the @laihoe/demoparser2 library. Use this specific package if your target environment is a Linux system running on ARM64 architecture using the musl C library (common in lightweight distributions like Alpine Linux).

npm install @laihoe/demoparser2-linux-arm64-musl

To benchmark the parser's performance and reproduce the baseline metrics, use the parse_bench binary. The benchmark performs a representative full parse (including player properties, all events, and ticks) using a release build with Link Time Optimization (LTO) enabled.

Run the benchmark using the following command structure:

# Build the benchmark binary in release mode
cargo build --release --bin parse_bench

# Run the benchmark
# Usage: ./target/release/parse_bench <demo_path> <iterations> <mode>
./target/release/parse_bench "<path_to_demo>" 5 both

Arguments:

• <demo>: Path to the .dem file.
• 5: Number of timed iterations.
• both: Run both single-threaded (st) and multi-threaded (mt) modes.

cargo build --release --bin parse_bench
./target/release/parse_bench "<nuke.dem>" 5 both

You can install the demoparser2 library depending on your target environment:

• Python (requires Python >= 3.8): Use pip.
• NodeJS: Use npm to install the standard package.
• WASM: Use npm to install the WASM-specific package.

# Python
pip install demoparser2

# NodeJS
npm i @laihoe/demoparser2

# WASM
npm i demoparser2

To install demoparser2 into your current Python environment, use maturin. It is recommended to perform this installation within a virtual environment (venv) or a conda environment to avoid conflicts with system packages.

Run the following command from the root of the repository:

maturin develop --release