# three-pathfinding-3d

**Repository Path**: yjsdszz/three-pathfinding-3d

## Basic Information

- **Project Name**: three-pathfinding-3d
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 21
- **Forks**: 2
- **Created**: 2025-08-18
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# three-pathfinding-3d

> 基于 [three-pathfinding](https://github.com/agentile/three-pathfinding) 优化的 3D 导航网格路径查找库，专为 Three.js 场景设计。

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
  <img src="https://img.shields.io/badge/version-1.0.9-brightgreen" alt="Version">
  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p>

## 📌 项目背景

原库 [three-pathfinding](https://github.com/agentile/three-pathfinding) 目前已停止维护，社区提交的 Pull Request 长期未被合并。  
为此，我们 fork 并重构了该项目，修复了多个关键问题，提升其在 **3D 复杂场景** 中的稳定性和准确性。

📧 联系作者：[526838933@qq.com](mailto:526838933@qq.com)

---

## 🔧 主要修复与优化

本项目基于原始库代码进行了深度改进，解决了以下核心问题：

1. **修复 funnel 算法缺失首通道的问题**  
   原算法遗漏第一个通道顶点，导致最终路径偏移甚至错误，现已修正。

2. **针对 3D 场景优化 funnel 算法**  
   原始实现仅适用于 2D 投影，在高度变化明显的 3D 场景中路径偏差严重。现通过三维空间计算优化通道处理逻辑，显著提升路径真实感和可用性。

3. **修正左右通道定义错误**  
   原算法中左右通道判断逻辑颠倒，造成路径扭曲。已重新校准左右边界判定规则，确保 funnel 正确收缩。

---

## 🚀 未来规划

- ✅ 已完成：Funnel 算法三维化与逻辑修复  
- ⏳ 开发中：新增 `BufferPolygon` 模块，支持高效多边形数据管理  
- 🔜 计划中：支持 NavMesh 数据结构整体导出，无需每次运行时重建，提升性能与加载速度

---

## 💾 安装方式

使用 npm 安装：

```bash
npm install three-pathfinding-3d
```
在项目中引入：
```
import { Pathfinding, PathfindingHelper } from 'three-pathfinding-3d';
```
🔍 快速开始（本地演示）
克隆仓库并启动示例项目：
```
git clone https://gitee.com/yjsdszz/three-pathfinding-3d
pnpm i 
pnpm run demo
```

示例包含一个简单的 Three.js 场景，展示角色在导航网格上的自动寻路过程。

🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
如果你发现 bug 或有功能建议，请随时联系我们或发起 PR。

📄 许可证
本项目基于 MIT License 开源，自由使用，欢迎二次开发。