{"id":29117821,"url":"https://github.com/prismarinejs/mineflayer-pathfinder","last_synced_at":"2025-10-11T22:19:13.258Z","repository":{"id":37848625,"uuid":"257460120","full_name":"PrismarineJS/mineflayer-pathfinder","owner":"PrismarineJS","description":"Pathfinding plugin that gives bot the ability to go from A to B","archived":false,"fork":false,"pushed_at":"2025-08-18T11:07:37.000Z","size":466,"stargazers_count":260,"open_issues_count":41,"forks_count":83,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-04T21:29:59.454Z","etag":null,"topics":["bot","minecraft","pathfinding"],"latest_commit_sha":null,"homepage":"","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/PrismarineJS.png","metadata":{"files":{"readme":"readme.md","changelog":"history.md","contributing":null,"funding":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-04-21T02:34:23.000Z","updated_at":"2025-10-04T05:19:17.000Z","dependencies_parsed_at":"2025-04-19T02:33:35.862Z","dependency_job_id":"799483c5-8a8e-440b-9b3e-a2a87e7136aa","html_url":"https://github.com/PrismarineJS/mineflayer-pathfinder","commit_stats":{"total_commits":310,"total_committers":43,"mean_commits":7.209302325581396,"dds":0.567741935483871,"last_synced_commit":"d69a02904bc83f4c36598ae90d470a009a130105"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/PrismarineJS/mineflayer-pathfinder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrismarineJS%2Fmineflayer-pathfinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrismarineJS%2Fmineflayer-pathfinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrismarineJS%2Fmineflayer-pathfinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrismarineJS%2Fmineflayer-pathfinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PrismarineJS","download_url":"https://codeload.github.com/PrismarineJS/mineflayer-pathfinder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrismarineJS%2Fmineflayer-pathfinder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279009056,"owners_count":26084548,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bot","minecraft","pathfinding"],"created_at":"2025-06-29T12:07:45.422Z","updated_at":"2025-10-11T22:19:13.216Z","avatar_url":"https://github.com/PrismarineJS.png","language":"JavaScript","funding_links":["https://issuehunt.io/r/PrismarineJS/mineflayer-pathfinder"],"categories":[],"sub_categories":[],"readme":"# Mineflayer-pathfinder\n\n[![npm version](https://badge.fury.io/js/mineflayer-pathfinder.svg)](https://badge.fury.io/js/mineflayer-pathfinder) ![npm](https://img.shields.io/npm/dt/mineflayer-pathfinder) [![Try it on gitpod](https://img.shields.io/badge/try-on%20gitpod-brightgreen.svg)](https://gitpod.io/#https://github.com/PrismarineJS/mineflayer-pathfinder) [![Issue Hunt](https://github.com/BoostIO/issuehunt-materials/blob/master/v1/issuehunt-shield-v1.svg)](https://issuehunt.io/r/PrismarineJS/mineflayer-pathfinder)\n\nPathfinding plugin for the Minecraft Bot API [Mineflayer](https://github.com/PrismarineJS/mineflayer). Create static, dynamic or composite goals to navigate Minecraft terrain fully autonomously.\n\nMostly stable. Feel free to contribute by making suggestions or posting issues.\n\n## Install\n\n```bash\nnpm install mineflayer-pathfinder\n```\n\n## Tutorial \u0026 Explanation\n\nFor a basic explanation of how to use mineflayer-pathfinder, you can read [this tutorial](./examples/tutorial/goalsExplained.md).\n\n## Video Tutorials\n\nFor a video tutorial explaining the usage of mineflayer-pathfinder, you can watch the following Youtube videos:\n\n[\u003cimg src=\"https://img.youtube.com/vi/UWGSf08wQSc/0.jpg\" alt=\"part 1\" width=\"200\"\u003e](https://www.youtube.com/watch?v=UWGSf08wQSc)\n[\u003cimg src=\"https://img.youtube.com/vi/ssWE0kXDGJE/0.jpg\" alt=\"part 2\" width=\"200\"\u003e](https://www.youtube.com/watch?v=ssWE0kXDGJE)\n\n## Example\n\n```js\nconst mineflayer = require('mineflayer')\nconst pathfinder = require('mineflayer-pathfinder').pathfinder\nconst Movements = require('mineflayer-pathfinder').Movements\nconst { GoalNear } = require('mineflayer-pathfinder').goals\nconst bot = mineflayer.createBot({ username: 'Player' })\n\nbot.loadPlugin(pathfinder)\n\nbot.once('spawn', () =\u003e {\n  const defaultMove = new Movements(bot)\n  \n  bot.on('chat', function(username, message) {\n  \n    if (username === bot.username) return\n\n    const target = bot.players[username] ? bot.players[username].entity : null\n    if (message === 'come') {\n      if (!target) {\n        bot.chat('I don\\'t see you !')\n        return\n      }\n      const p = target.position\n\n      bot.pathfinder.setMovements(defaultMove)\n      bot.pathfinder.setGoal(new GoalNear(p.x, p.y, p.z, 1))\n    } \n  })\n})\n```\n\n## Features\n * Optimized and modernized A* pathfinding\n * Complexe goals can be specified (inspired by [baritone goals](https://github.com/cabaletta/baritone/blob/master/FEATURES.md#goals) )\n * Customizable movements generator\n * Each movement can have a different cost\n * Can break/place blocks as part of its deplacement\n * Automatically update path when environment change\n * Long distance paths\n * Can swim\n * Can avoid entities\n * Modular and easily extendable with different behavior\n\n## API\nConsidering there are a lot of deep changes that are being worked on, it could take some time before it's done\n\nAlso, **for now**, there is only the `pathfinder` module, `movements` and `goals` still need to be done\n\n\n# Functions:\n\n### bot.pathfinder.goto(goal)\nReturns a Promise with the path result. Resolves when the goal is reached. Rejects on error.\n * `goal` - Goal instance\n\n### bot.pathfinder.bestHarvestTool(block)\nReturns the best harvesting tool in the inventory for the specified block.\n * `Returns` - `Item` instance or `null`\n * `block` - Block instance\n\n### bot.pathfinder.getPathTo(movements, goal, timeout)\n * `Returns` - The path\n * `movements` - Movements instance\n * `goal` - Goal instance\n * `timeout` - number (optional, default `bot.pathfinder.thinkTimeout`)\n\n### bot.pathfinder.getPathFromTo* (movements, startPos, goal, options = {})\nReturns a Generator. The generator computes the path for as longs as no full path is found or `options.timeout` is reached. \nThe generator will block the event loop until a path is found or `options.tickTimeout` (default to 50ms) is reached.\n * `Returns` - A generator instance. See [MDN function*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*).\n * `movements` - Movements instance\n * `startPos` - A Vec3 instance. The starting position to base the path search from. \n * `goal` - Goal instance\n * `options` - A optional options object contains:\n   * `optimizePath` - Boolean Optional. Optimize path for shortcuts like going to the next node in a strait line instead walking only diagonal or along axis.\n   * `resetEntityIntersects` - Boolean Optional. Reset the `entityIntersections` index for `movements`. Default: true\n   * `timeout` - Number Optional. Total computation timeout.\n   * `tickTimeout` - Number Optional. Maximum amount off time before yielding.\n   * `searchRadius` - Number Optional. Max distance to search.\n   * `startMove` - instance of Move Optional. A optional starting position as a Move. Replaces `startPos` as the starting position.\n\n### bot.pathfinder.setGoal(Goal, dynamic)\n * `goal` - Goal instance\n * `dynamic` - boolean (optional, default false)\n \n### bot.pathfinder.setMovements(movements)\nAssigns the movements config.\n * `movements` - Movements instance\n\n### bot.pathfinder.stop()\nStops pathfinding as soon as the bot has reached the next node in the path (this prevents the bot from stopping mid-air). Emits `path_stop` when called.\nNote: to force stop immediately, use `bot.pathfinder.setGoal(null)`\n\n### bot.pathfinder.isMoving()\nA function that checks if the bot is currently moving.\n * `Returns` - boolean\n\n### bot.pathfinder.isMining()\nA function that checks if the bot is currently mining blocks.\n * `Returns` - boolean\n\n### bot.pathfinder.isBuilding()\nA function that checks if the bot is currently placing blocks.\n * `Returns` - boolean\n\n# Properties:\n### bot.pathfinder.thinkTimeout\nThink Timeout in milliseconds.\n * `Default` - `5000`\n\n### bot.pathfinder.tickTimeout\nHow many milliseconds per tick are allocated to thinking.\n * `Default` - `40`\n\n### bot.pathfinder.searchRadius\nThe search limiting radius, in blocks, if `-1` the search is not limited by distance.\n * `Default` - `-1`\n\n# Movement class\nThis class configures how pathfinder plans its paths. It configures things like block breaking or different costs for moves. This class can be extended to add or change how pathfinder calculates its moves.\n\n## Usage\nPathfinder instantiates the default movement class by itself if no instance is specified. If you want to change values you should create a new instance of the Movements class, change it's values and set it as pathfinders new movement class. \n### Example:\n```js\nconst { Movements } = require('mineflayer-pathfinder') // Import the Movements class from pathfinder\n\nbot.once('spawn', () =\u003e {\n  // A new movement instance for specific behavior\n  const defaultMove = new Movements(bot)\n\n  defaultMove.allow1by1towers = false // Do not build 1x1 towers when going up\n  defaultMove.canDig = false // Disable breaking of blocks when pathing \n  defaultMove.scafoldingBlocks.push(bot.registry.itemsByName['netherrack'].id) // Add nether rack to allowed scaffolding items\n  bot.pathfinder.setMovements(defaultMove) // Update the movement instance pathfinder uses\n\n  // Do pathfinder things\n  // ...\n})\n```\n\n## Movements class default properties\nMovement class properties and their default values.\n### canDig\nBoolean to allow breaking blocks.\n* Default `true`\n\n### digCost\nAdditional cost for breaking blocks.\n* Default - `1`\n\n### placeCost\nAdditional cost for placing blocks.\n* Default - `1`\n\n### maxDropDown\nMax drop down distance. Only considers drops that have blocks to land on.\n* Default - `4`\n\n### infiniteLiquidDropdownDistance\nOption to ignore maxDropDown distance when the landing position is in water.\n* Default - `true`\n\n### liquidCost\nAdditional cost for interacting with liquids.\n* Default - `1`\n\n### entityCost\nAdditional cost for moving through an entity hitbox (besides passable ones).\n* Default - `1`\n\n### dontCreateFlow\nDo not break blocks that touch liquid blocks.\n* Default - `true`\n\n### dontMineUnderFallingBlock\nDo not break blocks that have a gravityBlock above.\n* Default - `true`\n\n### allow1by1towers\nAllow pillaring up on 1x1 towers.\n* Default - `true`\n\n### allowFreeMotion\nAllow to walk to the next node/goal in a straight line if terrain allows it.\n* Default - `false`\n\n### allowParkour\nAllow parkour jumps like jumps over gaps bigger then 1 block.\n* Default - `true`\n\n### allowSprinting\nAllow sprinting when moving.\n* Default - `true`\n\n### allowEntityDetection\nTest for entities that may obstruct path or prevent block placement. Grabs updated entities every new path.\n* Default - `true`\n\n### entitiesToAvoid\nSet of entities (by bot.registry name) to completely avoid when using entity detection.\n* instance of `Set`\n\n### passableEntities\nSet of entities (by bot.registry name) to ignore when using entity detection.\n* instance of `Set`\n* Default - See lib/passableEntities.json\n\n### interactableBlocks\nSet of blocks (by bot.registry name) that pathfinder should not attempt to place blocks or 'right click' on.\n* instance of `Set`\n* Default - See lib/interactable.json\n\n### blocksCantBreak\nSet of block id's pathfinder cannot break. Includes chests and all unbreakable blocks.\n* instance of `Set`\n\n### blocksToAvoid\nSet of block id's to avoid.\n* instance of `Set`\n\n### liquids\nSet of liquid block id's.\n* instance of `Set`\n\n### climbables\nSet of block id's that are climable. Note: Currently unused as pathfinder cannot use climables.\n* instance of `Set`\n\n### replaceables\nSet of block id's that can be replaced when placing blocks.\n* instance of `Set`\n\n### scafoldingBlocks\nArray of item id's that can be used as scaffolding blocks.\n* Default - `[\u003cscaffoldingItems\u003e]`\n\n### gravityBlocks\nSet of block id's that can fall on bot's head.\n* instance of `Set`\n\n### fences\nSet of block id's that are fences or blocks that have a collision box taller then 1 block.\n* instance of `Set`\n\n### carpets\nSet of all carpet block id's or blocks that have a collision box smaller then 0.1. These blocks are considered safe to walk in.\n* instance of `Set`\n\n### exclusionAreasStep\nAn array of functions that define an area or block to be step on excluded. Every function in the array is parsed the Block the bot is planing to step on. Each function should return a positive number (includes 0) that defines extra cost for that specific Block. 0 means no extra cost, 100 means it is impossible for pathfinder to consider this move.\n* Array of functions `(block: Block) =\u003e number`\n\n### exclusionAreasBreak\nAn array of functions that define an area or block to be break excluded. Every function in the array is parsed the Block the bot is planing to break. Each function should return a positive number (includes 0) that defines extra cost for that specific Block. 0 means no extra cost, 100 means it is impossible for pathfinder to consider this move.\n* Array of functions `(block: Block) =\u003e number`\n\n### exclusionAreasPlace\nAn array of functions that define an area to be block placement excluded. Every function in the array is parsed the current Block the bot is planing to place a block inside (should be air or a replaceable block most of the time). Each function should return a positive number (includes 0) that defines extra cost for that specific Block. 0 means no extra cost, 100 makes it impossible for pathfinder to consider this move.\n* Array of functions `(block: Block) =\u003e number`\n\n### entityIntersections\nA dictionary of the number of entities intersecting each floored block coordinate. Updated automatically for each path, but you may mix in your own entries before calculating a path if desired (generally for testing). To prevent this from being cleared automatically before generating a path,s see the [path gen options](#botpathfindergetpathfromto-movements-startpos-goal-options--). \n* Formatted entityIntersections['x,y,z'] = #ents\n* Dictionary of costs `{string: number}`\n\n### canOpenDoors\nEnable feature to open Fence Gates. Unreliable and known to be buggy.\n* Default - `false`\n\n# Events:\n\n### goal_reached\nCalled when the goal has been reached. Not called for dynamic goals.\n\n### path_update\nCalled whenever the path is recalculated. Status may be:\n * `success` a path has been found\n * `partial` a partial path has been found, computations will continue next tick\n * `timeout` timed out\n * `noPath` no path was found\n\n### goal_updated\nCalled whenever a new goal is assigned to the pathfinder.\n\n### path_reset\nCalled when the path is reset, with a reason:\n * `goal_updated`\n * `movements_updated`\n * `block_updated`\n * `chunk_loaded`\n * `goal_moved`\n * `dig_error`\n * `no_scaffolding_blocks`\n * `place_error`\n * `stuck`\n\n ### path_stop\n Called when the pathing has been stopped by `bot.pathfinder.stop()`\n\n# Goals:\n\n### Goal\nAbstract Goal class. Do not instantiate this class. Instead extend it to make a new Goal class.\n\nHas abstract methods:\n - `heuristic(node)`\n   * `node` - A path node\n   * Returns a heuristic number value for a given node. Must be admissible – meaning that it never overestimates the actual cost to get to the goal.\n - `isEnd(node)`\n   * `node`\n   * Returns a boolean value if the given node is a end node. \n\nImplements default methods for:\n - `isValid()`\n   * Always returns `true`\n - `hasChanged(node)`\n   * `node` - A path node\n   * Always returns `false`\n\n### GoalBlock(x, y, z)\nOne specific block that the player should stand inside at foot level\n * `x` - Integer\n * `y` - Integer\n * `z` - Integer\n\n### GoalNear(x, y, z, range)\nA block position that the player should get within a certain radius of\n * `x` - Integer\n * `y` - Integer\n * `z` - Integer\n * `range` - Integer\n \n### GoalXZ(x, z)\nUseful for long-range goals that don't have a specific Y level\n * `x` - Integer\n * `z` - Integer\n\n### GoalNearXZ(x, z, range)\nUseful for finding builds that you don't have an exact Y level for, just an approximate X and Z level.\n * `x` - Integer\n * `z` - Integer\n * `range` - Integer\n\n### GoalY(y)\nGet to a Y level.\n * `y` - Integer\n\n\n### GoalGetToBlock(x, y, z)\nDon't get into the block, but get directly adjacent to it. Useful for chests.\n * `x` - Integer\n * `y` - Integer\n * `z` - Integer\n\n### GoalCompositeAny(Array\\\u003cGoal\u003e?)\nA composite of many goals, any one of which satisfies the composite.\nFor example, a GoalCompositeAny of block goals for every oak log in loaded\nchunks would result in it pathing to the easiest oak log to get to.\n * `Array` - Array of goals\n\n### GoalCompositeAll(Array\\\u003cGoal\u003e?)\nA composite of multiple goals, requiring all of them to be satisfied.\n * `Array` - Array of goals\n\n### GoalInvert(goal)\nInverts the goal.\n * `goal` - Goal to invert\n\n### GoalFollow(entity, range)\nFollows an entity.\n * `entity` - Entity instance\n * `range` - Integer\n\n### GoalPlaceBlock(pos, world, options)\nPosition the bot in order to place a block.\n * `pos` - Vec3 the position of the placed block\n * `world` - the world of the bot (Can be accessed with `bot.world`)\n * `options` - object containing all optionals properties:\n   * `range` - maximum distance from the clicked face\n   * `faces` - the directions of the faces the player can click\n   * `facing` - the direction the player must be facing\n   * `facing3D` - boolean, facing is 3D (true) or 2D (false)\n   * `half` - `top` or `bottom`, the half that must be clicked\n\n ### GoalLookAtBlock(pos, world, options = {})\n Path into a position were a blockface of block at pos is visible. Fourth argument is optional and contains extra options.\n  * `pos` - Vec3 the block position to look at\n  * `world` - the world of the bot (Can be accessed with `bot.world`)\n  * `options` - object containing all optionals properties:\n    * `reach` - number maximum distance from the clicked face. Default `4.5`\n    * `entityHeight` - number Default is `1.6`\n\n ### GoalBreakBlock(x, y, z, bot, options)\n Deprecated. Wrapper for GoalLookAtBlock. Use GoalLookAtBlock instead.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprismarinejs%2Fmineflayer-pathfinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprismarinejs%2Fmineflayer-pathfinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprismarinejs%2Fmineflayer-pathfinder/lists"}