A Dota 2 replay parser for Python

The replay, read back as facts.

gem turns Source 2 .dem files into typed Python objects, DataFrames and interactive reports. It reports what happened; the interpretation is yours.

Read the guide See a reportpip install gem-dota

Offline: No servers, no API keys
Old and new: Both combat-log formats, one schema
Pure Python: 3.10 and newer, MIT licensed

01 · Parsing

From replay bytes to a table.

A replay is a stream of protobuf messages and entity updates. gem decodes it into aParsedMatch: players, fights, wards, objectives and the full combat log.

import gem
from gem.constants import hero_display

match = gem.parse("8856501050.dem")
for p in match.players[:5]:
    print(hero_display(p.hero_name),
          p.kills, p.deaths, p.assists,
          p.net_worth, p.gold_per_min)

frames = gem.parse_to_dataframe("8856501050.dem")

Hero	K / D / A	Net worth	GPM
Tiny	10 / 6 / 12	51,761	718
Sniper	11 / 8 / 13	60,021	773
Timbersaw	6 / 8 / 20	58,262	660
Lion	4 / 15 / 19	19,033	332
Ancient Apparition	0 / 7 / 19	24,409	432

Table 1. Vici Gaming, who won match 8856501050, straight from match.players.

02 · The map

A map model you can check.

Regions and camps are traced on the 7.41 map and checked against the replays' own neutral spawners and combat log. gem.region_of(x, y) tells you where any position is. Wards carry exact positions; gem samples heroes each second, and Figure 3 reads them on every replay packet.

Figure 1. gem's map model on the 7.41 map: both halves, the river, the two lotus pools and all 28 neutral camps, coloured by type.

large
small
ancient
medium
flooded small
flooded medium

Figure 2. The 7 wards up at 42:49, the first death of Figure 3's fight. Radiant had 2 observers and 4 sentries up, Dire 1 sentry; circles are observer vision. Over the whole match the teams placed 82 observers, 63 of them in the Radiant half, and 139 sentries.

Observer
Sentry
Radiant
Dire

Figure 3. The match's biggest fight, 42:34–43:46: each hero, ringed in its team's colour, where it was at the last death, and ✕ where each hero died.

03 · Recipes

Questions, answered from the facts.

Did the Roshan team win the next fight?Across the nine fixture replays, the Roshan team won 15 of the 24 next fights that had a winner.How fast did each core farm from 10 to 20 minutes?In match 8974053011, Razor earned 860 gold a minute from 10:00 to 20:00 and spent half of it in Radiant's half.How often did a smoke lead to a kill?74 of 137 smokes got a kill within 60 seconds, a median of 26 seconds after the smoke.

04 · Where to start

Use itQuickstartInstall gem, parse a replay and export data.Understand itHow proto parsing worksWhat a replay is made of and how gem reads it.Integrate itAPI referenceEvery public class and function, from the docstrings.

gem is a pure-Python parser. The Go (Manta) and Java (Clarity) parsers are faster; gem aims for Python-native data and an implementation you can read end to end.