Navigation meshes#
A navigation mesh divides walkable space into connected polygonal areas.
Use NavMesh to locate a point or find a route.
awpy-data supplies CS2 .nav files.
Dust 2 nav areas, drawn with awpy.plot.nav().#
NavMesh#
from awpy import NavMesh
nav = NavMesh("de_dust2")
nav.find_area((-1500.0, 900.0, 60.0)) # -> an area id, e.g. 812
nav.find_path(812, 42) # -> [812, ..., 42] (area ids along the way)
The constructor takes a map name or a .nav file:
NavMesh("de_dust2") # newest release cached under ~/.awpy
# (downloads the latest if none is cached)
NavMesh("de_dust2", version=2000873) # pin an awpy-data release
NavMesh("path/to/de_dust2.nav") # load a specific .nav file
A string counts as a file path when it ends in .nav or contains a path
separator; a pathlib.Path always does. Anything else is treated as a map name
and resolved through awpy.data.nav_path.
Points use (x, y, z) in Hammer units, with Z vertical.
find_area returns a numeric area_id.
Areas#
nav.areas has one row per area:
nav.areas
# shape: (2_248, 9)
# ┌─────────┬────────────┬─────────────────────────┬───────────┬───┬──────┬───────────────┐
# │ area_id ┆ hull_index ┆ dynamic_attribute_flags ┆ n_corners ┆ … ┆ size ┆ n_connections │
# ╞═════════╪════════════╪═════════════════════════╪═══════════╪═══╪══════╪═══════════════╡
# │ 1 ┆ 0 ┆ 0 ┆ 4 ┆ … ┆ 520… ┆ 1 │
# │ … ┆ … ┆ … ┆ … ┆ … ┆ … ┆ … │
Column |
Description |
|---|---|
|
Unique id of the area. |
|
Collision hull the area was generated for. |
|
Engine attribute bitset (bomb-target, defuse, …). |
|
Number of polygon corners. |
|
Geometric center of the polygon. |
|
2D area of the polygon (Hammer units²). |
|
Distinct neighbouring areas. |
For the full geometry of a single area — its corners and neighbour ids — use
nav.area(area_id):
nav.area(1)
# {'area_id': 1, 'hull_index': 0, 'dynamic_attribute_flags': 0,
# 'corners': [(150.5, 10.5, 12.0), (185.0, 21.0, 10.0), ...],
# 'connections': [3], 'ladders_above': [], 'ladders_below': [],
# 'centroid': (162.5, 25.1, 11.0), 'size': 520.9}
Queries#
area = nav.find_area((x, y, z)) # area containing a world point (or None)
nav.neighbors(area) # -> [ids reachable directly]
nav.find_path(start, end) # -> [ids] from start to end, inclusive
find_area handles overlapping floors: when several areas cover the same
(x, y) (a bridge over a tunnel, stacked levels), it returns the one whose
height is closest to the point’s z.
find_path accepts either an area id or a point for each endpoint (a
point is resolved with find_area first), and returns the list of area ids from
start to end inclusive — or an empty list if either endpoint maps to no area
or no route connects them. Connections are directional, matching the mesh.
Edges can be weighted three ways:
nav.find_path(a, b, weight="distance") # default: 3D distance between centroids
nav.find_path(a, b, weight="hops") # fewest areas
nav.find_path(a, b, weight="size") # sum of area sizes; routes away from large areas
Draw a route with awpy.plot.nav():
from awpy.plot import nav as plot_nav
route = nav.find_path((-680.0, 1500.0, 0.0), (1200.0, 2400.0, 0.0))
fig, ax = plot_nav("de_dust2", highlight=route)
Use highlight= to draw a route or another set of area IDs.#
Member |
Type |
Description |
|---|---|---|
|
Load a map’s nav (or a |
|
|
|
One row per area (see above). |
|
|
Full detail for one area, including |
|
|
Area containing an |
|
|
Distinct areas reachable directly. |
|
|
Shortest area path; endpoints are ids or points. |
|
|
Nav-mesh format version (CS2 ships 36). |
|
|
Whether bot-navigation data was generated. |
|
|
Number of areas. |
|
|
The file the nav was loaded from. |
Example: tag every kill with its area#
import polars as pl
from awpy import Demo, NavMesh
demo = Demo("match.dem")
nav = NavMesh(demo.header["map_name"])
kills = demo.kills.with_columns(
pl.Series(
"victim_area",
[
nav.find_area((r["victim_x"], r["victim_y"], r["victim_z"]))
for r in demo.kills.iter_rows(named=True)
],
)
)
See Visibility & map data for assets and cache management.