pbdems2
pbdems2 is a game-neutral Rust library for Valve Source 2 demos. It handles the shared PBDEMS2 container and entity wire format. Games keep their own protobufs and domain logic.
It is built for projects like Boon for Deadlock and Awpy for CS2.
What it handles
- PBDEMS2 headers, commands, packet messages, and Snappy bodies
- byte and bit readers
- serializers, field paths, and configurable field decoding
- entities, string tables, baselines, and coordinates
- playback, tick callbacks, seeking, filtering, and decode limits
- borrowed input and optional memory-mapped files
Game crates handle generated protobufs, events, domain models, constants, and language bindings. Basically, if it's specific to a game, you won't find it in pbdems2!
Field paths use signed components and compact 64-bit keys. Treat field keys as opaque values. Resolve them from the current serializer; do not store numeric keys across parser upgrades. Pointer clears and vector shrink updates remove child values. Other partial updates preserve fields that were not sent.
Decoded class baselines are cached within each entity container. Changes to baseline bytes, serializers, tick intervals, or decode limits invalidate reuse. Cloned sessions rebuild this cache on demand.
Format guide
The PBDEMS2 format guide documents the shared file header and command stream, packet-message framing, serializers and field paths, string tables and baselines, entities and handles, and the adapter/playback lifecycle. Game-specific parsers can link to these pages and keep only their protobuf and domain documentation locally.
Game adapters
Each game supplies a neutral decode profile for its wire quirks:
use ;
const PROFILE: DecodeProfile = new
.with_ammo_field;
Adapters decode their protobuf messages, convert them to pbdems2 input types,
and pass them to CommandContext. Generated messages never enter pbdems2.
Parsing
Demo gives you allocation-free command iteration and a header-only seek
index. DemoParser adds signon setup, playback, tick callbacks, filtering, and
full-packet seeks.
let limits = default
.with_max_command_body_bytes
.with_max_packet_message_bytes;
let parser = with_limits?;
let state = parser.try_run_to_end?;
Use the try_* methods when a tick callback can fail. The regular methods take
infallible callbacks.
Inside a tick callback, EntityContainer::entity_changes exposes ordered create, update, reactivation, leave-PVS, and delete records. Each record keeps the entity index, serial, class ID, and shared class name. This makes slot reuse unambiguous without cloning full entities or allocating a class name per change. The log clears after a successful callback. Sign-on establishes the initial state without emitting changes, and full-packet keyframes report the commands they decode rather than a synthetic snapshot. The older updated_indices API keeps its existing behavior.
CommandContext::packet_messages reads the common packet framing while the
adapter decides what each message ID means. Aligned payloads are borrowed.
PacketMessageFrame::payload_or_copy returns that borrowed slice when possible
and otherwise reconstructs the payload in one caller-owned reusable buffer.
Demo::header exposes validated file-info and spawn-groups offsets.
parse_to_tick starts at the nearest full packet and replays the needed deltas.
Prepared playback
Adapters that implement CheckpointAdapter can decode signon and build the
seek index once, then create independent sessions for repeated or parallel
work:
let prepared = parser.prepare?;
let state = prepared
.session?
.try_run_to_end?;
PreparedPlayback does not borrow the encoded bytes, so an owning game parser
can cache it without becoming self-referential. Each session verifies that its
DemoParser uses the same allocation and decode limits, then clones neutral
state and restores a fresh adapter from the signon checkpoint.
Use try_run_to_end_with_adapter and the corresponding filtered or segment
methods when a callback also needs game-specific adapter state. This supports a
single entity-and-event pass without putting generated messages or event types
in pbdems2.
Prepared values can be shared across threads when their checkpoint state is
Send + Sync. PreparedPlayback::segment_plan produces a bounded,
never-empty set of ranges across the post-signon baseline, full-packet
keyframes, and the demo tail; each range can be decoded in an independent
session. Full-packet segment restarts are exact only for classes that the game
fully re-keyframes in those snapshots.
Limits and large files
DecodeLimits bounds untrusted lengths and counts before allocation. Limit,
allocation, command, and packet errors keep useful context.
The optional mmap feature provides an owning read-only map:
= { = "0.4", = ["mmap"] }
// SAFETY: Keep the file unchanged and untruncated while `mapped` exists.
let mapped = unsafe ;
let parser = mapped.parser?;
The constructor is unsafe because the caller must keep the mapped file stable.
Install
[]
= "0.3"
Serde support is on by default and includes EntityId and lifecycle records. Turn it off if you do not serialize decoded values:
= { = "0.4", = false }
Consumer crates can keep old module paths with re-exports:
CLI
The private pbdems2-cli crate builds a pbdems2 inspector. It maps the file,
validates every command, and reports offsets, sizes, ticks, seek points, and
compression stats.
Add --json for machine-readable output. Release archives include Linux,
macOS, and Windows binaries. The CLI is not published to crates.io, but is available on the Releases.
Select entity properties
Compile a filter from a prepared playback's serializers, then create a new session:
use PropertyFilter;
let filter = new;
prepared.session_with_properties?.run_to_end?;
The filter is optional. Without it, full decoding uses the existing path.
Unlisted classes keep all fields; combine property and class filters to omit
other classes. Missing paths select nothing. Use field_value or try_get to
distinguish an omitted value from zero.
A composite or array path selects its entire subtree, including future elements.
For example, Deadlock consumers can select
m_CCitadelAbilityComponent.m_vecAbilities. Numeric dynamic-array element paths
select only that element. Pointer presence and array lengths are always retained
so clear and shrink updates remove stale children.
The selection is fixed for the session and remains in its checkpoints. Use a
fresh session to change it. The filter rejects a different serializer schema;
the demo index's has_schema_changes() can identify files that need full
decoding. Skipped values still consume their wire data and enforce decode limits.