> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Nav
icon: footprints
---

# <ApiPageIcon icon="footprints" />Nav

<Heading level={2} id="nav-1">
  nav

  <ApiTag label="global table" />
</Heading>

Finds walking paths on the navigation mesh of the current map.

The mesh is read from the `.nav` file of the map on the first call after a level loads. It is
removed when the map changes or when you disconnect. Outside a game, or on a map without a
`.nav` file, `nav.IsLoaded` returns `false` and the other functions return `nil`.

Paths are for a player on foot. They can use steps, drops and jumps up to the height of a
crouch jump.

Distances are in walk units. One walk unit is the time a player needs to run one world unit
with a knife at 250 units per second. Drops and jumps take more time, so they count as more
than their length. Divide a distance by 250 to estimate the time in seconds.

<ApiMembers>
  <ApiMember kind="fn" name="nav.IsLoaded" summary="Returns whether the navigation mesh of the current map is loaded. The first call on a new level builds the mesh." args="" sig="[{&#x22;s&#x22;:&#x22;nav.IsLoaded&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]">
    <ApiExample title="Check for a nav mesh">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/nav:0:7b9b84c6e519"
      if not nav.IsLoaded() then print("no nav mesh on this map") end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="fn" name="nav.Snap" summary="Finds the point on the navigation mesh that is closest to a world position." args="pos, max_distance?" sig="[{&#x22;s&#x22;:&#x22;nav.Snap&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;pos&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;max_distance&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}],[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;pos&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The position in world space.&#x22;},{&#x22;n&#x22;:&#x22;max_distance&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;}],&#x22;d&#x22;:&#x22;The search radius in world units. The default is `256`.&#x22;,&#x22;o&#x22;:true}]" returns="[{&#x22;n&#x22;:&#x22;point&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}],&#x22;d&#x22;:&#x22;The closest point on the mesh.&#x22;},{&#x22;n&#x22;:&#x22;distance&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}],&#x22;d&#x22;:&#x22;The distance from `pos` to `point`.&#x22;}]">
    <ApiNotes>
      Returns the point on the mesh and its distance from `pos`. Returns `nil` if there is no
      walkable area within `max_distance`. Throws an error if `pos` is not a finite vector or if
      `max_distance` is negative or not finite.
    </ApiNotes>

    <ApiExample title="Snap a position to the mesh">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/nav:1:9f9a465a39ff"
      local point, distance = nav.Snap(Vector(-300, 1200, 100))
      if point then
          print("nearest walkable point ", point, ", ", distance, " units away")
      end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="fn" name="nav.GetDistance" summary="Returns the shortest walking distance between two world positions, in walk units." args="from, to" sig="[{&#x22;s&#x22;:&#x22;nav.GetDistance&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;from&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;to&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;from&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The start position.&#x22;},{&#x22;n&#x22;:&#x22;to&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The goal position.&#x22;}]">
    <ApiNotes>
      Both positions are moved to the closest point on the mesh within 256 units. Returns `nil` if a
      position has no mesh within 256 units, or if no walkable route connects the two positions.
      Throws an error if a position is not a finite vector.
    </ApiNotes>

    <ApiExample title="Estimate walking time">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/nav:2:acb6f9fe0826"
      local pawn = entity.GetLocalPlayerPawn()
      local distance = pawn and nav.GetDistance(pawn:GetAbsOrigin(), Vector(-300, 1200, 100))
      if distance then print(("about %.1f s away"):format(distance / 250)) end
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="fn" name="nav.FindPath" summary="Returns the shortest walking path between two world positions, as a list of points from `from` to `to`." args="from, to" sig="[{&#x22;s&#x22;:&#x22;nav.FindPath&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;from&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;to&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;from&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The start position.&#x22;},{&#x22;n&#x22;:&#x22;to&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The goal position.&#x22;}]">
    <ApiNotes>
      Both positions are moved to the closest point on the mesh within 256 units to find the
      route. The path is smoothed, so it cuts corners where the mesh allows it. Returns `nil` if a
      position has no mesh within 256 units, or if no walkable route connects the two positions.
      Throws an error if a position is not a finite vector.
    </ApiNotes>

    <ApiExample title="Walk the path segment by segment">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/nav:3:2b73dbfcbb19"
      local pawn = entity.GetLocalPlayerPawn()
      local path = pawn and nav.FindPath(pawn:GetAbsOrigin(), Vector(-300, 1200, 100))
      if path then
          for i = 2, #path do
              print(("segment %d: %.0f units"):format(i - 1, path[i - 1]:DistTo(path[i])))
          end
      end
      ```
    </ApiExample>
  </ApiMember>
</ApiMembers>
