{"id":"metricrb/parallel-path","name":"parallel-path","scope":"metricrb","platform":"roblox","description":"Parallel Luau pathfinding for humanoids, vehicles, and custom rigs","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"f98b106ff07ce7b59750fb56db15c78ce6494df4eb36348fcf8c013df39576ee","likes":0,"downloads":0,"install":"forest install metricrb/parallel-path","url":"https://forest.dev/p/roblox/metricrb/parallel-path","files":"https://api.forest.dev/ai/package/roblox/metricrb/parallel-path/files","readme":"# parallel-path\n\n> Parallel Luau pathfinding for humanoids, vehicles, and custom rigs — no MoveToFinished stutter.\n\n[![CI](https://github.com/metricrb/parallel-path/actions/workflows/ci.yml/badge.svg)](https://github.com/metricrb/parallel-path/actions/workflows/ci.yml)\n[![Build Documentation](https://github.com/metricrb/parallel-path/actions/workflows/build-docs.yml/badge.svg)](https://metricrb.github.io/parallel-path/)\n[![Wally Package](https://img.shields.io/badge/wally-metricrb%2Fparallel--path-blue)](https://wally.run/package/metricrb/parallel-path)\n\n## Why parallel-path?\n\nSimplePath is great, but has one critical flaw: **MoveToFinished event causes visible stuttering** when humanoids reach waypoints. The event fires on the server after the client has already moved past the waypoint, creating noticeable jitter.\n\n**parallel-path solves this** by replacing MoveToFinished with a **Heartbeat distance-polling loop**, borrowed from Roblox's ClickToMove controller logic. This eliminates stutter entirely.\n\nBeyond that, parallel-path offers:\n\n- **Parallel path computation** via Actors + Parallel Luau. Compute multiple paths at once without blocking gameplay.\n- **Multi-mode steering**: Humanoid rigs, vehicles with PID steering, or completely custom controllers.\n- **Robust failsafes**: Automatic recomputation on block, stuck detection with recovery, fallback to direct movement.\n- **No external dependencies**: Signal and Promise are bundled.\n- **Comprehensive documentation**: Full API reference, guides, and examples.\n\n## Quick start\n\n### Installation\n\nAdd to your `wally.toml`:\n\n```toml\n[dependencies]\nParallelPath = \"metricrb/parallel-path@0.1\"\n```\n\nRun `wally install`.\n\n### Basic usage\n\n```luau\nlocal parallel_path = require(game:GetService(\"ReplicatedStorage\").Packages.ParallelPath)\nlocal Agent = parallel_path.Agent\nlocal Scheduler = parallel_path.Scheduler\n\n-- Initialize once at game startup\nScheduler.init(4)\n\n-- Create an agent for a humanoid NPC\nlocal agent = Agent.new(workspace.MyNPC, {\n    steeringMode = \"Humanoid\",\n})\n\n-- Move to target\nagent:MoveTo(workspace.Target.Position)\n\n-- Handle events\nagent.Reached:Connect(function(model, waypoint)\n    print(\"Reached target!\")\nend)\n\nagent.Failed:Connect(function(model, reason)\n    print(\"Movement failed:\", reason)\nend)\n```\n\nSee [Getting Started](https://metricrb.github.io/parallel-path/getting-started.html) for more.\n\n## Features\n\n### Heartbeat distance-polling\n\nNo more MoveToFinished stutter. The Agent reads the model's position every frame and compares it to the target waypoint distance. When close enough, the next waypoint is queued instantly.\n\n### Parallel path computation\n\nPath requests run in Actor-isolated Parallel Luau, never blocking the main thread. Submit multiple paths at once — they compute in parallel.\n\n### Multi-mode steering\n\n| Mode | Use case |\n|------|----------|\n| **Humanoid** | NPCs, monsters, animated characters |\n| **Vehicle** | Cars, tanks, with PID-controlled steering |\n| **Custom** | AnimationControllers, TweenService, BodyVelocity, physics rigs |\n\n### Built-in stuck detection\n\nIf an agent doesn't move for 3 seconds, it automatically attempts a recovery jump (humanoids) or fires the `Stuck` signal. Configurable timeout and recovery strategy.\n\n### Failsafe hierarchy\n\nWhen pathfinding fails:\n1. Automatically recompute (up to maxRetries)\n2. Attempt partial path to nearest reachable node\n3. Optionally fall back to direct steering\n4. Fire `Failed` signal with detailed reason code\n\n## Documentation\n\n- **[API Reference](https://metricrb.github.io/parallel-path/api-reference.html)** — All methods, signals, and types\n- **[Getting Started](https://metricrb.github.io/parallel-path/getting-started.html)** — Step-by-step walkthrough\n- **[Guides](https://metricrb.github.io/parallel-path/guides/)** — Vehicle steering, parallel computation, failsafes, migration from SimplePath\n- **[Examples](https://metricrb.github.io/parallel-path/examples/)** — Humanoid NPC, AI car, custom rig with BodyVelocity\n\n## Project structure\n\n```\nparallel-path/\n├── src/\n│   ├── init.luau                    -- Main export point\n│   ├── Agent.luau                   -- Core movement controller\n│   ├── Scheduler.luau               -- Actor pool manager\n│   ├── WorkerScript.server.luau     -- Runs inside each Actor\n│   ├── GridBuilder.luau             -- Optional walkability grid\n│   ├── Signal.luau                  -- Lightweight Signal (no BindableEvents)\n│   ├── Promise.luau                 -- Minimal Promise implementation\n│   ├── Types.luau                   -- Type definitions\n│   └── Steering/\n│       ├── HumanoidSteering.luau    -- Humanoid:MoveTo() wrapper\n│       ├── VehicleSteering.luau     -- PID-controlled vehicle steering\n│       └── CustomSteering.luau      -- User-supplied callback\n├── tests/\n│   ├── Agent.spec.luau\n│   ├── Scheduler.spec.luau\n│   └── Steering.spec.luau\n├── docs/\n│   ├── index.md                     -- Overview\n│   ├── getting-started.md           -- Quick start\n│   ├── api-reference.md             -- Full API\n│   ├── guides/\n│   │   ├── vehicle-steering.md\n│   │   ├── parallel-computation.md\n│   │   ├── failsafe-hierarchy.md\n│   │   └── migrating-from-simplepath.md\n│   └── examples/\n│       ├── humanoid-npc.luau\n│       ├── ai-car.luau\n│       └── custom-rig.luau\n├── wally.toml\n├── default.project.json\n├── .luaurc\n└── selene.toml\n```\n\n## Performance\n\n- **Humanoid NPCs**: 2–3x smoother due to Heartbeat polling (no MoveToFinished stutter)\n- **Many agents (10+)**: 5–10x faster with parallel computation\n- **Vehicles**: New capability, significantly faster than humanoid pathfinding\n- **Memory**: Slightly higher (Actor overhead), negligible for most games\n\n## Comparison with SimplePath\n\n| Feature | SimplePath | parallel-path |\n|---------|-----------|----------------|\n| Humanoid pathfinding | ✓ | ✓ |\n| No MoveToFinished stutter | ✗ | ✓ |\n| Parallel path computation | ✗ | ✓ |\n| Vehicle steering | ✗ | ✓ |\n| Custom steering callbacks | ✗ | ✓ |\n| Stuck detection | ✗ | ✓ |\n| Pause/resume | ✗ | ✓ |\n| Recompute on block | ✓ | ✓ |\n| Error signals | ✓ | ✓ (more detailed) |\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes (`git commit -am 'Add feature'`)\n4. Push to the branch (`git push origin feature/my-feature`)\n5. Open a Pull Request\n\n## Testing\n\nRun tests with:\n\n```bash\nwally install\nrojo test\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE) for details.\n\n## Acknowledgments\n\n- Inspired by Roblox's ClickToMove controller for the Heartbeat polling approach\n- Built with Luau strict mode for safety and type checking\n- Designed for production games with performance in mind\n\n---\n\n**Questions?** Check the [documentation](https://metricrb.github.io/parallel-path/) or open an issue on GitHub.\n","readmeTruncated":false}