![\"License\"](\"https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square\"){kind=icon}
\n ![\"Wally\"](\"https://img.shields.io/badge/📦_Wally-elentium%2Fpathfindingplus-00b4ab?style=flat-square\"){kind=icon}
\n\n
\n A Powerful Pathfinding Library\n
\n\nPathfindingPlus is a powerful PathfindingService wrapper designed for smart pathfinding with intelligent caching and optimization.\n\n## Features\n\n- **Smart Caching**: Caches path computation results and reusable Path objects to minimize redundant calculations\n- **Raycast Optimization**: Automatically checks if a direct path is clear before computing a full path\n- **Performance Oriented**: Designed for games with static maps that require frequent path computations\n- **Simple API**: Single main method (`CalculatePath`) for all pathfinding needs\n- **Automatic Cleanup**: Built-in cache expiration and cleanup system\n\n## Notes\n\n- The library is designed to handle scalable path computations with a single main method (`CalculatePath`)\n- It is optimized for static maps. Due to its caching system, it may not be ideal for dynamic maps with sudden environment changes\n- Best suited for games with static maps that require a lot of path computing\n\n## Installation\n\nAdd PathfindingPlus to your `wally.toml`:\n\n```toml\n[dependencies]\nPathfindingPlus = \"elentium/pathfindingplus@0.0.1\"\n```\n\nThen run `wally install`.\n\n## Usage\n\n```lua\nlocal PathfindingPlus = require(path.to.PathfindingPlus)\n\n-- Basic usage\nlocal success, result = PathfindingPlus.CalculatePath(\n Vector3.new(0, 0, 0), -- Start position\n Vector3.new(100, 0, 100) -- End position\n)\n\nif success then\n if type(result) == \"vector\" then\n -- Direct path is clear, result is the end position\n print(\"Direct path available:\", result)\n else\n -- Path computed, result is an array of PathWaypoints\n for _, waypoint in result do\n print(\"Waypoint:\", waypoint.Position)\n end\n end\nend\n\n-- With agent parameters\nlocal success, waypoints = PathfindingPlus.CalculatePath(\n startPosition,\n endPosition,\n {\n AgentRadius = 2,\n AgentHeight = 5,\n AgentCanJump = true,\n AgentCanClimb = true,\n WaypointSpacing = 4,\n Costs = {\n Water = 10,\n Lava = 20\n }\n }\n)\n\n-- With raycast parameters for optimization\nlocal raycastParams = RaycastParams.new()\nraycastParams.FilterType = Enum.RaycastFilterType.Blacklist\nraycastParams.FilterDescendantsInstances = {character}\n\nlocal success, result = PathfindingPlus.CalculatePath(\n startPosition,\n endPosition,\n nil, -- No agent parameters\n raycastParams\n)\n```\n\n## How the Library Works\n\nPathfindingPlus uses a multi-layered caching system to optimize pathfinding performance:\n\n1. **Operation Cache**: Stores the results of path computations (either direct paths or waypoint arrays) to avoid recalculating identical paths\n2. **Free Path Cache**: Reuses Path objects with the same agent parameters, reducing object creation overhead\n3. **Automatic Cleanup**: Periodically removes expired cache entries based on configurable lifetimes\n4. **Raycast Optimization**: Before computing a full path, checks if a direct raycast is clear, avoiding unnecessary path computations\n\nThe 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.\n\n## API\n\n### `CalculatePath