selimanac/defold-astar/astar
A* Path Finding
- GitHub: selimanac/defold-astar — pinned to
v1.2.3(released while Defold 1.12.3 was current)- Pick a release from selimanac/defold-astar releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as astar from "astar"
- Pick a release from selimanac/defold-astar releases and add its Source code (zip) URL (or a packaged
- Asset Portal: defold-astar
Functions
astar.new_map_id(): numberastar.delete_map(map_id: number)astar.setup(map_width: number, map_height: number, direction: number, allocate: number, typical_adjacent: number, cache[optional]: boolean, use_zero[optional]: boolean, map_vflip[optional]: boolean, map_id[optional]: number)astar.set_map(world: table, map_id[optional]: number)astar.set_costs(costs: table, map_id[optional]: number)astar.solve(start_x: number, start_y: number, end_x: number, end_y: number, map_id[optional]: number): LuaMultiReturn<[number, number, number, table]>astar.solve_near(start_x: number, start_y: number, max_cost: number, map_id[optional]: number): LuaMultiReturn<[number, number, table]>astar.reset_cache(map_id[optional]: number)astar.get_at(x: number, y: number, map_id[optional]: number): numberastar.set_at(x: number, y: number, value: number, map_id[optional]: number)
astar.new_map_id(): number
Get a new self-incrementing map_id.
Returns
map_id:number— ID of a new map.
astar.delete_map(map_id: number)
Delete a map by its ID. This will free the memory used by the map.
Parameters
map_id:number— ID of the map to delete. Has to be an integer from 0 to 2^16 - 1.
astar.setup(map_width: number, map_height: number, direction: number, allocate: number, typical_adjacent: number, cache[optional]: boolean, use_zero[optional]: boolean, map_vflip[optional]: boolean, map_id[optional]: number)
Initial setup. You have to setup the astar before calling any other methods.
local map_width = 5
local map_height = 4
local direction = astar.DIRECTION_EIGHT
local allocate = map_width * map_height
local typical_adjacent = 8
local cache = true -- Optional. Default is true
local flip_map = false -- Optional. Default is false
astar.setup("my_map", map_width, map_height, direction, allocate, typical_adjacent, cache, flip_map)Parameters
map_width:number— Width of your map. This is generally width of your tilemap.map_height:number— Height of your map. This is generally width of your tilemap.direction:number— Movement direction (astar.DIRECTION_FOUR or astar.DIRECTION_EIGHT)astar.DIRECTION_FOUR- on a square grid that allows 4 directions of movement using Manhattan distance.astar.DIRECTION_EIGHT- on a square grid that allows 8 directions of movement using Euclidean distance.allocate:number— How many states should be internally allocated at a time. This can be hard to get correct. The higher the value, the more memory Patfinder will use.- If you have a small map (a few thousand states?) it may make sense to pass in the maximum value. This will cache everything, and MicroPather will only need one main memory allocation. For a chess board, allocate would be set to 8x8 (64)
- If your map is large, something like 1/4 the number of possible states is good.
- If your state space is huge, use a multiple (5-10x) of the normal path. "Occasionally" call
astar.reset_cache()to free unused memory.
typical_adjacent:number— Used to determine cache size. The typical number of adjacent states to a given state. (On a chessboard, 8.) Higher values use a little more memory.cache[optional]:boolean— Turn on path caching. Uses more memory (yet again) but at a huge speed advantage if you may call the pather with the same path or sub-path, which is common for pathing over maps in games. Default istrueuse_zero[optional]:boolean— Toggle start index 0 or 1 for tables and tile positions. Also you can set it by callastar.use_zero(). Default isfalsemap_vflip[optional]:boolean— Flips the map vertically. This doesn't flip the coordinates. Also you can set it by callastar.map_vflip(). Default isfalsemap_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
astar.set_map(world: table, map_id[optional]: number)
Set your map data.
- Setting new map data reset the current cache.
Parameters
world:table— Your tilemap data. Keep it simple as much as you can.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
astar.set_costs(costs: table, map_id[optional]: number)
Set costs for walkable tiles on your world table. This table keys determine the walkable area.
Table's sum must be the astar.DIRECTION_FOUR or astar.DIRECTION_EIGHT.
Parameters
costs:table— Table of costs for directions.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
astar.solve(start_x: number, start_y: number, end_x: number, end_y: number, map_id[optional]: number): LuaMultiReturn<[number, number, number, table]>
Solves the path.
Parameters
start_x:number— Start tile X.start_y:number— Start tile Y.end_x:number— End tile X.end_y:number— End tile Y.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
Returns
result:number— Result code (astar.SOLVED,astar.NO_SOLUTION,astar.START_END_SAME).size:number— Size of the path.total_cost:number— Total cost of the path.path:table— Table with x and y coordinates. First value is the given start point.
astar.solve_near(start_x: number, start_y: number, max_cost: number, map_id[optional]: number): LuaMultiReturn<[number, number, table]>
Finds the neighbours according to a given cost.
Parameters
start_x:number— Start tile X.start_y:number— Start tile Y.max_cost:number— Maximum cost for finding neighbours.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
Returns
near_result:number— Result code (astar.SOLVED,astar.NO_SOLUTION,astar.START_END_SAME).near_size:number— Size of the found neighbours.nears:table— Table with x and y coordinates. First value is the given start point.
astar.reset_cache(map_id[optional]: number)
If your state space is huge, occasionally call astar.reset_cache() to free unused memory.
Parameters
map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
astar.get_at(x: number, y: number, map_id[optional]: number): number
Returns the value from the map array by coordinates.
Parameters
x:number— Tile X.y:number— Tile Y.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
Returns
value:number— The value at the specified coordinates.
astar.set_at(x: number, y: number, value: number, map_id[optional]: number)
Set your value to the map array by coordinates.
Parameters
x:number— Tile X.y:number— Tile Y.value:number— The value to set.map_id[optional]:number— ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is0.
Constants
astar.use_zero
Toggle start index 0 or 1 for tables and tile positions.
If set to false, astar.solve, astar.solve_near, astar.get_at, astar.set_at methods expect positions start with 1 and returns table indexes from 1.
Default is false = 1
astar.SOLVED
Represents a solved path result.
astar.NO_SOLUTION
Represents a result where no path is found.
astar.START_END_SAME
Represents a result where the start and end points are the same.
astar.DIRECTION_FOUR
Represents the four-direction movement option.
astar.DIRECTION_EIGHT
Represents the eight-direction movement option.