sourcenav

The sourcenav namespace provides a parser for Source engine .nav navigation mesh files (Version 16).

---

Function

local nav_data = sourcenav.parse(file_bytes: string) --> table | nil

Parses navigation mesh binary bytes (e.g. loaded via files.read). Returns nil if the file is invalid or not an analyzed version 16 mesh.

---

Returned Data Structure

The returned table contains:

• places: List of named map place regions (e.g. "BombsiteA", "Mid").
• ladders: List of navigation ladder connections.
• areas: List of navigation areas, where each area includes:
  • id: Unique area ID
  • north_west, south_east: Area bounding vector coordinates
  • connections: Adjacent area connections
  • hiding_spots: Strategic cover and ambush points
  • encounter_paths: Travel paths and battle segments
  • ladders: Attached ladder IDs
  • visible_areas: Line of sight area IDs

---

Example: Reading Map Nav Mesh

local map_name = common.get_map_shortname()
local nav_path = string.format("csgo/maps/%s.nav", map_name)

if files.exists(nav_path) then
    local nav = sourcenav.parse(files.read(nav_path))
    if nav then
        print(string.format("Loaded Nav Mesh for %s: %d areas, %d places",
            map_name,
            #nav.areas,
            #nav.places
        ))
    end
end