Skip to Content
defold-typescript libraries
selimanac

selimanac/defold-astar/astar

A* Path Finding

  • GitHub: selimanac/defold-astar — pinned to v1.2.3 (released while Defold 1.12.3 was current)
    1. Pick a release from selimanac/defold-astar releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as astar from "astar"
  • Asset Portal: defold-astar

Functions

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 is true
  • use_zero[optional]: boolean — Toggle start index 0 or 1 for tables and tile positions. Also you can set it by call astar.use_zero(). Default is false
  • map_vflip[optional]: boolean — Flips the map vertically. This doesn't flip the coordinates. Also you can set it by call astar.map_vflip(). Default is false
  • map_id[optional]: number — ID of the map. Has to be an integer from 0 to 2^16 - 1. Default is 0.

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 is 0.

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 is 0.

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 is 0.

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 is 0.

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 is 0.

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 is 0.

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 is 0.

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.

On this page