graphpath Reference

Module defined in lua/common/graphpath.lua. Graph-based pathfinding library implementing Dijkstra's algorithm with extensions for road networks - supports edge properties (drivability, speed limits, lanes, one-way), point-to-point paths, chase/flee AI behaviors, and traffic flow analysis.

---

Exports

Global Functions

newGraphpath()

Creates a new empty graph instance.

• Returns: Graphpath - Graph object

Instance Methods - Graph Construction

graph:edge(sp, ep, dist)

Adds a bidirectional edge with a simple distance cost.

• Parameters:
  • sp - string|number - Start node ID
  • ep - string|number - End node ID
  • dist - number - Edge distance/cost

graph:uniEdge(inNode, outNode, dist, drivability, speedLimit, lanes, oneWay, gated, inPos, inRad, outPos, outRad)

Adds a unidirectional road edge with full road properties.

• Parameters:
  • inNode, outNode - any - Node IDs
  • dist - number - Edge distance
  • drivability - number - Drivability score (0-1)
  • speedLimit - number - Speed limit
  • lanes - string - Lane encoding string
  • oneWay - boolean - One-way flag
  • gated - boolean - Gated/blocked flag
  • inPos, outPos - vec3 - Node positions
  • inRad, outRad - number - Node radii

graph:bidiEdge(inNode, outNode, dist, drivability, speedLimit, lanes, oneWay, gated, inPos, inRad, outPos, outRad) - Same params as uniEdge, adds edges in both directions.

graph:clear() - Clears all nodes and edges.

Instance Methods - Pathfinding

graph:getPath(start, goal, dirMult)

Finds shortest path between two nodes using Dijkstra's algorithm.

• Parameters:
  • start - any - Start node ID
  • goal - any - Goal node ID
  • dirMult - number|nil - Direction multiplier for one-way penalty
• Returns: table - Array of node IDs from start to goal

graph:getFilteredPath(start, goal, cutOffDrivability, dirMult, penaltyAboveCutoff, penaltyBelowCutoff)

Pathfinding with drivability filtering - applies penalties based on road quality.

• Returns: table - Path as array of node IDs

graph:getPointNodePath(start, target, cutOffDrivability, dirMult, penaltyAboveCutoff, penaltyBelowCutoff, wZ)

Finds path from a start node to a target node with drivability and height penalties.

• Returns: table - Path

graph:getPointToPointPath(sourcePos, iter, targetPos, cutOffDrivability, dirMult, penaltyAboveCutoff, penaltyBelowCutoff, wZ)

Finds path between two arbitrary 3D positions (snaps to nearest graph nodes).

• Parameters:
  • sourcePos - vec3 - Start position
  • iter - function - Iterator over candidate start nodes
  • targetPos - vec3 - Target position
• Returns: table - Path

graph:getEdgePath(bNode, fNode, goal, dirMult)

Finds path from an edge (between bNode and fNode) to a goal node.

• Returns: table - Path

graph:getPathT(start, mePos, pathLenLim, illegalDirPenalty, initDir)

Finds a path with traffic-aware traversal, preferring legal driving directions.

• Returns: table - Path

graph:getPathTWithState(start, mePos, pathLenLim, state)

Extended traffic-aware pathfinding preserving traversal state between calls.

• Returns: table - Path

Instance Methods - AI Behaviors

graph:getChasePath(nodeBehind, nodeAhead, targetNodeBehind, targetNodeAhead, mePos, meVel, targetPos, targetVel, dirMult)

Computes a path for an AI vehicle to chase a target vehicle.

• Returns: table - Chase path

graph:getFleePath(startNode, initialDir, chasePos, pathLenLimit, rndDirCoef, rndDistCoef)

Computes a path for fleeing from a pursuer.

• Returns: table - Flee path

graph:getRandomPath(nodeAhead, nodeBehind, dirMult)

Generates a random path from the current position.

• Returns: table - Random path

graph:getRandomPathG(startNode, initialDir, pathLenLimit, rndDirCoef, rndDistCoef, oneway)

Generates a random path with configurable randomness and length.

• Returns: table - Random path

graph:getPathAwayFrom(start, goal, mePos, stayAwayPos, dirMult)

Finds a path that avoids a specific position.

• Returns: table - Avoidance path

Instance Methods - Graph Analysis

graph:spanMap(source, nodeBehind, target, edgeDict, dirMult)

Builds a distance map from source spanning the graph.

• Returns: table - Distance/path map

graph:getMaxNodeAround(start, radius, dir)

Finds the farthest reachable node within a radius.

• Returns: any, number - Node ID and distance

graph:getBranchNodesAround(start, maxRadius)

Finds all branch/intersection nodes within a radius.

• Returns: table - Array of branch node IDs

graph:getFlows(inNode, outNode)

Computes traffic flow probabilities for an edge.

• Returns: table - Flow data

graph:graphMinor()

Simplifies the graph by removing degree-2 nodes (merging consecutive edges).

Instance Methods - Utility

graph:getEdgePositions(n1id, n2id) → vec3, vec3

graph:getEdgeRadii(n1id, n2id) → number, number

graph:setPointPosition(p, pos) / graph:setPointPositionRadius(p, pos, radius)

graph:setNodeRadius(node, radius)

graph:edgeLanesInDirection(fromNode, toNode) → number

graph:numOfEdgeLanes(inNode, outNode) → number

graph:export(edgeCount) → table

graph:import(graphData)

MinHeap (Internal Priority Queue)

Used internally for Dijkstra/A* pathfinding.

newMinheap()

Creates a new min-heap instance.

• Returns: table - A new MinHeap object with insert, pop, peekKey, peekValue, and size methods.

insert(key, value)

Inserts a key-value pair into the heap.

pop()

Removes and returns the minimum key-value pair.

peekKey()

Returns the minimum key without removing it.

peekVal()

Returns the value associated with the minimum key without removing it.

empty()

Returns true if the heap is empty.

Internal Notes

• Uses a custom min-heap priority queue for Dijkstra's algorithm
• Graph stored as adjacency lists: graph[nodeId][neighborId] = {dist, drivability, speedLimit, ...}
• Node data: positions[nodeId] = vec3, radius[nodeId] = number
• Lane encoding: string of characters where each char represents a lane direction
• The getPathT family of functions implements traffic-aware traversal for AI driving
• Path results are arrays of node IDs; empty table {} indicates no path found

Additional Exports