Datasets#
Dataset properties on Demo return cached Polars DataFrames with typed columns.
Batch loading#
Use Demo.load() when an analysis needs several datasets:
demo.load("players", "stats")
players = demo.players
stats = demo.stats
The method returns None and caches the requested DataFrames.
It validates all names before decoding and skips cached datasets.
Use Demo.available_datasets() to list valid names.
Requested event datasets share one pass, as do requested grenades, fires,
and smokes. Stats reuse combat, round, and roster inputs.
A combined stats request can also collect bomb and shot rows in that pass.
Direct property access prepares its compatible event or projectile group.
Use load() to restrict collection to a known set.
Entity rows expose a slot (entity_id) and generation (entity_serial).
Use both as the identity: the engine can reuse slots after deletion.
All Steam ID columns use Polars UInt64, including columns that are empty or
contain only null values. Keep this type when you join datasets. To convert a
dataset to pandas without a floating-point conversion, use Arrow extension
arrays:
pandas_kills = demo.kills.to_pandas(use_pyarrow_extension_array=True)
This conversion requires pyarrow. The default NumPy-backed pandas conversion
cannot represent nullable integers and can change a nullable Steam ID column to
float64.
rounds#
demo.rounds
One row per round, reconstructed from CCSGameRules.
Round events are not required. Overtime rounds are included.
Column |
Type |
Description |
|---|---|---|
|
i32 |
1-indexed round number ( |
|
i32? |
Tick the round’s freeze time began (null if not observed). |
|
i32? |
Tick freeze time ended and play began. |
|
i32 |
Tick the round was decided (a winner was set). |
|
i32? |
Tick the round officially ended (post-round reset, ≈ the next round’s freeze start); null for the last round. |
|
i32 |
Winning team number (2 = terrorist, 3 = counter-terrorist). |
|
str |
Winning side name. |
|
i32 |
Raw round-end reason code ( |
|
str |
Human-readable reason (e.g. |
|
bool |
Whether this is a knife round — a side-decider round where every kill is a melee (knife) kill, with no firearm or grenade kills. Excluded from |
# Final score by side
demo.rounds.group_by("winner_side").len()
kills#
demo.kills
One row per player_death event. Entity decoding resolves participants and
positions, so this costs more than reading raw events.
For each of attacker, victim, assister:
Column |
Type |
Description |
|---|---|---|
|
i32? |
Player-pawn entity slot. |
|
u32? |
Player-pawn entity generation. |
|
u64? |
64-bit Steam id (from the controller’s |
|
str? |
Display name ( |
|
str? |
|
|
f32? |
World position (Hammer units) at the kill tick. |
Plus the kill’s own fields: weapon (str), headshot (bool), dominated,
noscope (bool), penetrated, revenge, thrusmoke (bool), hitgroup,
hitgroup_name, is_trade (bool), victim_traded (bool), and tick.
Participant columns are null if the participant is absent or cannot be resolved.
Trades#
Two flags mark each kill’s place in a trade. A trade is a kill that avenges a teammate killed within the last 5.25 seconds:
Column |
Description |
|---|---|
|
This kill is a trade — the attacker killed someone who had just killed one of their teammates. |
|
This kill’s victim was traded — a teammate of the victim killed this attacker within the window. |
Each revenge kill trades only the earliest qualifying teammate death within
5.25 seconds. Each death can be traded once. Equal-tick deaths use event order.
The revenge kill has is_trade; the matched death has victim_traded.
Stats count victim_traded as traded_deaths.
The two flag totals are equal. A kill can have both flags.
# Headshot rate per weapon
kills = demo.kills
kills.group_by("weapon").agg(
total=pl.len(),
hs_rate=pl.col("headshot").mean(),
).sort("total", descending=True)
# Kills by side
kills.group_by("attacker_side").len()
# Who trades for their team the most?
kills.filter(pl.col("is_trade")).group_by("attacker_name").len().sort("len", descending=True)
# How often does each player's death go unavenged?
kills.group_by("victim_name").agg(
deaths=pl.len(),
traded=pl.col("victim_traded").sum(),
).with_columns(trade_rate=pl.col("traded") / pl.col("deaths"))
damages#
demo.damages
One row per player_hurt game event, with the attacker and victim resolved to a
Steam id, name, side, and world position (like kills), plus the victim’s
health/armor before and after the hit.
For each of attacker, victim: <who>_entity_id, <who>_entity_serial,
<who>_steamid, <who>_name, <who>_side, and <who>_x / _y / _z.
Other columns: weapon, dmg_health, dmg_armor, hitgroup, hitgroup_name,
health_pre, health_post, armor_pre, armor_post, and tick.
Pre-hit values are post + damage, capped at 100.
Raw damage can exceed the victim’s remaining health.
bomb#
demo.bomb
Bomb actions with the acting player and their position. Columns: tick,
event (one of pickup, drop, start_plant, interrupt_plant,
finish_plant, defuse), entity_id, entity_serial, steamid, name,
bombsite (A / B; null before the plant), x, y, z.
start_plant and interrupt_plant rows require the corresponding events.
grenades#
demo.grenades
Thrown-grenade trajectories — one row per tick each grenade projectile is in
flight (samples stop once it settles). Columns: tick, thrower_name,
thrower_steamid, thrower_side, type (smoke / he / flashbang /
molotov / decoy), entity_id, entity_serial, x, y, z.
fires / smokes#
demo.fires # burning infernos (molotov / incendiary)
demo.smokes # deployed smoke clouds
One row per fire / smoke. Columns: start_tick, end_tick,
thrower_name, thrower_steamid, thrower_side, entity_id,
entity_serial, x, y, z. fires also has a type column.
The window is the game’s own event pair, not the (longer) entity lifetime:
inferno_startburn → inferno_expire for fires (the ~7 s burn, cut short when a
molotov is smoked out) and smokegrenade_detonate → smokegrenade_expired for
smokes (the deployed cloud, excluding the throw).
Use an interval join to find player samples during fires. Apply a spatial filter to test whether a player was inside a fire:
import polars as pl
pos = demo.snapshots(start_tick=demo.fires["start_tick"].min(), end_tick=demo.fires["end_tick"].max())
in_fire = pos.join_where(
demo.fires,
pl.col("tick") >= pl.col("start_tick"),
pl.col("tick") <= pl.col("end_tick"),
)
shots#
demo.shots
One row per weapon_fire event, with the shooter’s state and active-weapon
state. Columns: tick, entity_id, entity_serial, steamid, name, side,
x, y, z, pitch, yaw, weapon, scoped, inaccuracy (the
weapon’s networked accuracy penalty), and num_bullets_remaining (active
weapon’s clip).
blinds#
demo.blinds
One row per flash event — a player blinded by a flashbang — resolved like
kills: the attacker (the flash’s thrower) and victim (the blinded player)
each get a Steam id, name, side, and world position, plus a duration.
Column |
Type |
Description |
|---|---|---|
|
i32 |
Tick the flash detonated and the blind began. |
|
The flash’s thrower. |
|
|
The thrower’s pawn identity. |
|
|
The blinded pawn’s identity. |
|
|
The blinded player. |
|
|
f32 |
Blind duration in seconds. |
The attacker may be a teammate (a team-flash) or the victim themselves (a
self-flash), so filter on attacker_side / victim_side or compare Steam ids
as needed.
Awpy reconstructs blinds from increases in a pawn’s flash duration.
It attributes the flash to a flashbang_detonate event on the same tick.
Without those events, the result is empty.
# Enemy flashes only, longest first
import polars as pl
demo.blinds.filter(pl.col("attacker_side") != pl.col("victim_side")).sort(
"duration", descending=True
)
item_events#
demo.item_events
Weapon-item transactions — purchases, pickups, and drops — one row each, with the acting player resolved.
Column |
Type |
Description |
|---|---|---|
|
i32 |
Tick the transaction occurred. |
|
str |
|
|
The acting player’s pawn identity. |
|
|
The acting player. |
|
|
str |
Short weapon name (e.g. |
|
f32? |
The player’s world position. |
|
u64? |
Steam id of the weapon’s original owner. For a |
|
i32? |
Money spent, for a |
|
bool? |
For a |
Awpy tracks each player’s inventory (m_hMyWeapons).
An acquired weapon is a purchase if money decreases on that tick; otherwise,
it is a pickup. A weapon left on the ground is a drop.
Thrown grenades, knives, and free default equipment are excluded.
Scope is weapon-type items (guns, pistols, grenades, C4, taser). Armor, helmet,
and defuser purchases are not included (they are pawn fields, not weapon
entities). Note that C4 pickups/drops also appear, in resolved form, in the
bomb dataset.
# Every player's buy on the pistol round
import polars as pl
r1 = demo.rounds.row(0, named=True)
demo.item_events.filter(
(pl.col("action") == "purchase")
& (pl.col("tick") >= r1["start_tick"])
& (pl.col("tick") <= r1["freeze_end_tick"])
).select("name", "item", "cost")
# Guns picked up off the ground (someone else's weapon)
demo.item_events.filter(
(pl.col("action") == "pickup")
& (pl.col("original_owner_steamid") != pl.col("steamid"))
)
stats#
demo.stats
One row per player, aggregating the kill / damage / round datasets into the
common scoreboard metrics. Columns: steamid, name, rounds_played, kills,
deaths, assists, flash_assists, headshot_kills, headshot_pct,
opening_kills, opening_deaths, traded_deaths, multikill_2k …
multikill_5k, kast, adr, clutches (clutches_played, clutches_won,
clutch_1v1 … clutch_1v5), plus utility: utility_damage, flashes_thrown,
enemies_flashed, flash_duration_dealt.
Assists include the kill event’s recorded assister and teammates with an active
blind on the victim at the kill. Each player counts once per kill. Flash assists
are a subset of assists. Several players can receive credit for one kill.
The kills table retains the event’s single recorded assister.
See Reference for metric definitions. KAST is the percentage of rounds with a kill, assist, survival, or traded death. ADR is the average enemy health removed per round.
Every player is treated as having played every round (the denominator for KAST and ADR is the match’s round count), so players who join or leave mid-match are approximate.
Knife rounds are excluded from counts and denominators by default.
Set include_knife_rounds=True to include them:
demo.stats # excludes knife rounds (default)
demo.player_stats(include_knife_rounds=True) # counts them
Both forms are cached. demo.stats and
demo.player_stats(include_knife_rounds=False) return the same cached default
result. The include_knife_rounds=True variant reuses the decoded combat and
round inputs, then caches its aggregated DataFrame separately.
# Top fraggers with KAST and ADR
demo.stats.sort("kills", descending=True).select("name", "kills", "kast", "adr")
# Clutch success rate
demo.stats.filter(pl.col("clutches_played") > 0).select(
"name", "clutches_won", "clutches_played",
rate=pl.col("clutches_won") / pl.col("clutches_played"),
).sort("rate", descending=True)
round_economy#
demo.round_economy
One row per (round, side), with equipment value at freeze end and buy type. Columns: round_num,
side, equipment_value, buy_type, n_players. buy_type is pistol / eco
/ force / full — see the Reference for the thresholds and
how pistol rounds are detected. (This is the current equipment at freeze end —
the finished buy; the equipment_value_round_start snapshot column is the pre-buy
carry-over.) Knife rounds are excluded.
# Full-buy rounds
demo.round_economy.filter(pl.col("buy_type") == "full")
players#
demo.players # steamid, name, side, team_clan_name
The roster: one row per player seen in the demo. side is the last team the
player was observed on (players swap at halftime); bots (e.g. the GOTV camera
controller) have steamid 0.
team_clan_name comes from CCSTeam entities and is null if not set.
It is recorded with side, so players who leave retain their last team name.
# Group a match's players by organization
demo.players.drop_nulls("team_clan_name").group_by("team_clan_name").agg("name")
# Join team names onto the scoreboard
demo.stats.join(
demo.players.select("steamid", "team_clan_name"), on="steamid", how="left"
).sort("kills", descending=True)
chat#
demo.chat # tick, entity_index, name, message, channel
Chat messages from SayText, SayText2, and SayTextChannel.
channel identifies the chat channel, such as Cstrike_Chat_All.
The DataFrame is empty if no supported chat messages are recorded.
The absence of chat entries in demo.events does not establish this:
user messages and game events are different streams.
convars#
demo.convars # -> dict[str, str]
demo.convars["mp_maxrounds"] # -> "24"
Server console variables collected from the demo stream — useful for round
math (mp_maxrounds, mp_freezetime, mp_overtime_enable) and for telling
match formats apart programmatically.
Game state: snapshots#
demo.snapshots(ticks=29000) # one moment
demo.snapshots(ticks=[29000, 30000, 31000]) # specific ticks
demo.snapshots(start_tick=29000, end_tick=30000) # every tick in a window
demo.snapshots(every=64) # every 64 ticks
demo.snapshots(seconds=1.0) # every second
demo.snapshots(events="player_death") # at each kill tick
demo.snapshots(every=64, start_tick=29000, end_tick=64000) # stride, bounded
Read a fixed schema of player position, aim, health, weapons, economy, and status.
Use ticks for other properties or non-player entities.
One row per active player per tick. Pass any combination of ticks (an int or a
list), a stride (every / seconds), events (a name or list), and a
start_tick / end_tick window — given on their own, the window is a contiguous
range; combined with a sampler, they bound it. At least one must be given.
Identity, position & movement: tick, steamid, name, side, x, y, z,
velocity_x, velocity_y, velocity_z, velocity, pitch, yaw.
Column |
Type |
Description |
|---|---|---|
|
f32? |
X velocity in Hammer units per second. |
|
f32? |
Y velocity in Hammer units per second. |
|
f32? |
Z velocity in Hammer units per second. |
|
f32? |
Three-dimensional speed derived from the velocity vector. |
|
i32 |
Hit points. |
|
i32 |
Armor value. |
|
bool |
Kevlar + helmet. |
|
bool |
Defuse kit. |
|
bool |
Carrying the C4. |
|
str? |
Short name of the weapon currently held. (Per-shot clip / accuracy is on |
|
str? |
Primary-slot weapon (rifle / SMG / shotgun / sniper / LMG), or null. |
|
str? |
Pistol held, or null. |
|
i32 |
Molotov + incendiary held. |
|
i32 |
Smoke grenades held. |
|
i32 |
HE grenades held. |
|
i32 |
Flashbangs held. |
|
i32 |
Decoy grenades held. |
|
i32 |
Value of current equipment ( |
|
i32 |
Equipment value at the round start. |
|
i32 |
Cash on hand. |
|
bool |
Fully ducked. |
|
bool |
Moving quietly. |
|
bool |
Airborne (off the ground). |
|
bool |
Standing in a plant zone. |
|
bool |
Scoped in. |
|
bool? |
Active weapon’s |
|
bool? |
True when the active weapon’s |
|
bool |
Defusing the bomb. |
|
bool |
Whether |
|
f32 |
Replicated duration set at flash onset. This is not a remaining-time counter. |
|
str |
Comma-separated short names of every weapon in the loadout, in slot order (e.g. |
Reload columns are nullable Boolean columns. Both are false when there is
no active weapon. A missing schema field on an active weapon produces null.
Older demos without m_bStealthy have null in is_silent_reloading when
a weapon is active. If the schema has a Boolean field but the demo omits its
value, the value defaults to false.
The silent-reload column reports stealth reload mode, not measured sound.
The mapping has synthetic tests but has not yet been checked against a
demo that contains quiet reloads.
See Reference or awpy.SNAPSHOT_PROPERTIES for engine properties.
Snapshot weapon names are short names, such as ak47 and usp_silencer.
Event weapon strings can differ.
Dead players have no weapons but retain their last equipment_value.
from awpy import plot
snap = demo.snapshots(ticks=29000)
players = [
plot.Player(x=r["x"], y=r["y"], z=r["z"], yaw=r["yaw"], hp=r["health"],
armor=r["armor"], side=r["side"], label=r["name"])
for r in snap.iter_rows(named=True)
]
fig, ax = plot.frame(demo.header["map_name"], players)
Requests for one to four explicit ticks, without other selectors, use seeking. Other requests decode keyframe segments in parallel. A coarse stride reduces output, but decoding can still be required between samples.
Any game event: demo.events#
For events without a dedicated dataset, demo.events maps event names to
DataFrames — a tick column plus one string column per event key. Everything
is parsed lazily and cached.
demo.events.names # what the demo contains
demo.events.counts # {name: occurrences}
demo.events.bomb_planted # one event as a DataFrame
demo.events["smokegrenade_detonate"]
The Reference catalogs the common events (also
awpy.GAME_EVENTS).
Per-tick entity state: ticks#
demo.ticks() # default props (below)
demo.ticks(["X", "Y", "Z", "health"]) # friendly aliases
demo.ticks(["m_iHealth", "m_iTeamNum"]) # raw CS2 field names
Use ticks for a selected set of network properties or for non-player entities.
For example, demo.ticks(["velocity_x", "velocity_y", "velocity_z", "velocity"])
returns velocity components and derived speed without the full snapshot schema.
With players_only=True (the default) there is one row per player per tick,
keyed by steamid: each player’s pawn and controller are merged into a single
row, and every requested property is read from whichever of the two carries it
(so pawn fields like health and controller fields like name mix freely).
Columns: tick, steamid, then one column per requested property, each typed
natively — integers → Int64, floats → Float64, booleans → Boolean, strings →
Utf8.
The default props are ["X", "Y", "Z", "health", "armor", "team_num"].
Use aliases or raw CS2 network names:
Alias |
Meaning |
|---|---|
|
Computed world position (from cell + offset). |
|
|
|
|
|
|
|
|
|
|
|
Networked velocity components. Short aliases |
|
Derived three-dimensional speed. |
(anything else) |
Used verbatim as a raw network field name. |
ticks() decodes keyframe segments in parallel.
Set players_only=False for a raw per-entity dump instead — one row per (tick,
entity), with columns tick, entity_id, entity_serial,
class_name, then the requested properties. Use (entity_id, entity_serial)
as the stable identity because Source 2 can reuse an entity slot.