BabylonJS / BabylonJS/Babylon-Lite

Navcat alongside Recast navigation

Open
#411 2 comments 2 reactions 1 assignee Claimed by @CedricGuillemet View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.