Boon

Boon is a fast Deadlock demo / replay parser written in Rust with native Python bindings. It parses Source 2 demo files (.dem) and returns Polars DataFrames, giving you structured access to match data without dealing with the binary format yourself.

Table of Contents

• Why Boon?
• Installation
• Quick Start
• Available Datasets
• Project Structure
• Documentation
• Useful Links
• Contributing
• License

Why Boon?

Deadlock demo files contain a wealth of match data — player positions, kills, damage, item builds, objective state, and more — but the Source 2 demo format is complex and undocumented. Boon handles the low-level parsing so you can focus on analysis.

• ⚡ Fast. The core parser is written in Rust. Parsing a full match takes seconds, not minutes.
• 📊 Structured output. Every dataset is a Polars DataFrame, ready for filtering, grouping, joins, and visualization.
• 🎯 Parse only what you need. Each dataset is loaded on demand. Request one property and Boon skips everything else. Batch multiple datasets with load() to share a single parse pass.
• 🗂️ Comprehensive. Player state, kills, damage, item purchases, ability upgrades, objectives, chat, lane troopers, neutral creeps, buffs/debuffs, urn tracking, and street brawl scoring.
• 💻 CLI included. pip install boon-deadlock ships a boon command for quick inspection without writing any code.

Installation

Boon can be used as a Python library, a Rust crate, or a standalone CLI tool.

Python

We recommend using uv:

uv add boon-deadlock

You can also use pip:

pip install boon-deadlock

Requires Python 3.11–3.14.

CLI

pip install boon-deadlock (or uv add boon-deadlock) puts a boon command on your PATH automatically — see the CLI docs. A separate low-level boon-dev debugging tool also lives in the repo; build it from source with cargo build --release -p boon-dev.

Rust library

[dependencies]
boon-deadlock = "0.6"

Quick Start

Python

from boon import Demo

demo = Demo("match.dem")

# Match metadata
print(demo.match_id)         # 70555151
print(demo.map_name)         # "start"
print(demo.total_clock_time) # "37:38"
print(demo.winning_team_num) # 3

# Datasets are Polars DataFrames, lazy-loaded on first access
kills = demo.kills
damage = demo.damage
player_ticks = demo.player_ticks

# Batch-load multiple datasets in a single parse pass
demo.load("kills", "damage", "player_ticks", "objectives")

# See what datasets are available
Demo.available_datasets()

# Derived stats (boon.stats), also exposed as Demo methods
demo.kill_participation()    # (kills + assists) / team kills, per player

CLI

Bundled with the Python package (pip install boon-deadlock):

# Match metadata
boon info match.dem

# Player roster
boon players match.dem

# Any dataset as a table (add --json for machine-readable output)
boon show match.dem kills --limit 20

# Post-match summary
boon summary match.dem

# All available commands
boon --help

The in-repo boon-dev tool (build from source: cargo build --release -p boon-dev) adds lower-level commands (entities, events, send-tables, …); see the CLI reference.

Available Datasets

Each dataset is a property on the Demo class that returns a Polars DataFrame. Datasets are lazy-loaded on first access — Boon only parses what you request. If you need multiple datasets, load() parses them in a single pass for efficiency. Call Demo.available_datasets() to see the full list programmatically.

Dataset	Description
player_ticks	Per-player state every tick (position, health, souls, net worth, kills, deaths, assists, 40+ fields)
world_ticks	World state every tick (pause state, next mid boss spawn)
kills	Hero kill events with attacker, victim, and assisters
damage	Damage events with pre/post mitigation, hitgroups, and crit damage
item_purchases	Item shop transactions (purchased, upgraded, sold, swapped)
ability_upgrades	Hero ability point spending (tier 1-3)
abilities	Important ability usage events
flex_slots	Flex slot unlock events per team
chat	In-game chat messages (all chat and team chat)
objectives	Objective health state changes (walkers, barracks, shrines, patron, mid boss) with position and phase tracking
mid_boss	Mid boss lifecycle events (spawn, kill, rejuv pickup/use/expire)
troopers	Per-tick alive lane trooper state with position (opt-in, large)
neutrals	Neutral creep state changes with change detection (opt-in)
stat_modifier_events	Permanent stat bonus change events from pickups (opt-in)
active_modifiers	Active buff/debuff modifier events (opt-in)
urn	Urn lifecycle and delivery point events (opt-in)
street_brawl_ticks	Per-tick street brawl state (street brawl only)
street_brawl_rounds	Street brawl round scoring events (street brawl only)

Project Structure

Crate	Description
boon	Core parser library (published as boon-deadlock on crates.io)
boon-proto	Auto-generated Deadlock protobuf definitions
boon-dev	Low-level developer / debugging CLI (in-repo only, not published)
boon-python	Python bindings via PyO3 (published as boon-deadlock on PyPI)

Documentation

Full documentation is available at boon.readthedocs.io, including:

• Getting Started
• Examples
• API Reference
• CLI Reference
• FAQ
• Known Issues
• Changelog

Useful Links

• Deadlock — official home page
• Steam store page
• Deadlock Wiki
• r/DeadlockTheGame — Reddit community
• deadlock.nyc — an online demo parser powered by Boon

Contributing

See CONTRIBUTING.md for development setup, coding standards, and how to submit changes.

License

MIT — see LICENSE for details.