• astar.new_map_id()
• astar.delete_map()
• astar.setup()
• astar.use_zero()
• astar.set_map_type()
• astar.set_map()
• astar.map_vflip()
• astar.map_hflip()
• astar.set_costs()
• astar.set_entities()
• astar.use_entities()
• astar.get_at()
• astar.set_at()
• astar.print_map()
• astar.solve()
• astar.solve_near()
• astar.reset_cache()
• astar.reset()

If you want to support multi-maps, you should create a new map ID to pass to the relevant functions. For single maps, no action is required.

RETURN

• map_id (uint16) - New map ID

This method removes everything related to the map_id and frees the memory.

PARAMETERS

• map_id (uint16) – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

Initial setup. You have to setup the astar before calling any other methods.

PARAMETERS

• map_width (uint16) - Width of your map. This is generally width of your tilemap.

• map_height (uint16) - Height of your map. This is generally height of your tilemap.

• direction (enum) - 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 (uint16) - How many states should be internally allocated at a time. This can be hard to get correct. The higher the value, the more memory Pathfinder 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 (uint16) - 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 (bool)[optional] - 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 (bool)[optional] - 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 (bool)[optional] - 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 (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

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 use_zero = false -- Optional. Default is false = 1 based
local flip_map = false -- Optional. Default is false

astar.setup(map_width, map_height, direction, allocate, typical_adjacent, cache, use_zero, flip_map)

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

PARAMETERS

• toggle (bool) - true/false
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

astar.use_zero(false)

You can set different type of map coordinates. Default is astar.GRID_CLASSIC.

More information about hexagonal grid offset coordinates systems: Red Blob Games

PARAMETERS

• type (enum) - Type of the map coordinates.

  astar.GRID_CLASSIC : classic grid.
  astar.HEX_ODDR : odd-r hexagonal grid.
  astar.HEX_EVENR : even-r hexagonal grid.
  astar.HEX_ODDQ : odd-q hexagonal grid.
  astar.HEX_EVENQ : even-q hexagonal grid.

• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

astar.set_map_type(astar.HEX_ODDR)

Set your map data.
0.0 or 1.1 is top-left.

*Setting new map data reset the current cache.

PARAMETERS

• world (table) - Your tilemap data. Keep it simple as much as you can.
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

local world = {
	2, 0, 0, 0, 0,
	0, 0, 0, 0, 0,
	0, 0, 1, 0, 0,
	1, 0, 0, 0, 2,
}

astar.set_map(world)

Every time you call this function, it flips the map vertically. This does not flip the coordinates

*Flipping the map reset the current cache.

PARAMETERS

• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

local world = {
	2, 0, 0, 0, 0,
	0, 0, 0, 0, 0,
	0, 0, 1, 0, 0,
	1, 0, 0, 0, 2,
}

astar.set_map(world)
astar.map_vflip()
astar.print_map()

Every time you call this function, it flips the map horizontally. This does not flip the coordinates

*Flipping the map reset the current cache.

PARAMETERS

• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

local world = {
	2, 0, 0, 0, 0,
	0, 0, 0, 0, 0,
	0, 0, 1, 0, 0,
	1, 0, 0, 0, 2,
}

astar.set_map(world)
astar.map_hflip()
astar.print_map()

Set costs for your passable tiles on your world table. This table keys determines the passable area. In this example only numbered "0" tiles are passable.

Table's sum must be the astar.DIRECTION_FOUR (4) or astar.DIRECTION_EIGHT (8). In this example we want to move 8 direction.

*Setting new cost data reset the current cache.

PARAMETERS

• costs (table) - Your tile cost data.
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

-- For astar.DIRECTION_EIGHT
local costs = {
    [0] = {
        1.0, -- E
        1.0, -- N
        1.0, -- W
        1.0, -- S
        1.41, -- NE
        1.41, -- NW
        1.41, -- SW
        1.41 -- SE
    }
}

astar.set_costs(costs)
-- OR
-- For astar.DIRECTION_FOUR
local costs = {
    [0] = {
        1.0, -- E
        1.0, -- N
        1.0, -- W
        1.0 -- S
    }
}

astar.set_costs(costs)

Entities are usually not passable items like enemies or chests. You might want to target those tiles but also want to keep them not passable. You can set those entity ids as table. Your world table should contain those entities.

You have to toggle astar.use_entities() before calling astar.solve() or astar.solve_near().

PARAMETERS

• entities (table) - Your entities data.
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

-- IDs of the entities
local entities = {
	1, 2
}

astar.set_entities(entities)

If you want to include your entities to your solve operations, you have to set it true before calling astar.solve() or astar.solve_near().

If set the true:

astar.solve() only includes the end/last target tile to the path result. Other entities along the path stays as not passable.

astar.solve_near() includes all entities from entities table.

*When you call the astar.use_entities(), the current cache will be reset.

PARAMETERS

• toggle (boolean) - Toggle true or false. Default is false
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

-- IDs of the entities
local entities = {
	1, 2
}

astar.set_entities(entities)
astar.use_entities(true)

Returns the value from the map array by coordinates.

PARAMETERS

X, Y of the tile position on array not the screen position.

• x (int) - Tile X
• y (int) - Tile Y
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

RETURN

• value (int)

EXAMPLE

local value = astar.get_at(1, 1)

print(value)

Set your value to the map array by coordinates.

*Setting new data reset the current cache.

PARAMETERS

X, Y of the tile position on array not the screen position.

• x (int) - Tile X
• y (int) - Tile Y
• value (int)
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

astar.set_at(1, 1, 0) 

Prints the map state for debug purposes.

PARAMETERS

• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

astar.print_map()

cols/x:
1	2	3	4	5	
-	-	-	-	-	
2	0	0	0	0		- row/y: 1
0	0	0	0	0		- row/y: 2
0	0	1	0	0		- row/y: 3
1	0	0	0	2		- row/y: 4

Solves the path.

PARAMETERS

X, Y of the tile position on array not the screen position.

• start_x (int) - Start tile X
• start_y (int) - Start tile Y
• end_x (int) - End tile X
• end_y (int) - End tile Y
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

RETURN

• status (enum) -

  astar.SOLVED: Path solved
  astar.NO_SOLUTION: Can't find the path
  astar.START_END_SAME: Start and End is the same

• size (int) - Size of the path.

• total_cost (int) - Total cost of the path

• path (table) - Table with x, y coordinates and tile ID. First value is the given start point.

EXAMPLE

local start_x = 1
local start_y = 1
local end_x = 3
local end_y = 3

local status, size, total_cost, path = astar.solve(start_x, start_y, end_x, end_y)

if status == astar.SOLVED then
	print("SOLVED")
	print("Path Size", size)
	print("Total Cost:", total_cost)

	for _, tile in ipairs(path) do
		print("x:", tile.x, "y: ", tile.y, "tile ID: ", tile.id)
	end
elseif status == astar.NO_SOLUTION then
	print("NO_SOLUTION")
elseif status == astar.START_END_SAME then
	print("START_END_SAME")
end

Finds the neighbours according to given cost.

PARAMETERS

• start_x (int) - Start tile X
• start_y (int) - Start tile Y
• max_cost (float) - Maximun cost for finding neighbours
• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

RETURN

• near_status (enum) -

  astar.SOLVED: Path solved
  astar.NO_SOLUTION: Can't find the path
  astar.START_END_SAME: Start and End is the same

• near_size (int) - Size of the found neighbours.

• nears (table) - Table with x and y coordinates. First value is the given start point.

EXAMPLE

local start_x = 1
local start_y = 1
local max_cost = 3.0 -- near

local near_status, near_size, nears = astar.solve_near(start_x, start_y, max_cost)

if near_status == astar.SOLVED then
	print("NEAR SOLVED")
	print("Near Size:", near_size)
	for _, tile in ipairs(nears) do
		print("x:", tile.x, "y: ", tile.y, "tile ID: ", tile.id)
	end
elseif near_status == astar.NO_SOLUTION then
	print("NO_SOLUTION")
elseif near_status == astar.START_END_SAME then
	print("START_END_SAME")
end

If your state space is huge, occasionally call astar.reset_cache() to free unused memory.

PARAMETERS

• map_id (uint16) [optional] – The associated map ID generated by astar.new_map_id(), used only for multi-map support.

EXAMPLE

astar.reset_cache()

This method removes everything related to astar library and frees the memory. It may be used when the player completes/exits the level/game.

EXAMPLE

astar.reset()