Classes
class	Cost
class	Info

Public Member Functions
function	InitializePath (sources, goals, ignored_tiles=[])
	Initialize a path search between sources and goals.
function	FindPath (iterations)
	Try to find the path as indicated with InitializePath with the lowest cost.
function	PresetOriginal ()
	The settings in the original (v3) pathfinder by NoAI Team.
function	PresetPerfectPath ()
	Good preset for reusing existing roads.
function	PresetQuickAndDirty ()
	Quick but messy preset.
function	PresetCheckExisting ()
	Preset that only uses existing roads.
function	PresetStreetcar ()
	Reserved.
function	GetBuildCost ()
	Cost to build found path.
function	BuildPath ()
	Build the found path.
function	LoadPath ()
	Load an existing path.
function	GetPath ()
	Export the found path.
function	GetPathLength ()
	Get the length of the found path.
function	InitializePathOnTowns ()
	Initializes the pathfinder using two towns.
function	PathToTilePairs ()
	Get the found path as tile pairs.
function	PathToTiles ()
	Get a list of all the tiles in the path.
function	TilePairsToBuild ()
	Tiles in the path that need to be built.

Private Member Functions
	constructor ()
function	_GetBridgeNumSlopes (end_a, end_b)
function	_Cost (self, path, new_tile, new_direction)
function	_Estimate (self, cur_tile, cur_direction, goal_tiles)
function	_Neighbours (self, path, cur_node)
function	_CheckDirection (self, tile, existing_direction, new_direction)
function	_GetDirection (from, to, is_bridge)
function	_GetTunnelsBridges (last_node, cur_node, bridge_dir)
function	_IsSlopedRoad (start, middle, end)
function	_CheckTunnelBridge (current_tile, new_tile)

Private Attributes
	_aystar_class = import("graph.aystar", "", 6)
	_max_cost = null
	The maximum cost for a route.
	_cost_tile = null
	The cost for a single tile.
	_cost_no_existing_road = null
	The cost that is added to _cost_tile if no road exists yet.
	_cost_turn = null
	The cost that is added to _cost_tile if the direction changes.
	_cost_slope = null
	The extra cost if a road tile is sloped.
	_cost_bridge_per_tile = null
	The cost per tile of a new bridge, this is added to _cost_tile.
	_cost_tunnel_per_tile = null
	The cost per tile of a new tunnel, this is added to _cost_tile.
	_cost_coast = null
	The extra cost for a coast tile.
	_cost_level_crossing = null
	the extra cost for rail/road level crossings.
	_cost_drivethru_station = null
	The extra cost for drive-thru road stations.
	_pathfinder = null
	A reference to the used AyStar object.
	_max_bridge_length = null
	The maximum length of a bridge that will be build.
	_max_tunnel_length = null
	The maximum length of a tunnel that will be build.
	_cost_only_existing_roads = null
	Choose whether to only search through existing connected roads.
	_distance_penalty = null
	Penalty to use to speed up pathfinder, 1 is no penalty.
	_road_type = null
	cost = null
	Used to change the costs.
	_my_path = null
	Used to store the path after it's been found for Building functions.
	_running = null
	info = null

Detailed Description

Note: This file is licensed under the original license – LGPL v2.1 – and is based on the NoAI Team's Road Pathfinder v3.

\brief      A Road Pathfinder (and extras)

Version: v.10 (2025-07-15)

Author: NoAI Team; W. Minchin (MinchinWeb)

Since: MetaLibrary v.1

This road pathfinder tries to find a buildable / existing route for road vehicles. You can changes the costs below using for example roadpf.cost.turn = 30. Note that it's not allowed to change the cost between consecutive calls to FindPath. You can change the cost before the first call to FindPath and after FindPath has returned an actual route. To use only existing roads, set roadpf.cost.only_existing_road = True.

The pathfinder has been extended to provide 'presets' for configuration, store the found path, and build the found path.

Depends On:\n Graph.AyStar v6

See also: _MinchinWeb_DLS_; _MinchinWeb_ShipPathfinder_

Todo

upgrade slow bridges along path

convert existing level crossings (road/rail) to road bridge

do something about one-way roads - build a pair? route around?

if(AIRoad.AreRoadTilesConnected(new_tile, prev_tile) && !AIRoad.AreRoadTilesConnected(prev_tile, new_tile))

Todo

allow pre-building of tunnels and bridges

Add example usage code.

Definition at line 83 of file Pathfinder.Road.nut.

Member Function Documentation

◆ _CheckDirection()

function _MinchinWeb_RoadPathfinder_::_CheckDirection	(	self	,
		tile	,
		existing_direction	,
		new_direction	)

private

Definition at line 522 of file Pathfinder.Road.nut.

◆ _CheckTunnelBridge()

function _MinchinWeb_RoadPathfinder_::_CheckTunnelBridge	(	current_tile	,
		new_tile	)

private

Definition at line 606 of file Pathfinder.Road.nut.

◆ _Cost()

function _MinchinWeb_RoadPathfinder_::_Cost	(	self	,
		path	,
		new_tile	,
		new_direction	)

private

Definition at line 365 of file Pathfinder.Road.nut.

◆ _Estimate()

function _MinchinWeb_RoadPathfinder_::_Estimate	(	self	,
		cur_tile	,
		cur_direction	,
		goal_tiles	)

private

Definition at line 437 of file Pathfinder.Road.nut.

◆ _GetBridgeNumSlopes()

function _MinchinWeb_RoadPathfinder_::_GetBridgeNumSlopes	(	end_a	,
		end_b	)

private

Definition at line 345 of file Pathfinder.Road.nut.

◆ _GetDirection()

function _MinchinWeb_RoadPathfinder_::_GetDirection	(	from	,
		to	,
		is_bridge	)

private

Definition at line 526 of file Pathfinder.Road.nut.

◆ _GetTunnelsBridges()

function _MinchinWeb_RoadPathfinder_::_GetTunnelsBridges	(	last_node	,
		cur_node	,
		bridge_dir	)

private

Get a list of all bridges and tunnels that can be build from the current tile. Bridges will only be build starting on non-flat tiles for performance reasons. Tunnels will only be build if no terraforming is needed on both ends.

Definition at line 551 of file Pathfinder.Road.nut.

◆ _IsSlopedRoad()

function _MinchinWeb_RoadPathfinder_::_IsSlopedRoad	(	start	,
		middle	,
		end	)

private

Definition at line 578 of file Pathfinder.Road.nut.

◆ _Neighbours()

function _MinchinWeb_RoadPathfinder_::_Neighbours	(	self	,
		path	,
		cur_node	)

private

Definition at line 447 of file Pathfinder.Road.nut.

◆ BuildPath()

function _MinchinWeb_RoadPathfinder_::BuildPath ( )

Build the found path.

See also: BuildPath()

Definition at line 832 of file Pathfinder.Road.nut.

◆ constructor()

_MinchinWeb_RoadPathfinder_::constructor ( )

inlineprivate

Definition at line 107 of file Pathfinder.Road.nut.

◆ FindPath()

function _MinchinWeb_RoadPathfinder_::FindPath ( iterations )

Try to find the path as indicated with InitializePath with the lowest cost.

Parameters

iterations After how many iterations it should abort for a moment. This value should either be -1 for infinite, or > 0. Any other value aborts immediately and will never find a path.

Returns: A route if one was found, or false if the amount of iterations was reached, or null if no path was found. You can call this function over and over as long as it returns false, which is an indication it is not yet done looking for a route.

See also: AyStar::FindPath()

Definition at line 337 of file Pathfinder.Road.nut.

◆ GetBuildCost()

function _MinchinWeb_RoadPathfinder_::GetBuildCost ( )

Cost to build found path.

Turns to 'test mode,' builds the route provided, and returns the cost.

Note: All money for AI's is in British Pounds.; Due to inflation, this value can get stale

Returns: Cost to build path; False if the test build fails somewhere

Definition at line 753 of file Pathfinder.Road.nut.

◆ GetPath()

function _MinchinWeb_RoadPathfinder_::GetPath ( )

Export the found path.

Returns: The path stored by the pathfinder

See also: GetPath(); BuildPath()

Definition at line 924 of file Pathfinder.Road.nut.

◆ GetPathLength()

function _MinchinWeb_RoadPathfinder_::GetPathLength ( )

Get the length of the found path.

Runs over the path to determine its length.

Returns: The length of the path in tiles.

See also: LoadPath()

Definition at line 933 of file Pathfinder.Road.nut.

◆ InitializePath()

function _MinchinWeb_RoadPathfinder_::InitializePath	(	sources	,
		goals	,
		ignored_tiles	= [] )

inline

Initialize a path search between sources and goals.

Parameters

sources	The source tiles.
goals	The target tiles.
ignored_tiles	Tiles not to use in generating the path. "An array of tiles that cannot occur in the final path."

See also: AyStar::InitializePath(); InitializePathOnTowns()

Definition at line 142 of file Pathfinder.Road.nut.

◆ InitializePathOnTowns()

function _MinchinWeb_RoadPathfinder_::InitializePathOnTowns ( )

Initializes the pathfinder using two towns.

Note: Assumes that the town centres are road tiles. If this is not the case, the pathfinder will still run, but it will take a long time and eventually fail to return a path. This is generally not an issue because on map creation the centre of town will be a road tile.

See also: InitializePath()

Definition at line 947 of file Pathfinder.Road.nut.

◆ LoadPath()

function _MinchinWeb_RoadPathfinder_::LoadPath ( )

Load an existing path.

'Loads' a path to allow GetBuildCost(), BuildPath() and GetPathLength() to be used.

See also: GetBuildCost(); FindPath()

Definition at line 914 of file Pathfinder.Road.nut.

◆ PathToTilePairs()

function _MinchinWeb_RoadPathfinder_::PathToTilePairs ( )

Get the found path as tile pairs.

Returns: 2D array that has each pair of tiles that path joins.

See also: TilePairsToBuild(); PathToTiles()

Definition at line 955 of file Pathfinder.Road.nut.

◆ PathToTiles()

function _MinchinWeb_RoadPathfinder_::PathToTiles ( )

Get a list of all the tiles in the path.

Returns: 1D array that has each pair of tiles that path covers.

See also: PathToTilePairs()

Definition at line 981 of file Pathfinder.Road.nut.

◆ PresetCheckExisting()

function _MinchinWeb_RoadPathfinder_::PresetCheckExisting ( )

Preset that only uses existing roads.

Based on PerfectPath, but uses only existing roads. Useful for checking if there an existing route and how long it is.

Definition at line 725 of file Pathfinder.Road.nut.

◆ PresetOriginal()

function _MinchinWeb_RoadPathfinder_::PresetOriginal ( )

The settings in the original (v3) pathfinder by NoAI Team.

◆ PresetPerfectPath()

function _MinchinWeb_RoadPathfinder_::PresetPerfectPath ( )

Good preset for reusing existing roads.

My slightly updated version of PresetOriginal().

Definition at line 681 of file Pathfinder.Road.nut.

◆ PresetQuickAndDirty()

function _MinchinWeb_RoadPathfinder_::PresetQuickAndDirty ( )

Quick but messy preset.

Runs in as little as 5% of the time of PresetPerfectPath(), but builds odd bridges and loops.

Definition at line 702 of file Pathfinder.Road.nut.

◆ PresetStreetcar()

function _MinchinWeb_RoadPathfinder_::PresetStreetcar ( )

Reserved.

Reserved preset for future use for intraurban tram lines.

Definition at line 746 of file Pathfinder.Road.nut.

◆ TilePairsToBuild()

function _MinchinWeb_RoadPathfinder_::TilePairsToBuild ( )

Tiles in the path that need to be built.

Similar to PathToTilePairs(), but only returns those pairs where there isn't a current road connection.

Returns: 2D array that has each pair of tiles that path joins that are not currently joined by road.

See also: BuildPath()

Definition at line 1003 of file Pathfinder.Road.nut.

Member Data Documentation

◆ _aystar_class

_MinchinWeb_RoadPathfinder_::_aystar_class = import("graph.aystar", "", 6)

private

Definition at line 84 of file Pathfinder.Road.nut.

◆ _cost_bridge_per_tile

_MinchinWeb_RoadPathfinder_::_cost_bridge_per_tile = null

private

The cost per tile of a new bridge, this is added to _cost_tile.

Definition at line 90 of file Pathfinder.Road.nut.

◆ _cost_coast

_MinchinWeb_RoadPathfinder_::_cost_coast = null

private

The extra cost for a coast tile.

Definition at line 92 of file Pathfinder.Road.nut.

◆ _cost_drivethru_station

_MinchinWeb_RoadPathfinder_::_cost_drivethru_station = null

private

The extra cost for drive-thru road stations.

Definition at line 94 of file Pathfinder.Road.nut.

◆ _cost_level_crossing

_MinchinWeb_RoadPathfinder_::_cost_level_crossing = null

private

the extra cost for rail/road level crossings.

Definition at line 93 of file Pathfinder.Road.nut.

◆ _cost_no_existing_road

_MinchinWeb_RoadPathfinder_::_cost_no_existing_road = null

private

The cost that is added to _cost_tile if no road exists yet.

Definition at line 87 of file Pathfinder.Road.nut.

◆ _cost_only_existing_roads

_MinchinWeb_RoadPathfinder_::_cost_only_existing_roads = null

private

Choose whether to only search through existing connected roads.

Definition at line 98 of file Pathfinder.Road.nut.

◆ _cost_slope

_MinchinWeb_RoadPathfinder_::_cost_slope = null

private

The extra cost if a road tile is sloped.

Definition at line 89 of file Pathfinder.Road.nut.

◆ _cost_tile

_MinchinWeb_RoadPathfinder_::_cost_tile = null

private

The cost for a single tile.

Definition at line 86 of file Pathfinder.Road.nut.

◆ _cost_tunnel_per_tile

_MinchinWeb_RoadPathfinder_::_cost_tunnel_per_tile = null

private

The cost per tile of a new tunnel, this is added to _cost_tile.

Definition at line 91 of file Pathfinder.Road.nut.

◆ _cost_turn

_MinchinWeb_RoadPathfinder_::_cost_turn = null

private

The cost that is added to _cost_tile if the direction changes.

Definition at line 88 of file Pathfinder.Road.nut.

◆ _distance_penalty

_MinchinWeb_RoadPathfinder_::_distance_penalty = null

private

Penalty to use to speed up pathfinder, 1 is no penalty.

Definition at line 99 of file Pathfinder.Road.nut.

◆ _max_bridge_length

_MinchinWeb_RoadPathfinder_::_max_bridge_length = null

private

The maximum length of a bridge that will be build.

Definition at line 96 of file Pathfinder.Road.nut.

◆ _max_cost

_MinchinWeb_RoadPathfinder_::_max_cost = null

private

The maximum cost for a route.

Definition at line 85 of file Pathfinder.Road.nut.

◆ _max_tunnel_length

_MinchinWeb_RoadPathfinder_::_max_tunnel_length = null

private

The maximum length of a tunnel that will be build.

Definition at line 97 of file Pathfinder.Road.nut.

◆ _my_path

_MinchinWeb_RoadPathfinder_::_my_path = null

private

Used to store the path after it's been found for Building functions.

Definition at line 102 of file Pathfinder.Road.nut.

◆ _pathfinder

_MinchinWeb_RoadPathfinder_::_pathfinder = null

private

A reference to the used AyStar object.

Definition at line 95 of file Pathfinder.Road.nut.

◆ _road_type

_MinchinWeb_RoadPathfinder_::_road_type = null

private

Definition at line 100 of file Pathfinder.Road.nut.

◆ _running

_MinchinWeb_RoadPathfinder_::_running = null

private

Definition at line 103 of file Pathfinder.Road.nut.

◆ cost

_MinchinWeb_RoadPathfinder_::cost = null

private

Used to change the costs.

Definition at line 101 of file Pathfinder.Road.nut.

◆ info

_MinchinWeb_RoadPathfinder_::info = null

private

Definition at line 104 of file Pathfinder.Road.nut.

The documentation for this class was generated from the following file:

Pathfinder.Road.nut

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ _CheckDirection()

◆ _CheckTunnelBridge()

◆ _Cost()

◆ _Estimate()

◆ _GetBridgeNumSlopes()

◆ _GetDirection()

◆ _GetTunnelsBridges()

◆ _IsSlopedRoad()

◆ _Neighbours()

◆ BuildPath()

◆ constructor()

◆ FindPath()

◆ GetBuildCost()

◆ GetPath()

◆ GetPathLength()

◆ InitializePath()

◆ InitializePathOnTowns()

◆ LoadPath()

◆ PathToTilePairs()

◆ PathToTiles()

◆ PresetCheckExisting()

◆ PresetOriginal()

◆ PresetPerfectPath()

◆ PresetQuickAndDirty()

◆ PresetStreetcar()

◆ TilePairsToBuild()

Member Data Documentation

◆ _aystar_class

◆ _cost_bridge_per_tile

◆ _cost_coast

◆ _cost_drivethru_station

◆ _cost_level_crossing

◆ _cost_no_existing_road

◆ _cost_only_existing_roads

◆ _cost_slope

◆ _cost_tile

◆ _cost_tunnel_per_tile

◆ _cost_turn

◆ _distance_penalty

◆ _max_bridge_length

◆ _max_cost

◆ _max_tunnel_length

◆ _my_path

◆ _pathfinder

◆ _road_type

◆ _running

◆ cost

◆ info