{"id":13759038,"url":"https://github.com/donmccurdy/three-pathfinding","last_synced_at":"2025-11-13T22:56:11.562Z","repository":{"id":38184892,"uuid":"102173984","full_name":"donmccurdy/three-pathfinding","owner":"donmccurdy","description":"Navigation mesh utilities for three.js, based on PatrolJS.","archived":false,"fork":false,"pushed_at":"2025-04-21T14:35:39.000Z","size":2750,"stargazers_count":1289,"open_issues_count":17,"forks_count":135,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-04-29T21:31:32.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://three-pathfinding.donmccurdy.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donmccurdy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["donmccurdy"]}},"created_at":"2017-09-02T05:05:47.000Z","updated_at":"2025-04-29T01:01:27.000Z","dependencies_parsed_at":"2023-02-10T13:01:13.014Z","dependency_job_id":"9d15658c-ddc7-4359-a589-55f2891cf17e","html_url":"https://github.com/donmccurdy/three-pathfinding","commit_stats":{"total_commits":341,"total_committers":15,"mean_commits":"22.733333333333334","dds":0.7390029325513197,"last_synced_commit":"594cf93603e2a86a2d72e469efa0568442035a5f"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donmccurdy%2Fthree-pathfinding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donmccurdy%2Fthree-pathfinding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donmccurdy%2Fthree-pathfinding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donmccurdy%2Fthree-pathfinding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donmccurdy","download_url":"https://codeload.github.com/donmccurdy/three-pathfinding/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036811,"owners_count":22003653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T13:00:44.270Z","updated_at":"2025-11-13T22:56:11.541Z","avatar_url":"https://github.com/donmccurdy.png","language":"JavaScript","funding_links":["https://github.com/sponsors/donmccurdy"],"categories":["Gameplay","JavaScript","Pathfinding"],"sub_categories":["Visual Animation Editor","Svelte"],"readme":"# three-pathfinding\n\n[![Latest NPM release](https://img.shields.io/npm/v/three-pathfinding.svg)](https://www.npmjs.com/package/three-pathfinding)\n[![npm bundle size](https://img.shields.io/bundlephobia/minzip/three-pathfinding)](https://bundlephobia.com/package/three-pathfinding)\n[![License](https://img.shields.io/badge/license-MIT-007ec6.svg)](https://github.com/donmccurdy/three-pathfinding/blob/master/LICENSE)\n[![Build Status](https://github.com/donmccurdy/three-pathfinding/workflows/build/badge.svg?branch=main\u0026event=push)](https://github.com/donmccurdy/three-pathfinding/actions?query=workflow%3Abuild)\n\nNavigation mesh toolkit for ThreeJS, based on [PatrolJS](https://github.com/nickjanssen/PatrolJS). Computes paths between points on a 3D nav mesh, supports multiple zones, and clamps movement vectors for FPS controls. To learn how to create a navigation mesh using Blender, see [Creating a Nav Mesh](https://www.donmccurdy.com/2017/08/20/creating-a-nav-mesh-for-a-webvr-scene/).\n\nThanks to [Nick Janssen](https://github.com/nickjanssen) for creating [PatrolJS](https://github.com/nickjanssen/PatrolJS), which was the basis for this library.\n\n![screenshot](https://user-images.githubusercontent.com/1848368/34424850-d79e5a24-ebf4-11e7-87c4-afc75cdc41bd.png)\n\n## Introduction\n\nTraditionally games and 3D apps used waypoints to help their AI agents navigate. This is bad and has a lot of problems, but is generally easier to implement than navigation meshes. Navmeshes are far more accurate, faster, and take into account the size of the AI agent (e.g. tanks require move space to maneuver than soldiers).\n\nFor a thorough introduction to Navigation mesh pathfinding, see AI Blog's article, [Fixing Pathfinding Once and For All](https://web.archive.org/web/20110807104022/http://www.ai-blog.net:80/archives/000152.html).\n\n## Quickstart\n\n### Installation\n\n```\nnpm install --save three-pathfinding\n```\n\n### Creating a Navigation Mesh\n\nThis library does not build navigation meshes for you — instead, create a navigation mesh using [Blender](https://youtu.be/v4d_6ZCGlAg?t=6m8s), [Recast](https://github.com/recastnavigation/recastnavigation) ([CLI](https://github.com/but0n/recastCLI.js)), or another tool.\n\nCurrently, this library does not accept the custom navigation mesh file formats created by tools like Recast.\nInstead, you will need to export the navigation mesh to a 3D model format (like OBJ or glTF) and then load it\nwith one of the three.js loaders, like THREE.OBJLoader or THREE.GLTFLoader. The library accepts a [THREE.BufferGeometry](https://threejs.org/docs/#api/core/BufferGeometry) instance, and follows the +Y=Up convention of three.js and glTF.\n\n### Example\n\nLoading a mesh from a `.gltf` file:\n\n```js\n// For ES6, see: https://github.com/mrdoob/three.js/issues/9562\n// CommonJS\nconst THREE = window.THREE = require('three');\nrequire('three/examples/js/loaders/GLTFLoader.js');\n\nlet navmesh;\n\nconst loader = new THREE.GLTFLoader();\nloader.load( 'navmesh.gltf', ({scene}) =\u003e {\n    scene.traverse((node) =\u003e {\n        if (node.isMesh) navmesh = node;\n    });\n}, undefined, (e) =\u003e {\n    console.error(e);\n});\n```\n\nInitializing the library, creating a level, and finding a path:\n\n```js\n// ES6\nimport { Pathfinding } from 'three-pathfinding';\n// CommonJS\nconst { Pathfinding } = require('three-pathfinding');\n// UMD\nconst Pathfinding = window.threePathfinding.Pathfinding;\n\n// Create level.\nconst pathfinding = new Pathfinding();\nconst ZONE = 'level1';\npathfinding.setZoneData(ZONE, Pathfinding.createZone(navmesh.geometry));\n\n// Find path from A to B.\nconst groupID = pathfinding.getGroup(ZONE, a);\nconst path = pathfinding.findPath(a, b, ZONE, groupID);\n```\n\nThe origin of an agent should initially be placed on the surface of the nav mesh. If needed, a dummy object can be used for pathfinding logic, and the rendered model for that agent may be placed at on offset as needed.\n\n### Running the demo locally\n\n```\ngit clone https://github.com/donmccurdy/three-pathfinding.git\ncd three-pathfinding\n\nyarn install\nyarn run dev\n```\n\nThe demo will start at http://localhost:3000/.\n\n## API\n\n\u003c!--- API BEGIN ---\u003e\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n### Table of Contents\n\n-   [Pathfinding][1]\n    -   [setZoneData][2]\n    -   [getRandomNode][4]\n    -   [getClosestNode][6]\n    -   [findPath][8]\n    -   [getGroup][10]\n    -   [clampStep][12]\n    -   [createZone][14]\n-   [PathfindingHelper][16]\n    -   [setPath][17]\n    -   [setPlayerPosition][19]\n    -   [setTargetPosition][21]\n    -   [setNodePosition][23]\n    -   [setStepPosition][25]\n    -   [reset][27]\n-   [Zone][28]\n-   [Group][30]\n-   [Node][31]\n\n## Pathfinding\n\nDefines an instance of the pathfinding module, with one or more zones.\n\n### setZoneData\n\nSets data for the given zone.\n\n#### Parameters\n\n-   `zoneID` **[string][33]**\n-   `zone` **[Zone][34]**\n\n### getRandomNode\n\nReturns a random node within a given range of a given position.\n\n#### Parameters\n\n-   `zoneID` **[string][33]**\n-   `groupID` **[number][35]**\n-   `nearPosition` **Vector3**\n-   `nearRange` **[number][35]**\n\nReturns **[Node][36]**\n\n### getClosestNode\n\nReturns the closest node to the target position.\n\n#### Parameters\n\n-   `position` **Vector3**\n-   `zoneID` **[string][33]**\n-   `groupID` **[number][35]**\n-   `checkPolygon` **[boolean][37]**  (optional, default `false`)\n\nReturns **[Node][36]**\n\n### findPath\n\nReturns a path between given start and end points. If a complete path\ncannot be found, will return the nearest endpoint available.\n\n#### Parameters\n\n-   `startPosition` **Vector3** Start position.\n-   `targetPosition` **Vector3** Destination.\n-   `zoneID` **[string][33]** ID of current zone.\n-   `groupID` **[number][35]** Current group ID.\n\nReturns **[Array][38]\u0026lt;Vector3\u003e** Array of points defining the path.\n\n### getGroup\n\nReturns closest node group ID for given position.\n\n#### Parameters\n\n-   `zoneID` **[string][33]**\n-   `position` **Vector3**\n\nReturns **[number][35]**\n\n### clampStep\n\nClamps a step along the navmesh, given start and desired endpoint. May be\nused to constrain first-person / WASD controls.\n\n#### Parameters\n\n-   `start` **Vector3**\n-   `end` **Vector3** Desired endpoint.\n-   `node` **[Node][36]**\n-   `zoneID` **[string][33]**\n-   `groupID` **[number][35]**\n-   `endTarget` **Vector3** Updated endpoint.\n\nReturns **[Node][36]** Updated node.\n\n### createZone\n\n(Static) Builds a zone/node set from navigation mesh geometry.\n\n#### Parameters\n\n-   `geometry` **BufferGeometry**\n-   `tolerance` **[number][35]** Vertex welding tolerance. (optional, default `1e-4`)\n\nReturns **[Zone][34]**\n\n## PathfindingHelper\n\n**Extends Object3D**\n\nHelper for debugging pathfinding behavior.\n\n### setPath\n\n#### Parameters\n\n-   `path` **[Array][38]\u0026lt;Vector3\u003e**\n\nReturns **this**\n\n### setPlayerPosition\n\n#### Parameters\n\n-   `position` **Vector3**\n\nReturns **this**\n\n### setTargetPosition\n\n#### Parameters\n\n-   `position` **Vector3**\n\nReturns **this**\n\n### setNodePosition\n\n#### Parameters\n\n-   `position` **Vector3**\n\nReturns **this**\n\n### setStepPosition\n\n#### Parameters\n\n-   `position` **Vector3**\n\nReturns **this**\n\n### reset\n\nHides all markers.\n\nReturns **this**\n\n## Zone\n\nDefines a zone of interconnected groups on a navigation mesh.\n\nType: [Object][39]\n\n### Properties\n\n-   `groups` **[Array][38]\u0026lt;[Group][40]\u003e**\n-   `vertices` **[Array][38]\u0026lt;Vector3\u003e**\n\n## Group\n\nDefines a group within a navigation mesh.\n\nType: [Object][39]\n\n## Node\n\nDefines a node (or polygon) within a group.\n\nType: [Object][39]\n\n### Properties\n\n-   `id` **[number][35]**\n-   `neighbours` **[Array][38]\u0026lt;[number][35]\u003e** IDs of neighboring nodes.\n-   `vertexIds` **[Array][38]\u0026lt;[number][35]\u003e**\n-   `centroid` **Vector3**\n-   `portals` **[Array][38]\u0026lt;[Array][38]\u0026lt;[number][35]\u003e\u003e** Array of portals, each defined by two vertex IDs.\n-   `closed` **[boolean][37]**\n-   `cost` **[number][35]**\n\n[1]: #pathfinding\n\n[2]: #setzonedata\n\n[3]: #parameters\n\n[4]: #getrandomnode\n\n[5]: #parameters-1\n\n[6]: #getclosestnode\n\n[7]: #parameters-2\n\n[8]: #findpath\n\n[9]: #parameters-3\n\n[10]: #getgroup\n\n[11]: #parameters-4\n\n[12]: #clampstep\n\n[13]: #parameters-5\n\n[14]: #createzone\n\n[15]: #parameters-6\n\n[16]: #pathfindinghelper\n\n[17]: #setpath\n\n[18]: #parameters-7\n\n[19]: #setplayerposition\n\n[20]: #parameters-8\n\n[21]: #settargetposition\n\n[22]: #parameters-9\n\n[23]: #setnodeposition\n\n[24]: #parameters-10\n\n[25]: #setstepposition\n\n[26]: #parameters-11\n\n[27]: #reset\n\n[28]: #zone\n\n[29]: #properties\n\n[30]: #group\n\n[31]: #node\n\n[32]: #properties-1\n\n[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String\n\n[34]: #zone\n\n[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number\n\n[36]: #node\n\n[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean\n\n[38]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array\n\n[39]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object\n\n[40]: #group\n\u003c!--- API END ---\u003e\n\n## Thanks to\n\n* [PatrolJS](https://github.com/nickjanssen/PatrolJS)\n* [bgrin's astar library](https://github.com/bgrins/javascript-astar)\n* [Digesting Duck's Simple Stupid Funnel Algorithm](http://digestingduck.blogspot.jp/2010/03/simple-stupid-funnel-algorithm.html)\n* [Recastnavigation's level mesh](https://github.com/memononen/recastnavigation)\n* [Constrained Movement Along Navmesh pt. 3](http://digestingduck.blogspot.com/2010/07/constrained-movement-along-navmesh-pt-3.html?m=1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonmccurdy%2Fthree-pathfinding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonmccurdy%2Fthree-pathfinding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonmccurdy%2Fthree-pathfinding/lists"}