BabylonJS / BabylonJS/Babylon-Lite
Navcat alongside Recast navigation
- Dominant language
- TypeScript
- Stars
- 149
- Forks
- 29
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 106
Description
## Summary
Request to add `navcat` as an **optional navigation backend** in Babylon Lite, alongside the existing Recast V2 integration.
- Navcat: [https://github.com/isaac-mason/navcat](https://github.com/isaac-mason/navcat)
- Docs: [https://navcat.dev/docs](https://navcat.dev/docs)
Goal: enable apps to opt into a **pure-JS, tree-shakable** navmesh stack (and JSON-serializable navmesh data) without removing or changing the default Recast path.
## Motivation
Babylon Lite emphasizes:
- tree-shakability / minimal bytes
- modular opt-in features
- WebGPU-first architecture
Recast (WASM) is proven and featureful, but some apps want:
- no WASM init / payload
- easier debugging / introspection (plain JS objects)
- trivial persistence/networking of navmesh data (JSON)
Navcat offers:
- pure JS / TypeScript, designed to be tree-shakable
- solo + tiled navmesh generation + querying
- query filters as JS functions
- off-mesh connections
- optional crowd modules (`navcat/blocks`)
## Proposed design
### 1) New way to create navigation with Navcat
- `createNavcatManager()`
Keep existing Recast manager as it is currently.
### 2) Opt-in packaging / tree-shaking
- `navcat` should be in a **separate entrypoint** / lazily imported module so non-navcat apps pay **0 bytes**.
- If `navcat/blocks` is required (generation presets / crowd), gate it similarly (optional import).
### 3) Geometry extraction utilities
Navcat generation input is `(positions, indices)` with RH + CCW winding.
Provide a helper that extracts correct data from Lite/Babylon meshes, and documents:
- coordinate conventions (RH vs LH)
- winding order expectations
- what geometry should be included/excluded
### 4) Debug visualization
Navcat has engine-agnostic debug primitives (triangles/lines/points/boxes).
Add a Lite debug adapter so developers can visualize:
- navmesh polys
- search nodes
- paths
- off-mesh links
## Acceptance criteria (MVP)
### Querying
- [ ] `findNearestPoly`
- [ ] `findPath` (or `findNodePath` + `findStraightPath`)
- [ ] `raycast`
- [ ] `moveAlongSurface`
### Generation
- [ ] At least **solo** navmesh generation from mesh triangles
- [ ] Tiled generation optional (OK to defer)
### Features
- [ ] Off-mesh connections (add/remove + path traversal)
- [ ] Custom query filter hook (passability + cost)
### Integration & docs
- [ ] Document the new optional way to create navigation
- [ ] Document bundle-size + runtime tradeoffs
- [ ] Provide a minimal lab scene demoing navcat pathfinding + debug draw
### Lifecycle / teardown (required for real apps)
Without teardown + rebuild support, a nav backend is hard to use in real games that stream levels or let players edit worlds.
A key requirement for adopting navcat in real games is being able to **tear down** navigation cleanly when:
- unloading a scene / level
- switching levels
- rebuilding navmesh for edited geometry
- disabling nav temporarily (performance or gameplay reasons)
So the goals for this would be:
- [ ] Provide a `dispose()` / `teardownNavigation()` API that releases **all navigation resources** and detaches any per-frame hooks/observers.
- [ ] After teardown, all navigation queries either:
- no-op safely (return `{ success:false }`), or
- throw a clear, documented error (pick one and document).
- [ ] Teardown is **idempotent** (safe to call multiple times).
- [ ] Teardown covers:
- [ ] Navmesh data itself (navcat `NavMesh` object + tiles)
- [ ] Off-mesh connections created at runtime
- [ ] Any crowd / agent simulation state (if using `navcat/blocks`)
- [ ] Debug visualization resources (helper meshes/lines/points/boxes) created by the navcat debug adapter
- [ ] Any caches/pools used for query helpers (e.g., reused result objects) — ensure no leaks across level swaps
- [ ] Any worker/timer usage (if introduced later for building or crowd stepping)
- [ ] Nice-to-have: hot swap / rebuild
- [ ] Support `replaceNavMesh(newNavMesh)` (or `setNavMesh(null)` + `setNavMesh(mesh)`) so apps can rebuild without reconstructing the entire manager.
- [ ] Document whether `NodeRef` / polygon references become invalid across rebuilds and how callers should handle that (navcat has `isValidNodeRef`).
## Non-goals
- Replacing or deprecating Recast
- Perfect Babylon.js `RecastJSPlugin` API parity
- Full crowd simulation parity on day 1 (can be follow-up)
## Open questions
- How should coordinate-system conversion be handled if a caller uses LH content?
## References
- Navcat README: `https://github.com/isaac-mason/navcat`
- Navcat docs: `https://navcat.dev/docs`
- Existing Lite navigation scenes (Recast): 170–175 in `scene-config.json`
Contributor guide
Assessment
This issue has not been assessed yet.