recast-navigation 0.5.0 → 0.7.0

package/README.md

@@ -42,6 +42,7 @@ await init();
 To create a NavMesh, you can use the `generateSoloNavMesh` and `generateTiledNavMesh` functions.
 
 The input positions and indices should adhere to OpenGL conventions:
+
 - Use the right-handed coordinate system
 - Indices should be in counter-clockwise winding order
 - The `positions` and `indices` arguments should be flat arrays of numbers
@@ -87,49 +88,6 @@ const radius = 0.5;
 navMeshQuery.getRandomPointAround(position, radius);
 ```
 
-### Adding Obstacles to a NavMesh
-
-Recast Navigation supports creating Box and Cylinder obstacles.
-
-Note that in order to use obstacles, you must create a tiled NavMesh.
-
-```ts
-import { generateTiledNavMesh } from 'recast-navigation';
-
-/* create a tiled NavMesh */
-const { success, navMesh, tileCache } = generateTiledNavMesh(
-  positions,
-  indices,
-  {
-    /* ... */
-    tileSize: 16,
-  }
-);
-
-/* add a Box obstacle to the NavMesh */
-const position = { x: 0, y: 0, z: 0 };
-const extent = { x: 1, y: 1, z: 1 };
-const angle = 0;
-const boxObstacle = tileCache.addBoxObstacle(position, extent, angle);
-
-/* add a Cylinder obstacle to the NavMesh */
-const radius = 1;
-const height = 1;
-const cylinderObstacle = tileCache.addCylinderObstacle(
-  position,
-  radius,
-  height,
-  angle
-);
-
-/* update the NavMesh to reflect obstacle changes */
-tileCache.update(navMesh);
-
-/* remove the obstacles from the NavMesh */
-tileCache.removeObstacle(boxObstacle);
-tileCache.removeObstacle(cylinderObstacle);
-```
-
 ### Crowds and Agents
 
 First, create a `Crowd` instance.
@@ -161,7 +119,7 @@ const initialAgentPosition = navMeshQuery.getRandomPointAround(
   2 // radius
 );
 
-const agentIndex = crowd.addAgent(initialAgentPosition, {
+const agent = crowd.addAgent(initialAgentPosition, {
   radius: 0.5,
   height: 0.5,
   maxAcceleration: 4.0,
@@ -172,35 +130,76 @@ const agentIndex = crowd.addAgent(initialAgentPosition, {
 });
 
 /* get information about the agent */
-const agentPosition = crowd.getAgentPosition(agentIndex);
-const agentVelocity = crowd.getAgentVelocity(agentIndex);
-const agentNextTargetPath = crowd.getAgentNextTargetPath(agentIndex);
-const agentState = crowd.getAgentState(agentIndex);
-const agentCorners = crowd.getAgentCorners(agentIndex);
-const agentParameters = crowd.getAgentParameters(agentIndex);
+const agentPosition = agent.position();
+const agentVelocity = agent.velocity();
+const agentNextTargetPath = agent.nextTargetPath();
+const agentState = agent.state();
+const agentCorners = agent.corners();
+const agentParameters = agent.parameters();
 
 /* tell the agent to move to a target position */
 const targetPosition = { x: 0, y: 0, z: 0 };
-crowd.goto(agentIndex, targetPosition);
+agent.goto(targetPosition);
 
 /* reset the agents target */
-crowd.resetMoveTarget(agentIndex);
+agent.resetMoveTarget();
 
 /* teleport the agent to a position */
-crowd.teleport(agentIndex, targetPosition);
+agent.teleport(targetPosition);
 
 /* update some parameters of the agent */
-crowd.updateAgentParameters(agentIndex, {
+agent.updateParameters({
   maxAcceleration: 4.0,
 });
 
 /* set all parameters for an agent */
-crowd.setAgentParameters(agentIndex, {
+agent.setParameters({
   // any omitted parameters will be set to their default values
 });
 
-/* destroy the agent */
-crowd.removeAgent(agentIndex);
+/* remove the agent */
+crowd.removeAgent(agent);
+```
+
+### Temporary Obstacles
+
+Recast Navigation supports creating Box and Cylinder obstacles.
+
+Note that in order to use obstacles, you must create a TileCache.
+
+`TileCache` assumes small tiles (around 32-64 squared). Using `tileSize` values outside this range may result in unexpected behaviour.
+
+```ts
+import { generateTileCache } from 'recast-navigation';
+
+/* create a tile cache */
+const { success, navMesh, tileCache } = generateTileCache(positions, indices, {
+  /* ... */
+  tileSize: 16,
+});
+
+/* add a Box obstacle to the NavMesh */
+const position = { x: 0, y: 0, z: 0 };
+const extent = { x: 1, y: 1, z: 1 };
+const angle = 0;
+const boxObstacle = tileCache.addBoxObstacle(position, extent, angle);
+
+/* add a Cylinder obstacle to the NavMesh */
+const radius = 1;
+const height = 1;
+const cylinderObstacle = tileCache.addCylinderObstacle(
+  position,
+  radius,
+  height,
+  angle
+);
+
+/* update the NavMesh to reflect obstacle changes */
+tileCache.update(navMesh);
+
+/* remove the obstacles from the NavMesh */
+tileCache.removeObstacle(boxObstacle);
+tileCache.removeObstacle(cylinderObstacle);
 ```
 
 ### Debugging
@@ -232,21 +231,8 @@ const navMeshExport: Uint8Array = exportNavMesh(
 const { navMesh, tileCache } = importNavMesh(navMeshExport);
 ```
 
-### Escape Hatches
-
-This library provides a higher level api over Recast, but also exposes a `Raw` api that aims to match the recast and detour libraries as much as possible.
-
-This functionality is experimental, and not all of recast is exposed yet. You will need to have familiarity with the recast and detour c++ libraries, and you may need to submit an issue or a PR if something you need is not exposed yet.
-
-Auto-generated documentation can be found here: https://docs.recast-navigation-js.isaacmason.com/variables/index.Raw.html
-
-```ts
-import { Raw } from 'recast-navigation';
-
-const navMeshData = Raw.DetourNavMeshBuilder.createNavMeshData(/* ... */);
-```
-
-The solo and tiled nav mesh generators in this library are adaptations of the `RecastDemo` examples: https://github.com/isaac-mason/recastnavigation/blob/main/RecastDemo/Source/Sample_SoloMesh.cpp
+### Advanced Usage
 
-You can use the solo and tiled nav mesh generators in this library as the basis of a nav mesh generator suiting your requirements. See: https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-core/src/generators
+This library provides low-level APIs that aim to match the recast and detour c++ api, allowing you to create custom navigation mesh generators based on your specific needs. See: https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-core/src/generators
 
+Please note that this functionality is experimental, and not all everything is exposed. Familiarity with the recast and detour C++ libraries is required. If you require unexposed functionality, please submit an issue or a pull request.

package/package.json

@@ -18,7 +18,7 @@
     "email": "isaac@isaacmason.com",
     "url": "https://isaacmason.com/"
   },
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "MIT",
   "homepage": "https://github.com/isaac-mason/recast-navigation-js",
   "bugs": {
@@ -50,8 +50,8 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
-    "@recast-navigation/core": "0.5.0",
-    "@recast-navigation/three": "0.5.0"
+    "@recast-navigation/core": "0.7.0",
+    "@recast-navigation/three": "0.7.0"
   },
   "peerDependencies": {
     "three": "^0.155.0"
@@ -63,7 +63,7 @@
     "@react-three/csg": "^3.0.0",
     "@react-three/drei": "^9.78.2",
     "@react-three/fiber": "^8.12.0",
-    "@rollup/plugin-commonjs": "^24.0.1",
+    "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-multi-entry": "^6.0.0",
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-terser": "^0.4.3",