wow-navmesh
Python bindings (via nanobind) for
Detour, the navmesh query engine
from recastnavigation — scoped to pathfinding over the .mmap/.mmtile navmesh files
generated by TrinityCore/AzerothCore for World of Warcraft 3.3.5a.
This wraps Detour's query engine (dtNavMesh / dtNavMeshQuery) only. It does not
build navmeshes — that's Recast, and TrinityCore/AzerothCore's own mmap generator tools
already produce the .mmap/.mmtile files this library reads.
Install
pip install wow-navmesh
Prebuilt wheels are published for 64-bit CPython 3.10–3.13 on Windows (x64) only. No compiler needed for a normal install. Linux and macOS are not supported.
Quickstart
import wow_navmesh as wn
nm = wn.NavMesh(r"C:\path\to\mmaps")
nm.load_map(0) # 0 = Eastern Kingdoms
path = nm.find_path((x1, y1, z1), (x2, y2, z2))
for x, y, z in path:
print(x, y, z)
NavMesh also works as a context manager, freeing the loaded map on exit:
with wn.NavMesh(r"C:\path\to\mmaps") as nm:
nm.load_map(0)
...
Coordinates are (x, y, z) in WoW world-coordinate order everywhere in this API. The
.mmap/.mmtile files store them as (y, z, x); the swap happens internally at the
find_path() boundary, so callers never need to think about it.
API
NavMesh(mmaps_path: str)— bind to a directory of.mmap/.mmtilefiles..load_map(map_id: int)— load the navmesh for a map id, replacing any map currently loaded. RaisesRuntimeErrorif the files are missing, truncated, or were built for a differentdtPolyReflayout than this build targets (see below)..free_map()— release the currently loaded map..find_path(start, end, max_points=256) -> list[(x, y, z)]— the straight path between two points, or[]if none was found. RaisesRuntimeErrorif no map is loaded,ValueErrorifmax_points <= 0..is_loaded,.map_id,.mmaps_path— read-only properties.
Full type stubs ship with the package (py.typed).
A note on DT_POLYREF64
TrinityCore/AzerothCore build their mmap generator with Detour's DT_POLYREF64 option
enabled, which widens dtPolyRef from 32 to 64 bits. That changes the on-disk byte
layout of every tile (dtLink, which embeds a dtPolyRef, changes size — and every
section of a tile after it shifts as a result). Published wheels are built with
DT_POLYREF64 on, matching TrinityCore/AzerothCore's own tools; load_map() checks
each tile's layout against what it expects and raises a clear RuntimeError (naming the
mismatch) rather than silently misreading a tile built the other way.
Building from source against a plain Detour navmesh (not TrinityCore/AzerothCore's)?
Set WOW_NAVMESH_POLYREF64=OFF before installing:
$env:WOW_NAVMESH_POLYREF64 = "OFF"
pip install --no-binary wow-navmesh wow-navmesh
wow-navmesh only supports 64-bit Windows Python interpreters; 32-bit builds and non-Windows platforms are rejected at configure time.
Building from source
Requirements:
- Windows, 64-bit CPython 3.10–3.13.
- A C++ compiler with MSVC support — the
Visual Studio Build Tools (or full
Visual Studio) "Desktop development with C++" workload. CMake and Ninja are pulled in
automatically by
pipand don't need to be installed separately.
git clone --recursive https://github.com/srounet/wow-navmesh
cd wow-navmesh
pip install .
The --recursive clone (or a git submodule update --init --recursive afterwards) is
required — Detour's sources are vendored as a git submodule under
extern/recastnavigation/, pinned to upstream tag v1.6.0.
Run the tests with pip install pytest && pytest. A second tier of tests exercises
find_path() against a real mmaps directory; point WOW_NAVMESH_TEST_MMAPS at one to
enable it:
$env:WOW_NAVMESH_TEST_MMAPS = "C:\path\to\mmaps"
pytest
Known limitations
- Only verified against TrinityCore/AzerothCore mmaps for WoW 3.3.5a. The mmap format may differ across core versions or forks; nothing here has been tested against those.
- The nearest-poly search extents (50 units on each axis) and the internal path-buffer
size (512 polygons) used by
find_path()are currently fixed, not configurable. - License: TBD (recastnavigation/Detour itself is zlib-licensed; its notice is included
under
extern/recastnavigation/).
Acknowledgments
- recastnavigation by Mikko Mononen and contributors.
- nanobind by Wenzel Jakob.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
