Add PlayCanvas integration to Recast Navigation

.yarnrc.yml

@@ -5,3 +5,5 @@ enableGlobalCache: false
 nodeLinker: node-modules
 
 yarnPath: .yarn/releases/yarn-4.1.1.cjs
+
+npmRegistryServer: "https://registry.npmjs.org"

package.json

@@ -6,6 +6,7 @@
     "packages/recast-navigation-core",
     "packages/recast-navigation-generators",
     "packages/recast-navigation-three",
+    "packages/recast-navigation-playcanvas",
     "packages/recast-navigation",
     "apps/*",
     "examples/*"

packages/recast-navigation-playcanvas/.gitignore

@@ -0,0 +1,27 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# jest coverage
+coverage

packages/recast-navigation-playcanvas/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true
+}

packages/recast-navigation-playcanvas/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @recast-navigation/playcanvas
+
+## 1.0.0
+
+- Initial release!

packages/recast-navigation-playcanvas/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2022 Isaac Mason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/recast-navigation-playcanvas/README.md

@@ -0,0 +1,178 @@
+# @recast-navigation/playcanvas
+
+PlayCanvas nav mesh generation and visualisation helpers for [`recast-navigation`](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation).
+
+## Installation
+
+```bash
+> npm install @recast-navigation/playcanas recast-navigation
+```
+
+## Usage
+
+### Importing
+
+To import the PlayCanvas glue, you can either use the `playcanvas` entrypoint in `recast-navigation`:
+
+```ts
+import { init } from 'recast-navigation'
+import { ... } from 'recast-navigation/playcanvas';
+```
+
+Or you can use the packages directly:
+
+```ts
+import { init } from '@recast-navigation/core'
+import { ... } from '@recast-navigation/playcanvas';
+```
+
+### Initialization
+
+Before you can use the library, you must initialize it. This is an asynchronous operation.
+
+Calling `init()` after the library has already been initialized will return a promise that resolves immediately.
+
+```ts
+import { init } from 'recast-navigation';
+
+await init();
+```
+
+### Generating a NavMesh
+
+This package provides convenience functions for generating nav meshes from THREE.Mesh objects.
+
+```ts
+import { init } from 'recast-navigation';
+import { pcToSoloNavMesh, pcToTiledNavMesh, pcToTileCache } from 'recast-navigation/playcanvas';
+
+/* initialize the library */
+await init();
+
+
+
+/* generate a solo navmesh */
+const { success, navMesh } = pcToSoloNavMesh(meshes, {
+  // ... nav mesh generation config ...
+}});
+
+/* generate a tiled navmesh */
+const { success, navMesh } = pcToTiledNavMesh(meshes, {
+  tileSize: 16,
+  // ... nav mesh generation config ...
+}});
+
+/* generate a tile cache with support for temporary obstacles */
+const { success, navMesh, tileCache } = pcToTileCache(meshes, {
+  tileSize: 16,
+  // ... nav mesh generation config ...
+}});
+```
+
+### Interacting with a NavMesh
+
+You can documentation for interacting with the generated navmesh in the core library README:
+
+https://github.com/isaac-mason/recast-navigation-js
+
+This library provides helpers that are used in conjunction with the core library.
+
+
+### Helpers
+
+This package provides helpers for visualizing various recast-navigation objects in three.js.
+
+#### `NavMeshHelper`
+
+```ts
+import { NavMeshHelper } from 'recast-navigation/three';
+
+const navMeshHelper = new NavMeshHelper({ navMesh });
+
+this.entity.add(navMeshHelper);
+
+// update the helper when the navmesh changes
+navMeshHelper.update();
+```
+
+#### `OffMeshConnectionsHelper`
+
+```ts
+import { OffMeshConnectionsHelper } from 'recast-navigation/three';
+
+const offMeshConnectionsHelper = new OffMeshConnectionsHelper({
+  offMeshConnections,
+});
+
+this.entity.add(offMeshConnectionsHelper);
+```
+
+#### `TileCacheHelper`
+
+Visualises obstacles in a `TileCache`.
+
+```ts
+import { TileCacheHelper } from 'recast-navigation/three';
+
+const tileCacheHelper = new TileCacheHelper({ tileCache });
+
+this.entity.add(tileCacheHelper);
+
+// update the helper after adding or removing obstacles
+tileCacheHelper.update();
+```
+
+#### `CrowdHelper`
+
+Visualises agents in a `Crowd`.
+
+```ts
+import { CrowdHelper } from 'recast-navigation/three';
+
+const crowdHelper = new CrowdHelper({ crowd });
+
+this.entity.add(crowdHelper);
+
+// update the helper after updating the crowd
+crowdHelper.update();
+```
+
+#### Custom Materials
+
+You can optionally provide custom materials to the helpers.
+
+```ts
+// NavMeshHelper
+import { StandardMaterial } from 'playcanvas';
+const navMeshMaterial = new StandardMaterial();
+const navMeshHelper = new NavMeshHelper({
+  navMesh,
+  navMeshMaterial,
+});
+
+// OffMeshConnectionsHelper
+const offMeshConnectionEntryCircleMaterial = new StandardMaterial();
+const offMeshConnectionExitCircleMaterial = new StandardMaterial();
+const offMeshConnectionLineMaterial = new StandardMaterial();
+
+const offMeshConnectionsHelper = new OffMeshConnectionsHelper({
+  offMeshConnections,
+  entryCircleMaterial: offMeshConnectionEntryCircleMaterial,
+  exitCircleMaterial: offMeshConnectionExitCircleMaterial,
+  lineMaterial: offMeshConnectionLineMaterial,
+});
+
+// TileCacheHelper
+const obstacleMaterial = new StandardMaterial();
+const tileCacheHelper = new TileCacheHelper({
+  tileCache,
+  obstacleMaterial,
+});
+
+// CrowdHelper
+const agentMaterial = new StandardMaterial();
+const crowdHelper = new CrowdHelper({
+  crowd,
+  agentMaterial,
+});
+```

packages/recast-navigation-playcanvas/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from '@isaac-mason/eslint-config-typescript'
+
+export default [...config]

packages/recast-navigation-playcanvas/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@recast-navigation/playcanvas",
+  "description": "Utilities for using recast-navigation with PlayCanvas",
+  "version": "1.0.0",
+  "license": "MIT",
+  "homepage": "https://github.com/isaac-mason/recast-navigation-js",
+  "bugs": {
+    "url": "https://github.com/isaac-mason/recast-navigation-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rollup --config rollup.config.js --bundleConfigAsCjs",
+    "test": "tsc",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@recast-navigation/core": "0.34.0",
+    "@recast-navigation/generators": "0.34.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.5",
+    "@babel/preset-env": "^7.24.5",
+    "@babel/preset-typescript": "^7.24.1",
+    "@isaac-mason/eslint-config-typescript": "^0.0.9",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.0.1",
+    "@rollup/plugin-terser": "^0.4.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "eslint": "^9.6.0",
+    "prettier": "^3.1.0",
+    "rollup": "^4.14.0",
+    "rollup-plugin-copy": "^3.4.0",
+    "rollup-plugin-filesize": "^10.0.0",
+    "typescript": "^5.4.3"
+  },
+  "packageManager": "[email protected]",
+  "peerDependencies": {
+    "playcanvas": "^1.74.0"
+  }
+}

packages/recast-navigation-playcanvas/rollup.config.js

@@ -0,0 +1,55 @@
+import babel from '@rollup/plugin-babel';
+import commonjs from '@rollup/plugin-commonjs';
+import resolve from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+import typescript from '@rollup/plugin-typescript';
+import path from 'path';
+import filesize from 'rollup-plugin-filesize';
+
+const babelOptions = {
+  babelrc: false,
+  extensions: ['.ts'],
+  exclude: '**/node_modules/**',
+  babelHelpers: 'bundled',
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        loose: true,
+        modules: false,
+        targets: '>1%, not dead, not ie 11, not op_mini all',
+      },
+    ],
+    '@babel/preset-typescript',
+  ],
+};
+
+export default [
+  {
+    input: `./src/index.ts`,
+    external: [
+      '@recast-navigation/core',
+      '@recast-navigation/generators',
+      'three',
+    ],
+    output: [
+      {
+        file: `dist/index.mjs`,
+        format: 'es',
+        sourcemap: true,
+        exports: 'named',
+      },
+    ],
+    plugins: [
+      terser(),
+      resolve(),
+      commonjs(),
+      typescript({
+        tsconfig: path.resolve(__dirname, `tsconfig.json`),
+        emitDeclarationOnly: true,
+      }),
+      babel(babelOptions),
+      filesize(),
+    ],
+  },
+];