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:
objectA parsed Counter-Strike 2 demo file.
- Parameters:
path – Path to the
.demfile.- 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 theplayer_blindevent). Columns:tick, the resolvedattacker_*(thrower) andvictim_*(blinded player)steamid/name/side/x/y/z, andduration(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, andSayTextChannel. Columns:tick,entity_index(the sender’s controller slot),name,message, andchannel(e.g.Cstrike_Chat_Allfor all-chat,Cstrike_Chat_T/Cstrike_Chat_CTfor team chat).
- convars#
Server console variables, as a
{name: value}dict (cached).Collected from the demo’s
net_SetConVarmessages; when a convar is set more than once, the last value wins.
- damages#
Every damage instance (
player_hurtevent) as a DataFrame, all fields (cached).
- events#
Cached game events, indexed by name.
Use
demo.events.namesto list names anddemo.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_purchaseevent). Columns:tick,action(purchase/pickup/drop),steamid/name/side,item,x/y/z,original_owner_steamid,cost(purchases), andnear_buy_zone(drops).- Type:
Weapon-item transactions as a DataFrame (cached)
- kills#
Cached
player_deathevents with resolved participants.is_trademarks a kill that avenges a teammate within 5.25 seconds.victim_tradedmarks the earlier death; stats count it astraded_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=Trueto include rounds markedis_knife_round. Both variants reuse decoded inputs and cache their DataFrames. The default returns the same cached object asstats.
- players#
Cached roster with one row per observed player.
Columns:
steamid,name,side, andteam_clan_name. Bots have Steam ID 0. Side and team name are the last observed values. Team names come fromCCSTeamand 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), andn_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, andreason_name. Reconstructed fromCCSGameRulesstate, so it works on demos withoutround_start/round_endevents.
- 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_fireevents) 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_PROPERTIESfor the schema. Select ticks with:ticks: one tick or a list.everyorseconds: a stride in ticks or seconds. Do not set both.events: ticks with a named game event, or a list of event names.start_tickandend_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_1v1throughclutch_1v5count wins by the opponent count when the clutch started. Their sum isclutches_won. See the dataset and reference guides for columns and definitions.
- tick_rate#
Ticks per second, from
playback_ticks / playback_time.Returns
64.0when 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 aretick,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 aretick,entity_id,entity_serial, andclass_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, andmoney.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:
objectA 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,
intests 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
tickcolumn plus one string column per event key (e.g.attacker,weapon,headshotforplayer_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:
objectLine-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 pinnedawpy-datarelease, downloaded on demand;VisibilityChecker("path/to/de_inferno.mesh")— a specific file. Strings count as paths when they end in.meshor contain a path separator;pathlib.Pathobjects 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/*_zcolumns ofDemo.kills()), so you can pass entity positions in directly.- Parameters:
source – Map name (e.g.
"de_inferno") or path to a.meshfile.version –
awpy-datarelease to use whensourceis 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
versionis 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
atob?The complement of
is_visible().
- is_visible(a, b)#
Is the straight segment from
atobclear of geometry?- Parameters:
a – Start point
(x, y, z)in Hammer units.b – End point
(x, y, z)in Hammer units.
- Returns:
Trueif 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:
objectMap-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;
Noneis 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 withinfov / 2either side of where the player looks.360or 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 ofticks/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/neutralsum to 1), andnet_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’scentroid_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) aVisibilityChecker, 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.yawis the eye-angle yaw in degrees and may beNone; onlymethod="vision"reads it, and a player with no yaw is left unrestricted.visibility – The map’s
VisibilityChecker; required formethod="vision"andmethod="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; whenFalsereturn 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;
Noneis unbounded.contest_margin – Reachability travel-distance tie band.
fov – Horizontal field of view in degrees for
method="vision"(default90.0, CS2’s own FOV);360.0or more removes the limit, making it equivalent to"raycast". Seeawpy.map_control.MapControlParamsfor all six.
- Returns:
A dict with
ct_fraction,t_fraction,contested_fraction,neutral_fraction,net_control, and (whendetail) thearea_ids/control/ct/tper-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.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:
objectRender state for one player in a
frame().Only
x/yare required.sidepicks the marker color ("t"/"ct", or the demo dataframes’"terrorist"/"counter-terrorist", any case);hp=0draws the player as dead (a dim cross);yaw(degrees, 0 = +x, counter-clockwise) draws a view-direction tick;hp/armordraw bars under the marker;labelprints below;has_bombgives 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
Playerper player to draw. Sethas_bombon 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 ofsmoke_radiusworld units.fires – World
(x, y[, z])origins of burning infernos (molotov / incendiary), each drawn as a translucent orange disc offire_radiusworld 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, orx/y/zkeys — aDemo.grenadesrow) plus an optionaltype(e.g."smoke","molotov","he") that colors it, or an explicitcolor. 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;
0hides 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
Playerper player to draw. Sethas_bombon 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 offrame()keyword arguments (e.g.{"players": [...], "bomb": (x, y, z)}).path – Output
.giffile 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
_lowerradar)?
- 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 forhist. (kdeevaluates on a fixed fine grid.)cmap – Matplotlib colormap name.
alpha – Overlay opacity.
bandwidth –
kdesmoothing 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 ofheatmap().- 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
zin the map’slowervertical section?Multi-level maps (Nuke, Vertigo, Train, Baggage) publish altitude bands in
map_data.json; single-level maps have none, so this returnsFalse.
- 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"(seeawpy.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).
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, withhighlight, 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
pygrowing 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_DIRto 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
mapslist).
- awpy.data.clear(version: int | None = None) None#
Delete cached assets — one release, or the whole cache if
versionis 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-datarelease (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(forVisibilityChecker).
Local path to a map’s
.navmesh.
- 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=Truefor the lower level of a multi-level map (Nuke, Vertigo, Train).
- awpy.data.resolve_version(version: int | None = None) str#
Resolve
versionto a concrete release tag.A given
versionis returned as-is (stringified).Noneresolves 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 withupdate()(orawpy 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=Nonehere means the latest GitHub release — this is the “check for updates” entry point — not the newest cached one. Withforce=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()(besidestick), and the value is the engine property — or the derivation, for computed ones like world position. The direct fields (health,money, theis_*flags, …) can also be passed toDemo.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(ordemo.events.counts), anddemo.events[name]to pull any of them as a DataFrame.
Exceptions#
- exception awpy.InvalidDemoError#
Bases:
Exception