Boon

Boon is a fast Deadlock demo parser. The Rust core has native Python bindings. Boon reads Source 2 .dem files and returns Polars DataFrames.

Table of Contents

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

Why Boon?

Deadlock demos contain player positions, kills, damage, item builds, objective state, and other match data. The Source 2 demo format is complex and undocumented. Boon handles the format so that you can analyze structured data.

• ⚡ Fast. The core parser is written in Rust. Parsing a full match takes seconds, not minutes.
• 📊 Structured output. Each dataset is a Polars DataFrame. You can filter, group, join, and display the data.
• 🎯 Parse only what you need. Boon loads each dataset on demand. Use load() to parse multiple datasets in one pass.
• 🗂️ Comprehensive. Player state, combat, economy, objectives, map props, Sinner's Sacrifice, derived stats, buffs/debuffs, urn and Rift 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 adds the boon command to your PATH. See the CLI documentation. The repository also contains the low-level boon-dev debug tool. Build it with cargo build --release -p boon-dev.

Rust library

[dependencies]
boon-deadlock = "0.8"

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 boon-dev tool adds low-level commands such as entities, events, and send-tables. Build it with cargo build --release -p boon-dev. See the CLI reference.

Available Datasets

Each dataset is a Demo property that returns a Polars DataFrame. Boon loads a dataset when you first access it. Use load() to parse multiple datasets in one pass. Call Demo.available_datasets() to get the full list.

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 mitigation, hitgroups, source metadata, and light/heavy/other melee classification
item_purchases	Item shop transactions (purchased, upgraded, sold, swapped, failed)
ability_upgrades	Hero ability point spending (tier 1-3)
ability_ticks	Ability cooldown, charge, and slot state changes
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)
breakables	Breakable map-prop destruction events with resolved subclass and last-known position (opt-in)
sinners_sacrifice	Sinner's Sacrifice machine lifecycle and exact hit attribution (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)
rift	Rift (Koth) lifecycle, capture/expiry, winner, lane, and position (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 that use 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 setup instructions, coding standards, and submission instructions.

License

MIT — see LICENSE for details.