Metadata-Version: 2.1
Name: wow-navmesh
Version: 0.1.0
Summary: Python bindings for Detour (recastnavigation) navmesh pathfinding over TrinityCore/AzerothCore mmaps
Keywords: recastnavigation,detour,navmesh,pathfinding,trinitycore,azerothcore,wow
Author: srounet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries
Project-URL: Homepage, https://github.com/srounet/wow-navmesh
Project-URL: Repository, https://github.com/srounet/wow-navmesh
Project-URL: Issues, https://github.com/srounet/wow-navmesh/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# wow-navmesh

Python bindings (via [nanobind](https://github.com/wjakob/nanobind)) for
[Detour](https://github.com/recastnavigation/recastnavigation), 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

```bash
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

```python
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:

```python
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`/`.mmtile` files.
- `.load_map(map_id: int)` — load the navmesh for a map id, replacing any map currently
  loaded. Raises `RuntimeError` if the files are missing, truncated, or were built for a
  different `dtPolyRef` layout 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. Raises `RuntimeError` if no map is
  loaded, `ValueError` if `max_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:

```powershell
$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](https://visualstudio.microsoft.com/downloads/) (or full
  Visual Studio) "Desktop development with C++" workload. CMake and Ninja are pulled in
  automatically by `pip` and don't need to be installed separately.

```powershell
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:

```powershell
$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](https://github.com/recastnavigation/recastnavigation) by Mikko
  Mononen and contributors.
- [nanobind](https://github.com/wjakob/nanobind) by Wenzel Jakob.
