99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# `rp_pathfinder` API
|
|
|
|
This file explains how to use the `rp_pathfinder` pathfinder. You use it
|
|
by calling `rp_pathfinder.find_path`.
|
|
|
|
## `rp_pathfinder.find_path(pos1, pos2, searchdistance, options, timeout)`
|
|
|
|
Finds the shortest path to walk on between two positions, using the A* algorithm.
|
|
Walks on 'walkable' nodes while avoiding 'blocked' nodes and simulates
|
|
jumps and drops (like a player would do). There are many options to customize
|
|
the search.
|
|
|
|
Nodes that are 'walkable' and have node damage are considered 'blocked'.
|
|
|
|
By default, the search walks through nodes along the 4 cardinal directions,
|
|
does not check for height clearance, ignores climbable nodes, `disable_jump`
|
|
restrictions and does not cut corners.
|
|
|
|
### Parameters
|
|
|
|
* `pos1`: start position
|
|
* `pos2`: target position
|
|
* `searchdistance`: maximum distance from the search positions to search in.
|
|
In detail: Path must be completely inside a cuboid. The minimum
|
|
`searchdistance` of 1 will confine search between `pos1` and `pos2`.
|
|
Larger values will increase the size of this cuboid in all directions.
|
|
* `options`: Table to specify pathfinding options (each of these is optional):
|
|
* `max_jump`: Maximum allowed nodes to jump (default: 0)
|
|
* `max_drop`: Maximum allowed nodes to fall (default: 0)
|
|
* `climb`: If true, can climb climbable nodes up and down (default: false)
|
|
* `respect_climb_restriction`: If true, will respect `disable_jump` and `disable_descend`
|
|
at climbable nodes (default: true)
|
|
* `respect_disable_jump`: If true, can't jump at nodes with `disable_jump` group (default: false)
|
|
* `clear_height`: How many consecutive nodes stacked on top of each other need
|
|
to be 'passable' at each path position. At 1 (default), can walk through any 1-node high
|
|
hole in the wall, at 2, the holes need to be at least 2 nodes tall, and so on. Useful
|
|
to find paths for tall mobs.
|
|
* `handler_walkable`: A function that takes a node table and returns
|
|
true if the node can be walked on top
|
|
(default: all nodes with `walkable=true` are walkable)
|
|
* `handler_blocking`: A function that takes a node table and returns
|
|
true if the node shall block the path
|
|
(default: same as `handler_walkable`)
|
|
* `handler_climbable`: A function that takes a node table and returns
|
|
true if the node is considered climable
|
|
(default: if `climbing` field of node is true)
|
|
* `use_vmanip`: If true, nodes will be queried using a LuaVoxelManip;
|
|
otherwise, `minetest.get_node` will be used. Required for async
|
|
usage.
|
|
* `vmanip`: Only neccessary for asyn usage. Optionally pass a
|
|
pre-generated LuaVoxelManip object for the corresponding `pos1`,
|
|
`pos2` and `searchdistance` arguments. Use the return value of
|
|
`rp_pathfinder.get_voxelmanip_for_path` here.
|
|
If this is `nil` and `use_vmanip` is `true`, the LuaVoxelManip object will
|
|
be generated on the fly.
|
|
* `timeout`: Abort search if pathfinder ran for longer than this time (in seconds)
|
|
|
|
### Return value
|
|
|
|
On success, returns a list of positions of the path.
|
|
|
|
On failure, returns `nil, <reason>`, where `<reason>` is one of:
|
|
|
|
* `"no_path"`: No path exists within the searched area
|
|
* `"pos1_blocked"`: The node at `pos1` is blocked
|
|
* `"pos2_blocked"`: The node at `pos2` is blocked
|
|
* `"pos1_too_high"`: The node at `pos1` is too high above the floor
|
|
* `"path_complexity_reached"`: The path search became too complex
|
|
* `"timeout"`: Search was aborted because the time ran out
|
|
|
|
### Asynchronous usage
|
|
|
|
By default, this function can not be called in an async environment because it keeps calling `minetest.get_node`,
|
|
which is not permitted. To use the pathfinder asynchronously, you need to do the following:
|
|
|
|
* Register `init.lua` of this mod with `minetest.register_async_dofile`
|
|
* In the global environment, call `rp_pathfinder.get_voxelmanip_for_path`
|
|
and store the return value
|
|
* For the `options` of `rp_pathfinder.find_path` set `use_vmanip=true`
|
|
and `vmanip=<the previously stored value>`
|
|
* In the async environment, call `rp_pathfinder.find_path`
|
|
* Note: `pos1`, `pos2` and `searchdistance` **MUST** be equal for both function calls
|
|
|
|
### Performance notes
|
|
|
|
This function is less performant than the built-in `A*` pathfinder from Minetest,
|
|
but it has more features.
|
|
|
|
For long-distance destinations, calling this function asynchronously is a good idea so the lowered
|
|
performance doesn't lock up the server.
|
|
|
|
|
|
## `rp_pathfinder.get_voxelmanip_for_path(pos1, pos2, searchdistance)`
|
|
|
|
Returns a LuaVoxelManip object for a path between `pos1` and `pos2` and the given
|
|
`searchdistance`. Required function for asynchronous usage.
|
|
|
|
The parameters mean the same as for `rp_pathfinder.find_path`.
|