API reference#

This page uses the installed package docstrings. See Datasets for columns and Reference for definitions.

Demo#

Open a demo and read datasets as Polars DataFrames. Construction maps the file and checks its header. Dataset access triggers decoding. Results are cached; Demo.load(...) combines compatible requests.

class awpy.Demo(path)#

Bases: object

A parsed Counter-Strike 2 demo file.

Parameters:

path – Path to the .dem file.

Raises:
  • FileNotFoundError – If the file does not exist.

  • InvalidDemoError – If the file is not a valid CS2 demo.

static available_datasets()#

Dataset names accepted by [load](Self::load).

blinds#

one row per player blinded.

Reconstructed from pawn flash state and flashbang_detonate (so it works even on GOTV demos, which omit the player_blind event). Columns: tick, the resolved attacker_* (thrower) and victim_* (blinded player) steamid / name / side / x / y / z, and duration (blind seconds).

Type:

Flash events as a DataFrame (cached)

bomb#

Bomb actions (pickup / drop / plant / defuse) as a DataFrame (cached).

chat#

Chat messages as a DataFrame (cached).

Decoded from SayText, SayText2, and SayTextChannel. Columns: tick, entity_index (the sender’s controller slot), name, message, and channel (e.g. Cstrike_Chat_All for all-chat, Cstrike_Chat_T / Cstrike_Chat_CT for team chat).

convars#

Server console variables, as a {name: value} dict (cached).

Collected from the demo’s net_SetConVar messages; when a convar is set more than once, the last value wins.

damages#

Every damage instance (player_hurt event) as a DataFrame, all fields (cached).

events#

Cached game events, indexed by name.

Use demo.events.names to list names and demo.events[name] or attribute access to read a cached DataFrame:

demo.events.player_death
demo.events["player_ping"]
fires#

Burning infernos (one row per fire, with its [start_tick, end_tick]; cached).

grenades#

Thrown-grenade trajectories (one row per tick each grenade is live; cached).

header#

The demo file header and playback info as a dict.

item_events#

purchases, pickups, and drops, reconstructed from inventory state (so they work on demos that omit the item_purchase event). Columns: tick, action (purchase / pickup / drop), steamid / name / side, item, x / y / z, original_owner_steamid, cost (purchases), and near_buy_zone (drops).

Type:

Weapon-item transactions as a DataFrame (cached)

kills#

Cached player_death events with resolved participants.

is_trade marks a kill that avenges a teammate within 5.25 seconds. victim_traded marks the earlier death; stats count it as traded_deaths. Each kill trades only the earliest qualifying death. A kill can have both flags.

load(*datasets)#

Load and cache the named DataFrames.

Compatible event requests share one pass, as do projectile requests. Stats reuse combat, round, and roster inputs. A combined stats request can also collect bomb and shot rows. Cached datasets are skipped.

Raises:

ValueError – If any dataset name is unknown, before loading begins.

path#
player_stats(include_knife_rounds=False)#

Read player statistics with optional knife rounds.

Set include_knife_rounds=True to include rounds marked is_knife_round. Both variants reuse decoded inputs and cache their DataFrames. The default returns the same cached object as stats.

players#

Cached roster with one row per observed player.

Columns: steamid, name, side, and team_clan_name. Bots have Steam ID 0. Side and team name are the last observed values. Team names come from CCSTeam and are null when not set.

round_economy#

Per-team economy and buy type per round (cached).

One row per (round, side): round_num, side, equipment_value (team total at freeze end), buy_type (pistol / eco / force / full), and n_players.

rounds#

Per-round information as a DataFrame (cached).

One row per round with round_num, start_tick, freeze_end_tick, end_tick, winner (team number), winner_side, reason, and reason_name. Reconstructed from CCSGameRules state, so it works on demos without round_start / round_end events.

seconds_to_tick(seconds)#

Convert seconds from the start of the demo to the nearest demo tick.

Negative values are valid for demos whose first packet has a negative tick. The value must be finite and fit in a signed 32-bit tick.

shots#

Shots (weapon_fire events) with shooter and weapon state (cached).

Built in the same single pass as kills / damages / bomb / blinds.

smokes#

Deployed smoke clouds (one row per smoke, with its [start_tick, end_tick]; cached).

snapshots(*, ticks=None, every=None, seconds=None, events=None, start_tick=None, end_tick=None)#

Read player state at selected ticks as a DataFrame.

Return one row per active player per tick. See awpy.SNAPSHOT_PROPERTIES for the schema. Select ticks with:

  • ticks: one tick or a list.

  • every or seconds: a stride in ticks or seconds. Do not set both.

  • events: ticks with a named game event, or a list of event names.

  • start_tick and end_tick: an inclusive window. Alone, this selects every tick in the window. With other selectors, it bounds the selection.

At least one selector is required. One to four explicit ticks without other selectors use keyframe seeks. Other requests decode keyframe segments in parallel. Results are not cached.

Examples:

demo.snapshots(ticks=[29000, 30000])
demo.snapshots(seconds=1, start_tick=0, end_tick=64000)
demo.snapshots(events="player_death")
stats#

Cached match statistics, with one row per player.

Knife rounds are excluded. Includes kills, deaths, assists, headshots, openings, trades, multikills, KAST, ADR, clutches, and utility. clutch_1v1 through clutch_1v5 count wins by the opponent count when the clutch started. Their sum is clutches_won. See the dataset and reference guides for columns and definitions.

tick_rate#

Ticks per second, from playback_ticks / playback_time.

Returns 64.0 when playback timing is unavailable.

tick_to_seconds(tick)#

Convert a demo tick to seconds from the start of the demo.

ticks(props=None, players_only=True)#

Read selected entity properties at every tick.

With players_only=True, merge each player pawn and controller into one row per tick. Columns are tick, steamid, and the requested properties. Only player pawns and controllers are decoded.

With players_only=False, return one row per entity per tick. Identity columns are tick, entity_id, entity_serial, and class_name. Use the id and serial together as the entity identity.

Property types are inferred: Int64, Float64, Boolean, or Utf8. Mixed integer and float values use Float64. Names can be raw network fields or aliases: X, Y, Z, velocity_x, velocity_y, velocity_z, velocity (3D speed), health, armor, team_num, name, and money.

Each call decodes keyframe segments in parallel. Results are not cached.

Parameters:
  • props – Property names. Defaults to ["X", "Y", "Z", "health", "armor", "team_num"].

  • players_only – Merge player entities if true; otherwise, return all entities.

Events#

Read game events by name when no dedicated dataset is available.

class awpy._awpy.Events#

Bases: object

A demo’s game events, keyed by name. Returned by Demo.events.

Behaves like a read-only mapping from event name to DataFrame: iterating yields the (sorted) event names, in tests membership, and indexing or attribute access parses one event:

demo.events.names            # every event name in the demo
demo.events.counts           # {name: occurrences}
demo.events.player_death     # -> DataFrame
demo.events["player_ping"]   # -> DataFrame

Each frame has a tick column plus one string column per event key (e.g. attacker, weapon, headshot for player_death), is built on first access, and is cached.

__contains__(key, /)#

Return bool(key in self).

__getitem__(key, /)#

Return self[key].

__iter__()#

Implement iter(self).

__len__()#

Return len(self).

counts#

Occurrence counts, as a {event_name: count} dict.

names#

The event names present in the demo, sorted.

VisibilityChecker#

Check lines of sight against static collision geometry. Reuse the checker to avoid rebuilding its spatial index. See Visibility & map data.

class awpy.VisibilityChecker(source, *, version=None)#

Bases: object

Line-of-sight visibility over a map’s collision geometry.

Answers whether the straight segment between two world points is unobstructed, using the compact .mesh files published by awpy-data. Construct it from either a map name or a mesh file:

  • VisibilityChecker("de_inferno") — newest release cached under ~/.awpy (the latest release is downloaded if the cache is empty);

  • VisibilityChecker("de_inferno", version=2000873) — a pinned awpy-data release, downloaded on demand;

  • VisibilityChecker("path/to/de_inferno.mesh") — a specific file. Strings count as paths when they end in .mesh or contain a path separator; pathlib.Path objects always do.

A bounding-volume hierarchy is built once at construction, so each query is fast; reuse a single checker for many queries.

Coordinates are Hammer units, Z-up — the same frame as demo world positions (e.g. the *_x / *_y / *_z columns of Demo.kills()), so you can pass entity positions in directly.

Parameters:
  • source – Map name (e.g. "de_inferno") or path to a .mesh file.

  • version – awpy-data release to use when source is a map name — an integer ClientVersion (e.g. 2000873); defaults to the newest cached release.

Raises:
  • FileNotFoundError – If the file does not exist, or the release has no mesh for the map.

  • ValueError – If the file is not a valid awpy mesh, or version is combined with a file path.

Example

>>> from awpy import VisibilityChecker
>>> vc = VisibilityChecker("de_inferno")
>>> vc.is_visible((1258.04, 455.47, 181.22), (-158.62, 819.09, 103.73))
True
is_occluded(a, b)#

Does any triangle block the segment from a to b?

The complement of is_visible().

is_visible(a, b)#

Is the straight segment from a to b clear of geometry?

Parameters:
  • a – Start point (x, y, z) in Hammer units.

  • b – End point (x, y, z) in Hammer units.

Returns:

True if nothing blocks the line between the two points.

path#
triangle_count#

Number of triangles in the loaded mesh.

awpy.map_control#

Calculate map control from a demo. See Map control.

Estimate map control from player snapshots.

Models:

  • raycast: line of sight in any direction.

  • vision: line of sight within the horizontal field of view.

  • reachability: shortest travel distance over the nav graph.

Smokes block rays. Blinded players do not contribute to line-of-sight models. Fires block travel paths. Results estimate control, not exact player perception.

Use map_control() for a time series or map_control_at() for per-area labels. Assets are supplied by awpy.data.

awpy.map_control.LINE_OF_SIGHT_METHODS: frozenset[str] = frozenset({'raycast', 'vision'})#

Methods that cast rays through the collision mesh, and so need a VisibilityChecker.

class awpy.map_control.MapControlParams(eye_height: float = 64.0, crouch_eye_height: float = 46.0, target_height: float = 46.0, max_distance: float | None = None, contest_margin: float = 200.0, fov: float = 90.0, smoke_radius: float = 144.0, smoke_height: float = 60.0, fire_radius: float = 150.0, flash_threshold: float = 1.0)#

Bases: object

Map-control parameters. Distances use Hammer units.

Variables:
  • eye_height (float) – Standing eye height above the feet — where vision rays start.

  • crouch_eye_height (float) – Eye height when crouched.

  • target_height (float) – Ray endpoint height above each area’s floor.

  • max_distance (float | None) – Optional cap on vision range; None is unbounded.

  • contest_margin (float) – Travel-distance tie band — areas whose two sides’ travel distances differ by no more than this are contested.

  • fov (float) – Horizontal field of view in degrees for method="vision" — an area counts only within fov / 2 either side of where the player looks. 360 or more removes the limit.

  • smoke_radius (float) – Radius of a smoke cloud that blocks vision.

  • smoke_height (float) – How far above its landing point a smoke’s blocking sphere is centred.

  • fire_radius (float) – Radius around a molotov within which the ground is denied.

  • flash_threshold (float) – A currently flashing player projects no vision when the replicated flash duration is greater than this value. This filters out short partial flashes.

eye_height: float = 64.0#
crouch_eye_height: float = 46.0#
target_height: float = 46.0#
max_distance: float | None = None#
contest_margin: float = 200.0#
fov: float = 90.0#
smoke_radius: float = 144.0#
smoke_height: float = 60.0#
fire_radius: float = 150.0#
flash_threshold: float = 1.0#
awpy.map_control.map_control(demo: Demo, *, method: Method = 'vision', ticks: int | list[int] | None = None, every: int | None = None, seconds: float | None = None, events: str | list[str] | None = None, start_tick: int | None = None, end_tick: int | None = None, params: MapControlParams | None = None, map_name: str | None = None, version: int | None = None) → pl.DataFrame#

Map-control summary over time: one row of fractions per selected tick.

Ticks are chosen exactly as in awpy.Demo.snapshots() — pass any of ticks / every / seconds / events / start_tick / end_tick. Use a coarse stride (for example, seconds=1) or event ticks to reduce computation.

Parameters:
  • demo – The parsed demo.

  • method – "raycast", "vision", or "reachability" (see the module docs).

  • ticks – Tick selection, forwarded to awpy.Demo.snapshots().

  • every – Tick selection, forwarded to awpy.Demo.snapshots().

  • seconds – Tick selection, forwarded to awpy.Demo.snapshots().

  • events – Tick selection, forwarded to awpy.Demo.snapshots().

  • start_tick – Tick selection, forwarded to awpy.Demo.snapshots().

  • end_tick – Tick selection, forwarded to awpy.Demo.snapshots().

  • params – Model parameters (defaults if omitted).

  • map_name – Override the map (defaults to the demo header’s map).

  • version – awpy-data release for the nav/mesh assets (default: newest cached).

Returns:

A DataFrame with columns tick, method, ct, t, contested, neutral, net_control — the last five being the size-weighted fraction of the map in each bucket (ct/t/ contested/neutral sum to 1), and net_control = ct - t.

awpy.map_control.map_control_at(demo: Demo, tick: int, *, method: Method = 'vision', params: MapControlParams | None = None, map_name: str | None = None, version: int | None = None) → pl.DataFrame#

Per-area map control at a single tick.

Parameters:
  • demo – The parsed demo.

  • tick – The tick to evaluate.

  • method – "raycast", "vision", or "reachability" (see the module docs).

  • params – Model parameters (defaults if omitted).

  • map_name – Override the map (defaults to the demo header’s map).

  • version – awpy-data release for the nav/mesh assets.

Returns:

One row per nav area, with area_id, control ("ct" / "t" / "contested" / "neutral"), ct / t (does that side hold it, alone or contested), and the area’s centroid_x / centroid_y / centroid_z / size (joined from the nav mesh) for plotting.

compute_map_control#

Calculate map control from a nav mesh and player positions.

awpy._awpy.compute_map_control(nav, players, *, visibility=None, method='vision', smokes=[], fires=[], detail=True, eye_height=64.0, crouch_eye_height=46.0, target_height=46.0, max_distance=None, contest_margin=200.0, fov=90.0)#

Compute one snapshot’s map control over a nav mesh.

The low-level primitive behind awpy.map_control.map_control(). Given player positions and (for vision) a VisibilityChecker, it labels every nav area "ct" / "t" / "contested" / "neutral" and returns size-weighted summary fractions.

Parameters:
  • nav – The map’s NavMesh.

  • players – Sequence of (x, y, z, side, crouched, blind, yaw) for the living players at the tick. yaw is the eye-angle yaw in degrees and may be None; only method="vision" reads it, and a player with no yaw is left unrestricted.

  • visibility – The map’s VisibilityChecker; required for method="vision" and method="raycast".

  • method – "raycast" (line of sight in any direction, smoke-aware), "vision" (the same, narrowed to each player’s field of view), or "reachability" (who reaches each area first, fire-aware).

  • smokes – Active smoke spheres (x, y, z, radius) (vision only).

  • fires – Active inferno spheres (x, y, z, radius) (reachability only).

  • detail – When True (default) include the per-area arrays; when False return only the summary fractions.

  • eye_height – Standing eye height above the feet, where vision rays start.

  • crouch_eye_height – Eye height when crouched.

  • target_height – Height above an area’s floor that vision aims at.

  • max_distance – Optional cap on vision range; None is unbounded.

  • contest_margin – Reachability travel-distance tie band.

  • fov – Horizontal field of view in degrees for method="vision" (default 90.0, CS2’s own FOV); 360.0 or more removes the limit, making it equivalent to "raycast". See awpy.map_control.MapControlParams for all six.

Returns:

A dict with ct_fraction, t_fraction, contested_fraction, neutral_fraction, net_control, and (when detail) the area_ids / control / ct / t per-area lists.

awpy.plot#

Radar rendering, game-state frames, heatmaps, and GIFs. Requires the plot extra — pip install 'awpy[plot]'. See Plotting.

Plot CS2 demo data on radar images.

Use radar images from awpy.data. Set version= to select a release; otherwise, use the newest cached release. Install dependencies with pip install 'awpy[plot]'.

Draw players and the bomb:

from awpy import plot

players = [
    plot.Player(x=-158.6, y=819.1, z=103.7, side="ct", hp=87, label="ct1"),
    plot.Player(x=1258.0, y=455.5, z=181.2, side="t", yaw=135.0),
]
fig, ax = plot.frame("de_inferno", players, bomb=(200.0, 480.0, 90.0))
fig.savefig("frame.png")

Heatmap of demo positions (any (x, y, z) rows — e.g. death locations):

from awpy import Demo, plot

kills = Demo("match.dem").kills
deaths = kills.select(["victim_x", "victim_y", "victim_z"]).rows()
fig, ax = plot.heatmap("de_inferno", deaths, method="kde")

Use radar() and pass its ax to other functions to combine plots. world_to_pixel() and pixel_to_world() convert coordinates.

For multi-level maps, set lower=True to draw the lower radar. frame_levels() and heatmap_levels() draw one panel per level:

fig, (upper, lower) = plot.frame_levels("de_nuke", players, bomb=bomb)
awpy.plot.CONTESTED_COLOR = '#A855F7'#

Fill color for map-control areas held by both sides at once (see map_control()).

awpy.plot.NAV_COLOR = '#F5A524'#

Fill color for nav areas drawn by nav() — a muted amber that reads as “the walkable surface” without competing with the radar underneath.

awpy.plot.NAV_HIGHLIGHT_COLOR = '#22D3EE'#

Fill color for the areas passed as highlight to nav().

awpy.plot.RADAR_SIZE = 1024#

Side length, in pixels, of the awpy-data radar images.

awpy.plot.SMOKE_RADIUS = 144.0#

World-unit radii of a deployed smoke cloud and a molotov/incendiary fire.

awpy.plot.T_COLOR = '#EAB308'#

Default marker colors, keyed off Player.side.

class awpy.plot.Player(x: float, y: float, z: float = 0.0, side: str | None = None, hp: int | None = None, armor: int | None = None, yaw: float | None = None, label: str | None = None, color: str | None = None, has_bomb: bool = False)#

Bases: object

Render state for one player in a frame().

Only x/y are required. side picks the marker color ("t" / "ct", or the demo dataframes’ "terrorist" / "counter-terrorist", any case); hp=0 draws the player as dead (a dim cross); yaw (degrees, 0 = +x, counter-clockwise) draws a view-direction tick; hp/armor draw bars under the marker; label prints below; has_bomb gives the marker a red border (the player carrying the bomb).

x: float#
y: float#
z: float = 0.0#
side: str | None = None#
hp: int | None = None#
armor: int | None = None#
yaw: float | None = None#
label: str | None = None#
color: str | None = None#
has_bomb: bool = False#
awpy.plot.frame(map_name: str, players: Iterable[Player], *, bomb: Sequence[float] | None = None, bomb_planted: bool = False, smokes: Iterable[Sequence[float]] | None = None, fires: Iterable[Sequence[float]] | None = None, grenades: Iterable[Sequence[float] | Mapping[str, Any]] | None = None, smoke_radius: float = 144.0, fire_radius: float = 150.0, version: int | None = None, lower: bool = False, off_level_alpha: float = 0.3, ax: Axes | None = None) → tuple[Figure, Axes]#

Plot one game-state frame: players, bomb, smokes, fires and grenade paths.

Parameters:
  • map_name – Map to draw, e.g. "de_inferno".

  • players – A Player per player to draw. Set has_bomb on the carrier to give its marker a red border.

  • bomb – World (x, y, z) of the bomb, drawn as an orange diamond.

  • bomb_planted – Give the bomb a green border to mark it planted and ticking.

  • smokes – World (x, y[, z]) centers of active smoke clouds, each drawn as a translucent grey disc of smoke_radius world units.

  • fires – World (x, y[, z]) origins of burning infernos (molotov / incendiary), each drawn as a translucent orange disc of fire_radius world units.

  • grenades – Live grenade projectiles, each drawn as a small circle at its current position. An entry is either a world (x, y[, z]) position, or a dict carrying the position (pos, or x/y/ z keys — a Demo.grenades row) plus an optional type (e.g. "smoke", "molotov", "he") that colors it, or an explicit color. Pass only in-flight grenades (filter the row to the frame’s tick): a projectile’s rows end when it detonates, so the grenade naturally disappears as its smoke or inferno appears.

  • smoke_radius – Smoke-cloud radius in world units (default ~144).

  • fire_radius – Inferno radius in world units (default ~150).

  • version – awpy-data release to use (default: newest cached).

  • lower – Draw the lower-level radar of a multi-level map.

  • off_level_alpha – Opacity for markers whose altitude is on the other level of a multi-level map; 0 hides them entirely.

  • ax – Draw onto an existing axes instead of creating a new figure.

Returns:

The matplotlib (Figure, Axes).

awpy.plot.frame_levels(map_name: str, players: Iterable[Player], *, bomb: Sequence[float] | None = None, bomb_planted: bool = False, version: int | None = None) → tuple[Figure, tuple[Axes, ...]]#

Plot a game-state frame with one radar panel per vertical level.

On a multi-level map (Nuke, Vertigo, Train, Baggage) this returns two panels — upper and lower — with every player and the bomb drawn at full opacity on the panel matching their altitude. On a single-level map it degrades to one panel, so callers never need to special-case the map.

Parameters:
  • map_name – Map to draw, e.g. "de_nuke".

  • players – A Player per player to draw. Set has_bomb on the carrier to give its marker a red border.

  • bomb – World (x, y, z) of the bomb, drawn as an orange diamond.

  • bomb_planted – Give the bomb a green border to mark it planted and ticking.

  • version – awpy-data release to use (default: newest cached).

Returns:

The matplotlib (Figure, (Axes, ...)) — (upper, lower) panels, or a 1-tuple for single-level maps.

awpy.plot.gif(map_name: str, frames: Sequence[Iterable[Player] | dict], path: str, *, fps: int = 2, version: int | None = None, lower: bool = False, dpi: int = 150) → None#

Render a sequence of frame() calls to an animated GIF.

Parameters:
  • map_name – Map to draw, e.g. "de_inferno".

  • frames – One entry per GIF frame — either an iterable of Player, or a dict of frame() keyword arguments (e.g. {"players": [...], "bomb": (x, y, z)}).

  • path – Output .gif file path.

  • fps – Frames per second.

  • version – awpy-data release to use (default: newest cached).

  • lower – Draw the lower-level radar of a multi-level map.

  • dpi – Render resolution (150 → a 512px GIF).

awpy.plot.has_lower_level(map_name: str, *, version: int | None = None) → bool#

Does the map have a lower vertical level (and a _lower radar)?

awpy.plot.heatmap(map_name: str, points: Iterable[Sequence[float]], *, method: Literal['hex', 'hist', 'kde'] = 'hex', bins: int = 48, cmap: str = 'magma', alpha: float = 0.8, bandwidth: float = 16.0, version: int | None = None, lower: bool = False, ax: Axes | None = None) → tuple[Figure, Axes]#

Plot a density heatmap of world positions over the radar.

Parameters:
  • map_name – Map to draw, e.g. "de_inferno".

  • points – World positions — (x, y) or (x, y, z) rows, e.g. kills.select(["victim_x", "victim_y", "victim_z"]).rows().

  • method – "hex" (hexagonal binning), "hist" (square binning), or "kde" (gaussian-smoothed density).

  • bins – Grid resolution — hexagons across the radar for hex, cells per side for hist. (kde evaluates on a fixed fine grid.)

  • cmap – Matplotlib colormap name.

  • alpha – Overlay opacity.

  • bandwidth – kde smoothing radius, in radar pixels.

  • version – awpy-data release to use (default: newest cached).

  • lower – Draw the lower-level radar; only points at lower-level altitudes are included (and vice versa for the upper radar — off-level points are skipped with a warning).

  • ax – Draw onto an existing axes instead of creating a new figure.

Returns:

The matplotlib (Figure, Axes).

Raises:

ValueError – On an unknown method.

awpy.plot.heatmap_levels(map_name: str, points: Iterable[Sequence[float]], *, method: Literal['hex', 'hist', 'kde'] = 'hex', bins: int = 48, cmap: str = 'magma', alpha: float = 0.8, bandwidth: float = 16.0, version: int | None = None) → tuple[Figure, tuple[Axes, ...]]#

Plot a density heatmap with one radar panel per vertical level.

The multi-panel counterpart of heatmap(): on a multi-level map every point lands on the panel matching its altitude (no points are skipped); on a single-level map it degrades to one panel. Arguments are those of heatmap().

Returns:

The matplotlib (Figure, (Axes, ...)) — (upper, lower) panels, or a 1-tuple for single-level maps.

awpy.plot.is_lower_level(map_name: str, z: float, *, version: int | None = None) → bool#

Is altitude z in the map’s lower vertical section?

Multi-level maps (Nuke, Vertigo, Train, Baggage) publish altitude bands in map_data.json; single-level maps have none, so this returns False.

awpy.plot.map_control(demo: Demo, tick: int, *, method: Literal['raycast', 'vision', 'reachability'] = 'vision', params: MapControlParams | None = None, players: bool = True, occluders: bool = True, legend: bool = True, alpha: float = 0.5, version: int | None = None, map_name: str | None = None, lower: bool = False, ax: Axes | None = None) → tuple[Figure, Axes]#

Shade the map by which side controls each area at one tick.

Computes awpy.map_control.map_control_at() for the tick and fills every nav area with its controlling side’s color — blue (CT), yellow (T), purple (contested) — leaving neutral areas unshaded. The players are overlaid, along with the occluders that shaped the picture (smokes for the line-of-sight models, molotovs for "reachability").

Parameters:
  • demo – The parsed demo.

  • tick – The tick to draw.

  • method – "raycast", "vision", or "reachability" (see awpy.map_control).

  • params – Model parameters (defaults if omitted).

  • players – Overlay the players at the tick.

  • occluders – Draw the active smokes (vision) or fires (reachability).

  • legend – Draw a legend with each side’s share of the map.

  • alpha – Opacity of the area shading.

  • version – awpy-data release to use (default: newest cached).

  • map_name – Override the map (defaults to the demo header’s map).

  • lower – Draw the lower-level radar of a multi-level map.

  • ax – Draw onto an existing axes instead of creating a new figure.

Returns:

The matplotlib (Figure, Axes).

awpy.plot.nav(map_name: str, *, highlight: Sequence[int] | None = None, version: int | None = None, lower: bool = False, alpha: float = 0.25, edge: bool = True, legend: bool = True, ax: Axes | None = None) → tuple[Figure, Axes]#

Draw a map’s navigation mesh over its radar image.

Fills every walkable area from the map’s awpy.NavMesh, outlined so the tiling is visible. Useful for seeing what the bot navigation actually covers — and, with highlight, for showing a route across it.

Parameters:
  • map_name – Map to draw, e.g. "de_dust2".

  • highlight – Area ids to emphasize in a contrasting color, drawn above the rest. Pass the result of awpy.NavMesh.find_path() to show a route.

  • version – awpy-data release to use (default: newest cached).

  • lower – Draw the lower-level radar of a multi-level map. Areas are filtered to the level being drawn, so a two-level map needs one call per level (or use frame_levels()-style side-by-side axes).

  • alpha – Fill opacity of the areas.

  • edge – Outline each area, which is what makes the mesh legible as a mesh.

  • legend – Label the area count (and highlighted count, if any).

  • ax – Draw onto an existing axes instead of creating a new figure.

Returns:

The matplotlib (Figure, Axes).

Example

>>> from awpy import NavMesh
>>> from awpy.plot import nav
>>> fig, ax = nav("de_dust2")
>>> mesh = NavMesh("de_dust2")
>>> route = mesh.find_path((-680.0, 1500.0, 0.0), (1200.0, 2400.0, 0.0))
>>> fig, ax = nav("de_dust2", highlight=route)
awpy.plot.pixel_to_world(map_name: str, point: Sequence[float], *, version: int | None = None) → tuple[float, float]#

Convert a radar-pixel (px, py) back to a world (x, y) position.

awpy.plot.radar(map_name: str, *, version: int | None = None, lower: bool = False, ax: Axes | None = None) → tuple[Figure, Axes]#

Draw a map’s radar image — the canvas every other function draws onto.

Parameters:
  • map_name – Map to draw, e.g. "de_inferno".

  • version – awpy-data release to use (default: newest cached).

  • lower – Draw the lower-level radar of a multi-level map.

  • ax – Draw onto an existing axes instead of creating a new figure.

Returns:

The matplotlib (Figure, Axes), axis off, one radar pixel per data unit.

awpy.plot.world_to_pixel(map_name: str, point: Sequence[float], *, version: int | None = None) → tuple[float, float]#

Convert a world (x, y, ...) position to radar-pixel (px, py).

Pixel coordinates have the origin at the radar’s top-left corner, with py growing downward (matplotlib image convention).

awpy.data#

Download and cache awpy-data assets under ~/.awpy/<version>/. Set AWPY_DATA_DIR to change the root path. Accessors use the newest cached release unless version= is set. See Visibility & map data.

Download and cache versioned CS2 assets from awpy-data.

Assets include collision meshes, nav meshes, radar images, and coordinate tables. The cache is ~/.awpy/<ClientVersion>/. Set AWPY_DATA_DIR to change its root.

Path helpers download missing assets and return local paths. Set version= to select a release. Otherwise, use the newest cached release, or the latest release if the cache is empty. Use update() or awpy get to check for updates.

awpy.data.AWPY_DATA_DIR = PosixPath('/home/docs/.awpy')#

Root of the local asset cache. Read at call time, so tests (or callers) may reassign awpy.data.AWPY_DATA_DIR to redirect the cache.

awpy.data.DATA_REPO = 'pnxenopoulos/awpy-data'#

GitHub repository the assets are published from.

awpy.data.available_maps(version: int | None = None) → list[str]#

Map names shipped in a release (from the manifest’s maps list).

awpy.data.clear(version: int | None = None) → None#

Delete cached assets — one release, or the whole cache if version is None.

awpy.data.data_dir(version: int | None = None) → Path#

Return a release directory; default to the newest cached or latest release.

awpy.data.latest_version() → str#

Return the tag of the most recent awpy-data release (a ClientVersion).

Queries the GitHub API (once per process; the result is cached). Raises on a network or API failure.

awpy.data.local_versions() → list[str]#

Version directories already present in the cache, oldest first.

awpy.data.manifest(version: int | None = None) → dict#

The release manifest (version identifiers + per-file checksums) as a dict.

awpy.data.map_data(version: int | None = None) → dict#

The per-map world→radar coordinate table (map_data.json) as a dict.

awpy.data.mesh_path(map_name: str, version: int | None = None) → Path#

Local path to a map’s collision .mesh (for VisibilityChecker).

awpy.data.nav_path(map_name: str, version: int | None = None) → Path#

Local path to a map’s .nav mesh.

awpy.data.radar_path(map_name: str, version: int | None = None, *, lower: bool = False) → Path#

Local path to a map’s radar .png.

Set lower=True for the lower level of a multi-level map (Nuke, Vertigo, Train).

awpy.data.resolve_version(version: int | None = None) → str#

Resolve version to a concrete release tag.

A given version is returned as-is (stringified). None resolves to the newest release already in the cache — no network involved — so pinned analyses keep working offline and don’t shift under you mid-session. Only an empty cache falls through to the latest GitHub release. Move the cache forward explicitly with update() (or awpy get).

awpy.data.update(version: int | None = None, *, force: bool = False) → Path#

Download every asset for a release into the cache; return its directory.

Unlike the read helpers, version=None here means the latest GitHub release — this is the “check for updates” entry point — not the newest cached one. With force=True, re-download even if already cached.

awpy.schema#

List snapshot properties and common game events without parsing a demo. Both catalogs are also available from awpy. Use demo.events.names for the events in a specific demo.

awpy.schema.SNAPSHOT_PROPERTIES: dict[str, str]#

Per-player snapshot feature name -> the CS2 network property it is read from.

Every key is a column of Demo.snapshots() (besides tick), and the value is the engine property — or the derivation, for computed ones like world position. The direct fields (health, money, the is_* flags, …) can also be passed to Demo.ticks(), either by these readable names or by their raw network names.

awpy.schema.GAME_EVENTS: dict[str, str]#

Common CS2 game event name -> a one-line description of what it means.

Not exhaustive: a demo may carry events that are not listed here. For what a particular demo contains, use demo.events.names (or demo.events.counts), and demo.events[name] to pull any of them as a DataFrame.

Exceptions#

exception awpy.InvalidDemoError#

Bases: Exception