PathfindingPlus

A Powerful Pathfinding Library

PathfindingPlus is a powerful PathfindingService wrapper designed for smart pathfinding with intelligent caching and optimization.

Features

• Smart Caching: Caches path computation results and reusable Path objects to minimize redundant calculations
• Raycast Optimization: Automatically checks if a direct path is clear before computing a full path
• Performance Oriented: Designed for games with static maps that require frequent path computations
• Simple API: Single main method (CalculatePath) for all pathfinding needs
• Automatic Cleanup: Built-in cache expiration and cleanup system

Notes

• The library is designed to handle scalable path computations with a single main method (CalculatePath)
• It is optimized for static maps. Due to its caching system, it may not be ideal for dynamic maps with sudden environment changes
• Best suited for games with static maps that require a lot of path computing

Installation

Add PathfindingPlus to your wally.toml:

[dependencies]
PathfindingPlus = "elentium/pathfindingplus@0.0.1"

Then run wally install.

Usage

local PathfindingPlus = require(path.to.PathfindingPlus)

-- Basic usage
local success, result = PathfindingPlus.CalculatePath(
    Vector3.new(0, 0, 0),  -- Start position
    Vector3.new(100, 0, 100)  -- End position
)

if success then
    if type(result) == "vector" then
        -- Direct path is clear, result is the end position
        print("Direct path available:", result)
    else
        -- Path computed, result is an array of PathWaypoints
        for _, waypoint in result do
            print("Waypoint:", waypoint.Position)
        end
    end
end

-- With agent parameters
local success, waypoints = PathfindingPlus.CalculatePath(
    startPosition,
    endPosition,
    {
        AgentRadius = 2,
        AgentHeight = 5,
        AgentCanJump = true,
        AgentCanClimb = true,
        WaypointSpacing = 4,
        Costs = {
            Water = 10,
            Lava = 20
        }
    }
)

-- With raycast parameters for optimization
local raycastParams = RaycastParams.new()
raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
raycastParams.FilterDescendantsInstances = {character}

local success, result = PathfindingPlus.CalculatePath(
    startPosition,
    endPosition,
    nil,  -- No agent parameters
    raycastParams
)

How the Library Works

PathfindingPlus uses a multi-layered caching system to optimize pathfinding performance:

1. Operation Cache: Stores the results of path computations (either direct paths or waypoint arrays) to avoid recalculating identical paths
2. Free Path Cache: Reuses Path objects with the same agent parameters, reducing object creation overhead
3. Automatic Cleanup: Periodically removes expired cache entries based on configurable lifetimes
4. Raycast Optimization: Before computing a full path, checks if a direct raycast is clear, avoiding unnecessary path computations

The library is designed to handle high-frequency pathfinding requests efficiently, making it ideal for games with many NPCs or agents that need to navigate static environments.

API

CalculatePath<T>(Start, End, AgentParameters?, Params?) -> (boolean, (T | {PathWaypoint})?)

Calculates a path between two points using a three-step optimization process:

1. Cache Check: Checks if the operation result is already cached. If found, returns the cached result immediately
2. Raycast Check: Attempts to raycast in the direction to check if the path is clear. If clear, returns the end position directly
3. Path Computation: If the path is not clear, acquires a Path object (from cache if available), computes the path, caches the result, and returns the waypoints

Parameters:

• Start: Vector3 | vector - The start position of the path
• End: Vector3 | vector - The end position of the path
• AgentParameters: AgentParameters? - Optional agent parameters (AgentRadius, AgentHeight, AgentCanJump, AgentCanClimb, WaypointSpacing, Costs)
• Params: RaycastParams? - Optional raycast parameters for the direct path check

Returns:

• boolean - Whether the path calculation was successful
• ((vector | Vector3) | {PathWaypoint})? - The result: either the end position (if direct path is clear) or an array of PathWaypoints

ClearOperationsCache() -> ()

Clears the operations cache, removing all cached path computation results.

ClearFreePathsCache() -> ()

Clears the free paths cache, removing all cached Path objects.

Configuration

The library uses the following default constants (defined in the source code):

• MAX_OPERATIONS_CACHE_COUNT: 100 - Maximum number of cached path results
• MAX_FREE_PATHS_COUNT: 50 - Maximum number of cached Path objects
• OPERATION_CACHE_LIFETIME: 30 seconds - How long operation results are cached
• FREE_PATH_LIFETIME: 30 seconds - How long Path objects are cached
• CACHE_CLEANUP_INTERVAL: 5 seconds - How often cache cleanup runs

These can be modified in the source code if needed for your specific use case.