@esengine/pathfinding 13.2.0 → 13.3.1

package/dist/KDTree-BRpn7O8K.d.ts

@@ -0,0 +1,216 @@
+import { Vector2, IVector2 } from '@esengine/ecs-framework-math';
+import { I as IORCALine, e as IORCASolver, c as IORCASolverConfig, a as IAvoidanceAgent, b as IObstacle, g as ISpatialIndex, f as INeighborResult } from './CollisionResolver-CSgWsegP.js';
+
+/**
+ * @zh 2D 线性规划求解器
+ * @en 2D Linear Programming Solver
+ *
+ * @zh 用于 ORCA 算法中的速度优化求解
+ * @en Used for velocity optimization in ORCA algorithm
+ */
+
+/**
+ * @zh 2D 线性规划
+ * @en 2D Linear Programming
+ *
+ * @zh 在多个半平面约束下找到最优速度
+ * @en Find optimal velocity under multiple half-plane constraints
+ *
+ * @param lines - @zh 约束线列表 @en List of constraint lines
+ * @param radius - @zh 最大速度（圆盘半径）@en Maximum speed (disk radius)
+ * @param optVelocity - @zh 首选速度 @en Preferred velocity
+ * @param directionOpt - @zh 是否优化方向 @en Whether to optimize direction
+ * @param result - @zh 结果向量（输出）@en Result vector (output)
+ * @returns @zh 第一个失败的约束索引，如果成功则返回 lines.length @en Index of first failed constraint, or lines.length if successful
+ */
+declare function linearProgram2(lines: readonly IORCALine[], radius: number, optVelocity: IVector2, directionOpt: boolean, result: Vector2): number;
+/**
+ * @zh 3D 线性规划（回退方案）
+ * @en 3D Linear Programming (fallback)
+ *
+ * @zh 当 2D 线性规划失败时，使用此方法找到最小穿透的速度
+ * @en When 2D LP fails, use this to find velocity with minimum penetration
+ *
+ * @zh 重要：障碍物约束线（前 numObstLines 条）具有最高优先级，绝不会被违反
+ * @en Important: Obstacle constraint lines (first numObstLines) have highest priority and are never violated
+ *
+ * @param lines - @zh 约束线列表 @en List of constraint lines
+ * @param numObstLines - @zh 障碍物约束线数量 @en Number of obstacle constraint lines
+ * @param beginLine - @zh 开始处理的线索引 @en Index of line to start processing
+ * @param radius - @zh 最大速度 @en Maximum speed
+ * @param result - @zh 结果向量（输入/输出）@en Result vector (input/output)
+ */
+declare function linearProgram3(lines: IORCALine[], numObstLines: number, beginLine: number, radius: number, result: Vector2): void;
+/**
+ * @zh ORCA 线性规划求解结果
+ * @en ORCA Linear Programming solve result
+ */
+interface IORCALPResult {
+    /**
+     * @zh 计算得到的速度
+     * @en Computed velocity
+     */
+    velocity: Vector2;
+    /**
+     * @zh 是否找到可行解（满足所有约束）
+     * @en Whether a feasible solution was found (satisfies all constraints)
+     */
+    feasible: boolean;
+    /**
+     * @zh 违反的约束数量
+     * @en Number of violated constraints
+     */
+    violatedConstraints: number;
+}
+/**
+ * @zh 求解 ORCA 线性规划
+ * @en Solve ORCA Linear Programming
+ *
+ * @zh 综合使用 2D 和 3D 线性规划求解最优速度
+ * @en Use both 2D and 3D LP to solve for optimal velocity
+ *
+ * @zh 注意：此函数不包含回退逻辑，调用方应通过返回的 feasible 标志判断是否需要流量控制
+ * @en Note: This function does not include fallback logic, caller should check feasible flag for flow control
+ *
+ * @param lines - @zh ORCA 约束线列表 @en List of ORCA constraint lines
+ * @param numObstLines - @zh 障碍物约束线数量 @en Number of obstacle lines
+ * @param maxSpeed - @zh 最大速度 @en Maximum speed
+ * @param preferredVelocity - @zh 首选速度 @en Preferred velocity
+ * @returns @zh 求解结果，包含速度和可行性标志 @en Solve result with velocity and feasibility flag
+ */
+declare function solveORCALinearProgram(lines: IORCALine[], numObstLines: number, maxSpeed: number, preferredVelocity: IVector2): IORCALPResult;
+
+/**
+ * @zh ORCA 避让算法求解器
+ * @en ORCA Avoidance Algorithm Solver
+ *
+ * @zh 实现最优互惠碰撞避免（ORCA）算法，用于多代理局部避让
+ * @en Implements Optimal Reciprocal Collision Avoidance (ORCA) algorithm for multi-agent local avoidance
+ */
+
+/**
+ * @zh ORCA 求解器实现
+ * @en ORCA Solver implementation
+ *
+ * @zh 实现最优互惠碰撞避免算法，计算代理的安全速度
+ * @en Implements Optimal Reciprocal Collision Avoidance algorithm to compute safe velocities for agents
+ */
+declare class ORCASolver implements IORCASolver {
+    private readonly config;
+    constructor(config?: IORCASolverConfig);
+    /**
+     * @zh 计算代理的新速度
+     * @en Compute new velocity for agent
+     *
+     * @param agent - @zh 当前代理 @en Current agent
+     * @param neighbors - @zh 邻近代理列表 @en List of neighboring agents
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 计算得到的新速度 @en Computed new velocity
+     */
+    computeNewVelocity(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IVector2;
+    /**
+     * @zh 计算代理的新速度（带完整结果）
+     * @en Compute new velocity for agent (with full result)
+     *
+     * @param agent - @zh 当前代理 @en Current agent
+     * @param neighbors - @zh 邻近代理列表 @en List of neighboring agents
+     * @param obstacles - @zh 障碍物列表 @en List of obstacles
+     * @param deltaTime - @zh 时间步长 @en Time step
+     * @returns @zh 完整求解结果 @en Full solve result
+     */
+    computeNewVelocityWithResult(agent: IAvoidanceAgent, neighbors: readonly IAvoidanceAgent[], obstacles: readonly IObstacle[], deltaTime: number): IORCALPResult & {
+        numLines: number;
+    };
+    /**
+     * @zh 创建代理间的 ORCA 约束线
+     * @en Create ORCA constraint lines for agent-agent avoidance
+     */
+    private createAgentORCALines;
+    /**
+     * @zh 创建障碍物的 ORCA 约束线
+     * @en Create ORCA constraint lines for obstacle avoidance
+     */
+    private createObstacleORCALines;
+}
+/**
+ * @zh 创建 ORCA 求解器
+ * @en Create ORCA solver
+ *
+ * @param config - @zh 可选配置参数 @en Optional configuration parameters
+ * @returns @zh ORCA 求解器实例 @en ORCA solver instance
+ */
+declare function createORCASolver(config?: IORCASolverConfig): ORCASolver;
+
+/**
+ * @zh KD-Tree 空间索引
+ * @en KD-Tree Spatial Index
+ *
+ * @zh 用于快速查询指定范围内的邻近代理
+ * @en Used for fast neighbor queries within specified range
+ */
+
+/**
+ * @zh KD-Tree 空间索引
+ * @en KD-Tree spatial index
+ *
+ * @zh 每帧重建，支持高效的范围查询
+ * @en Rebuilt every frame, supports efficient range queries
+ */
+declare class KDTree implements ISpatialIndex {
+    private agents;
+    private agentIndices;
+    private nodes;
+    /**
+     * @zh 最大叶节点大小
+     * @en Maximum leaf size
+     */
+    private readonly maxLeafSize;
+    /**
+     * @zh 构建 KD-Tree
+     * @en Build KD-Tree
+     */
+    build(agents: readonly IAvoidanceAgent[]): void;
+    /**
+     * @zh 递归构建 KD-Tree
+     * @en Recursively build KD-Tree
+     */
+    private buildRecursive;
+    /**
+     * @zh 按 X 坐标排序
+     * @en Sort by X coordinate
+     */
+    private sortByX;
+    /**
+     * @zh 按 Y 坐标排序
+     * @en Sort by Y coordinate
+     */
+    private sortByY;
+    /**
+     * @zh 查询邻居
+     * @en Query neighbors
+     */
+    queryNeighbors(position: IVector2, radius: number, maxResults: number, excludeId?: number): INeighborResult[];
+    /**
+     * @zh 递归查询
+     * @en Recursive query
+     */
+    private queryRecursive;
+    /**
+     * @zh 清空索引
+     * @en Clear the index
+     */
+    clear(): void;
+    /**
+     * @zh 获取代理数量
+     * @en Get agent count
+     */
+    get agentCount(): number;
+}
+/**
+ * @zh 创建 KD-Tree
+ * @en Create KD-Tree
+ */
+declare function createKDTree(): KDTree;
+
+export { KDTree as K, ORCASolver as O, createKDTree as a, linearProgram3 as b, createORCASolver as c, linearProgram2 as l, solveORCALinearProgram as s };

package/dist/avoidance.d.ts

@@ -1,6 +1,6 @@
-import { k as IObstacleVertex, b as IObstacle } from './KDTree-2rs2EXvm.js';
-export { h as DEFAULT_AGENT_PARAMS, D as DEFAULT_ORCA_CONFIG, a as IAvoidanceAgent, f as INeighborResult, I as IORCALine, d as IORCAResult, e as IORCASolver, c as IORCASolverConfig, g as ISpatialIndex, K as KDTree, O as ORCASolver, j as createKDTree, i as createORCASolver } from './KDTree-2rs2EXvm.js';
-export { l as linearProgram2, a as linearProgram3, s as solveORCALinearProgram } from './LinearProgram-DyD3pI6v.js';
+import { m as IObstacleVertex, b as IObstacle } from './CollisionResolver-CSgWsegP.js';
+export { C as CollisionResolver, j as DEFAULT_AGENT_PARAMS, k as DEFAULT_COLLISION_CONFIG, D as DEFAULT_ORCA_CONFIG, E as EMPTY_COLLISION, a as IAvoidanceAgent, i as ICollisionResolverConfig, h as ICollisionResult, f as INeighborResult, I as IORCALine, d as IORCAResult, e as IORCASolver, c as IORCASolverConfig, g as ISpatialIndex, l as createCollisionResolver } from './CollisionResolver-CSgWsegP.js';
+export { K as KDTree, O as ORCASolver, a as createKDTree, c as createORCASolver, l as linearProgram2, b as linearProgram3, s as solveORCALinearProgram } from './KDTree-BRpn7O8K.js';
 import { IVector2 } from '@esengine/ecs-framework-math';
 export { IVector2 } from '@esengine/ecs-framework-math';
 
@@ -17,11 +17,33 @@ export { IVector2 } from '@esengine/ecs-framework-math';
  * @param startId - @zh 起始顶点 ID @en Starting vertex ID
  */
 declare function createObstacleVertices(vertices: readonly IVector2[], startId?: number): IObstacleVertex[];
+/**
+ * @zh 构建障碍物顶点的选项
+ * @en Options for building obstacle vertices
+ */
+interface IBuildObstacleOptions {
+    /**
+     * @zh 是否使用 Y 轴向下的坐标系（如 Canvas/屏幕坐标）
+     * @en Whether using Y-axis down coordinate system (like Canvas/screen coords)
+     *
+     * @zh 这会影响障碍物顶点顺序的判断
+     * @en This affects obstacle vertex order detection
+     *
+     * @default false
+     */
+    yAxisDown?: boolean;
+}
 /**
  * @zh 从障碍物数组创建所有障碍物顶点
  * @en Create all obstacle vertices from obstacle array
+ *
+ * @zh 自动检测并纠正顶点顺序为 CCW（逆时针）
+ * @en Automatically detects and corrects vertex order to CCW (counter-clockwise)
+ *
+ * @param obstacles - @zh 障碍物数组 @en Array of obstacles
+ * @param options - @zh 构建选项 @en Build options
  */
-declare function buildObstacleVertices(obstacles: readonly IObstacle[]): IObstacleVertex[];
+declare function buildObstacleVertices(obstacles: readonly IObstacle[], options?: IBuildObstacleOptions): IObstacleVertex[];
 /**
  * @zh 确保顶点按逆时针顺序排列
  * @en Ensure vertices are in counter-clockwise order

package/dist/avoidance.js

@@ -1,10 +1,14 @@
-import "./chunk-KEYTX37K.js";
+import "./chunk-H5EFZBBT.js";
 import {
+  CollisionResolver,
   DEFAULT_AGENT_PARAMS,
+  DEFAULT_COLLISION_CONFIG,
   DEFAULT_ORCA_CONFIG,
+  EMPTY_COLLISION,
   KDTree,
   ORCASolver,
   buildObstacleVertices,
+  createCollisionResolver,
   createKDTree,
   createORCASolver,
   createObstacleVertices,
@@ -12,14 +16,18 @@ import {
   linearProgram2,
   linearProgram3,
   solveORCALinearProgram
-} from "./chunk-JTZP55BJ.js";
+} from "./chunk-3VEX32JO.js";
 import "./chunk-T626JPC7.js";
 export {
+  CollisionResolver,
   DEFAULT_AGENT_PARAMS,
+  DEFAULT_COLLISION_CONFIG,
   DEFAULT_ORCA_CONFIG,
+  EMPTY_COLLISION,
   KDTree,
   ORCASolver,
   buildObstacleVertices,
+  createCollisionResolver,
   createKDTree,
   createORCASolver,
   createObstacleVertices,