Architecture

gem turns a raw .dem binary into structured Python objects in a single pass. This page shows how the modules fit together and what each layer produces.

Pipeline

Data flows top to bottom in a single pass. The schema layer feeds two parallel consumers — event processing and the extractors — which both fan back into assembly.

Entry pointgem.parse() · gem.parse_to_dataframe()

↓

Binary decodingOuter demo frames → bits, bytes, and varints

↓

Schema & stateSerializer tree, field decoders, string tables, entity deltas

↓

EventsGame events & the combat log (S1 + S2)

ExtractorsPlayers, objectives, wards, courier, draft, teamfights

↓

AssemblyCombat aggregation → typed result assembly

↓

OutputParsedMatch → DataFrames · JSON · Parquet

Layers at a glance

Entry points

gem.parse()gem.parse_to_dataframe()gem.parse_to_json()gem.parse_to_parquet()

Binary decoding

binary/stream.pybinary/reader.py

Schema decoding

schema/sendtable/schema/field_decoder/schema/field_path/state/string_table.pystate/entities.py

Events

state/game_events.pycombat/log.py

Extractors

extractors/players.pyextractors/objectives.pyextractors/wards.pyextractors/courier.pyextractors/draft.pyextractors/teamfights.py

Assembly

combat/aggregator.pyresults/assembly.py

Output

results/models.py · ParsedMatchresults/dataframes.py

Output model

gem.parse() returns a single ParsedMatch. Every field is either a scalar or a list of typed dataclasses — no raw dicts, no untyped payloads.

Field	Type	What it contains
players	list[ParsedPlayer]	One entry per player — KDA, gold/XP series, purchases, runes, buybacks, positions
draft	list[DraftEvent]	Chronological pick and ban events with hero name and team
combat_log	list[CombatLogEntry]	Every damage, kill, heal, ability-use, and modifier event
towers / barracks	list[TowerKill / BarracksKill]	Objective deaths with tick, team, and killer
roshans	list[RoshanKill]	Roshan kills with kill number and killer slot
tormentors / shrines	list[TormentorKill / ShrineKill]	Tormentor and Shrine of Wisdom destruction events
wards	list[WardEvent]	Ward placements with exact map coordinates
teamfights	list[Teamfight]	Detected fight windows with per-player damage, kills, and healing
smoke_events	list[SmokeEvent]	Smoke activations with grouped heroes and centroid position
aegis_events	list[AegisEvent]	Aegis pickups, steals, and denies
courier_snapshots	list[CourierSnapshot]	Courier state sampled each tick
chat	list[ChatEntry]	All-chat and team-chat messages
radiant_gold_adv / radiant_xp_adv	list[int]	Per-minute Radiant gold and XP advantage curves

For the full field listing see the Models reference and Full Match Data guide.